Simple test

Ensure your device works with this simple test.

examples/qwiicrelay_simpletest.py
 1# SPDX-FileCopyrightText: Copyright (c) 2019-2021 Gaston Williams
 2#
 3# SPDX-License-Identifier: Unlicense
 4
 5#  This is example is for the SparkFun Qwiic Relay.
 6#  SparkFun sells these at its website: www.sparkfun.com
 7#  Do you like this library? Help support SparkFun. Buy a board!
 8#  https://www.sparkfun.com/products/15168
 9
10"""
11 Qwiic Relay Simple Test - qwiicrelay_simpletest.py
12 Written by Gaston Williams, June 17th, 2019
13 The Qwiic Single Relay is a I2C controlled relay
14
15 Simple Test:
16 This program uses the Qwiic Relay CircuitPython Library to toggle
17 that status of the Qwiic Single Relay.
18"""
19import sys
20from time import sleep
21import board
22import sparkfun_qwiicrelay
23
24# Create bus object using our board's I2C port
25i2c = board.I2C()
26
27# Create joystick object
28relay = sparkfun_qwiicrelay.Sparkfun_QwiicRelay(i2c)
29
30# Check if connected
31if relay.connected:
32    print("Relay connected.")
33else:
34    print("Relay does not appear to be connected. Please check wiring.")
35    sys.exit()
36
37# Print firmware version and current status
38print("Firmware version " + relay.version)
39print("Relay status ", relay.status)
40
41# Turn the relay on and off
42print("Press Ctrl-C to exit program")
43while True:
44    relay.relay_on()
45    print("Relay status ", relay.status)
46    sleep(2)
47    relay.relay_off()
48    print("Relay status ", relay.status)
49    sleep(2)

Examples

  1. Basic Control - Turn the relay on and off.

examples/example1_basic_control.py
 1# SPDX-FileCopyrightText: Copyright (c) 2019-2021 Gaston Williams
 2#
 3# SPDX-License-Identifier: Unlicense
 4
 5#  This is example is for the SparkFun Qwiic Single Relay.
 6#  SparkFun sells these at its website: www.sparkfun.com
 7#  Do you like this library? Help support SparkFun. Buy a board!
 8#  https://www.sparkfun.com/products/15093
 9
10"""
11 Qwiic Relay Example 1 - example1_basic_control.py
12 Written by Gaston Williams, June 13th, 2019
13 Based on Arduino code written by
14 Kevin Kuwata @ SparkX, March 21, 2018
15 The Qwiic Single Relay is an I2C controlled relay produced by sparkfun
16
17 Example 1 - Basic Control:
18 This program uses the Qwiic Relay CircuitPython Library to
19 control the Qwiic Relay breakout over I2C and demonstrate
20 basic functionality.
21"""
22import sys
23from time import sleep
24import board
25import sparkfun_qwiicrelay
26
27# Create bus object using our board's I2C port
28i2c = board.I2C()
29
30# Create relay object
31relay = sparkfun_qwiicrelay.Sparkfun_QwiicRelay(i2c)
32
33print("Qwicc Relay Example 1 Basic Control")
34
35# Check if connected
36if relay.connected:
37    print("Relay connected.")
38else:
39    print("Relay does not appear to be connected. Please check wiring.")
40    sys.exit()
41
42print("Type Ctrl-C to exit program.")
43
44try:
45    while True:
46        relay.relay_on()
47        sleep(2)
48        relay.relay_off()
49        sleep(2)
50
51except KeyboardInterrupt:
52    pass

  1. Change I2C Address - Change the device I2C address.

example2_change_i2c_address.py
 1# SPDX-FileCopyrightText: Copyright (c) 2019-2021 Gaston Williams
 2#
 3# SPDX-License-Identifier: Unlicense
 4
 5#  This is example is for the SparkFun Qwiic Single Relay.
 6#  SparkFun sells these at its website: www.sparkfun.com
 7#  Do you like this library? Help support SparkFun. Buy a board!
 8#  https://www.sparkfun.com/products/15093
 9
10"""
11  Qwiic Relay Example 2 - example2_change_i2c_address.py
12  Written by Gaston Williams, June 19th, 2019
13  Based on Arduino code written by
14  Kevin Kuwata @ SparkX, March 21, 2019
15  The Qwiic Single Relay is a I2C controlled relay
16
17  Example 2 - Change I2C Address:
18  This program uses the Qwiic Relay CircuitPython Library to change
19  the I2C address for the device. You enter in the DEC value (8-119) or
20  HEX value (0x08-0x77) for the new Relay address.  After the i2c address
21  is changed, you can run the example3_i2c_scanner.py program to validate
22  the i2c address.
23
24  Syntax: python3 change_i2c_address.py [address]
25    where address is an optional current address value in decimal or hex
26
27    The default value for the address is 24 [0x18]
28"""
29
30import sys
31import board
32import sparkfun_qwiicrelay
33
34# The default QwiicRelay i2c address is 0x18 (24)
35i2c_address = 0x18
36
37# print('Arguement count: ' , len(sys.argv))
38# print('List: ' + str(sys.argv))
39
40# If we were passed an arguement, then use it as the address
41if len(sys.argv) > 1:
42    try:
43        # check to see if hex or decimal arguement
44        if "0x" in sys.argv[1]:
45            i2c_address = int(sys.argv[1], 16)
46        else:
47            i2c_address = int(sys.argv[1])
48    except ValueError:
49        print("Ignoring invalid arguement: " + str(sys.argv[1]))
50
51# Show the initial address
52print("Current i2c address = " + str(i2c_address) + " [" + hex(i2c_address) + "]")
53
54# Create busio object using our Board I2C port
55i2c = board.I2C()
56relay = sparkfun_qwiicrelay.Sparkfun_QwiicRelay(i2c, i2c_address)
57
58if relay.connected:
59    print("Qwiic Relay Example.")
60else:
61    # if we can't connecct, something is wrong so just quit
62    print("Relay does not appear to be connected. Please check wiring.")
63    sys.exit()
64
65print("Address: " + str(i2c_address) + " [" + hex(i2c_address) + "]")
66
67text = input(
68    "Enter a new I2C address (as a decimal from 8 to 119 or hex 0x08 to 0x77):"
69)
70
71# check to see if hex or decimal value
72if "0x" in text:
73    new_address = int(text, 16)
74else:
75    new_address = int(text)
76
77print("Changing address to " + str(new_address) + " [" + hex(new_address) + "]")
78
79result = relay.set_i2c_address(new_address)
80
81if result:
82    print("Address changed to " + str(new_address) + " [" + hex(new_address) + "]")
83    # After the change check the new connection and show firmware version
84    if relay.connected:
85        print("Connected to Relay after address change.")
86    else:
87        print("Error after address change. Cannot connect to Relay.")
88
89else:
90    print("Address change failed.")
91
92# good advice whether the address changed worked or not
93print("Run example3_i2c_scanner.py to verify the Qwiic Relay address.")

  1. I2C Scanner - Scan the IC2 bus for devices.

example3_i2c_scanner.py
 1# SPDX-FileCopyrightText: Copyright (c) 2019-2021 Gaston Williams
 2#
 3# SPDX-License-Identifier: Unlicense
 4
 5#  This is example is for the SparkFun Qwiic Single Relay.
 6#  SparkFun sells these at its website: www.sparkfun.com
 7#  Do you like this library? Help support SparkFun. Buy a board!
 8#  https://www.sparkfun.com/products/15093
 9
10"""
11  Qwiic Relay Example 3 - example3_i2c_Scanner.py
12  Written by Gaston Williams, June 17th, 2019
13  The Qwiic Single Relay is an I2C controlled relay produced by sparkfun
14
15  Example 3 - I2C Scanner
16  This progam uses CircuitPython BusIO library to find the current
17  address of the Qwiic Relay. It uses information from
18  https://learn.adafruit.com/circuitpython-basics-i2c-and-spi/i2c-devices
19  to manually scan for the Qwiic Single Relay.
20
21  Since the Qwiic Single Relay responds to any byte read request after it's
22  base address is written, i2c.scan()cannot be used.
23
24  This code manually scans addresses from 0x03 to 0x80, using only writes,
25  not writes and reads,to find i2c devices.
26
27  The factory default address is 0x18.
28"""
29import sys
30from time import sleep
31import board
32
33i2c = board.I2C()
34
35# Since i2c.scan() returns all addresses above the relay address,
36# we look for the relay address using only write requests.
37
38
39def test_i2c_write(addr):
40    "Write to an address to see if there's an device there" ""
41    while not i2c.try_lock():
42        pass
43
44    try:
45        # Make an empty write request to an address
46        i2c.writeto(addr, b"")
47        return True
48
49    except OSError:
50        return False
51
52    # Always unlock the i2c bus, before return
53    finally:
54        i2c.unlock()
55
56
57print("Press Ctrl-C to exit program")
58
59try:
60    while True:
61        found = []
62
63        # scan through all possible i2c addresses doi
64        for address in range(0x03, 0x80):
65            if test_i2c_write(address):
66                found.append(address)
67
68        if found:
69            print(
70                "I2C addresses found:",
71                [hex(device_address) for device_address in found],
72            )
73        else:
74            print("No I2C device found.")
75
76        # wait a bit and scan again
77        sleep(5)
78
79except KeyboardInterrupt:
80    pass

  1. Relay Status - Show if the relay is on or off.

examples/example4_get_relay_status.py
 1# SPDX-FileCopyrightText: Copyright (c) 2019-2021 Gaston Williams
 2#
 3# SPDX-License-Identifier: Unlicense
 4
 5#  This is example is for the SparkFun Qwiic Single Relay.
 6#  SparkFun sells these at its website: www.sparkfun.com
 7#  Do you like this library? Help support SparkFun. Buy a board!
 8#  https://www.sparkfun.com/products/15093
 9
10"""
11 Qwiic Relay Example 4 - example4_get_relay_status.py
12 Written by Gaston Williams, June 18th, 2019
13 Based on Arduino code written by
14 Kevin Kuwata @ SparkX, March 21, 2018
15 The Qwiic Single Relay is an I2C controlled relay produced by sparkfun
16
17 Example 4 - Get Relay Status:
18 This program uses the Qwiic Relay CircuitPython Library to
19 get the current status of the Qwiic Relay. The relay responds
20 with a 1 for on and a 0 for off.
21
22 Default Qwiic relay address is 0x18.
23"""
24import sys
25from time import sleep
26import board
27import sparkfun_qwiicrelay
28
29# Create bus object using our board's I2C port
30i2c = board.I2C()
31
32# Create relay object
33relay = sparkfun_qwiicrelay.Sparkfun_QwiicRelay(i2c)
34
35print("Qwiic Relay Example 4 Get Relay Status")
36
37# Check if connected
38if relay.connected:
39    print("Relay connected.")
40else:
41    print("Relay does not appear to be connected. Please check wiring.")
42    sys.exit()
43
44print("Type Ctrl-C to exit program.")
45
46try:
47    while True:
48        relay.relay_on()
49        print("The relay status is ", relay.status)
50        sleep(2)
51        relay.relay_off()
52        print("The relay status is ", relay.status)
53        sleep(2)
54
55except KeyboardInterrupt:
56    pass

  1. Firmware Version - Display the firmware version string.

examples/example5_get_firmware_version.py
 1# SPDX-FileCopyrightText: Copyright (c) 2019-2021 Gaston Williams
 2#
 3# SPDX-License-Identifier: Unlicense
 4
 5#  This is example is for the SparkFun Qwiic Single Relay.
 6#  SparkFun sells these at its website: www.sparkfun.com
 7#  Do you like this library? Help support SparkFun. Buy a board!
 8#  https://www.sparkfun.com/products/15093
 9
10"""
11 Qwiic Relay Example 5 - example5_get_firmware_version.py
12 Written by Gaston Williams, June 13th, 2019
13 Based on Arduino code written by
14 Kevin Kuwata @ SparkX, April 3, 2018
15 The Qwiic Single Relay is an I2C controlled relay produced by sparkfun
16
17 Example 5 - Get Firmware Version:
18 This program uses the Qwiic Relay CircuitPython Library to get the
19 firmware version of Qwiic Single Relay breakout.  If using version prior
20 to version 1.0 the version number will be 25.5 or 26.5. Starting at
21 version 1.0, the relay will respond with the correct firmware version.
22
23 Default Qwiic relay address is 0x18.
24"""
25import sys
26from time import sleep
27import board
28import sparkfun_qwiicrelay
29
30# Create bus object using our board's I2C port
31i2c = board.I2C()
32
33# Create relay object
34relay = sparkfun_qwiicrelay.Sparkfun_QwiicRelay(i2c)
35
36print("Qwicc Relay Example 5 Get Firmware Version")
37
38# Check if connected
39if relay.connected:
40    print("Relay connected.")
41else:
42    print("Relay does not appear to be connected. Please check wiring.")
43    sys.exit()
44
45print("Type Ctrl-C to exit program.")
46
47try:
48    while True:
49        print("Firmware version: " + relay.version)
50        sleep(2)
51
52except KeyboardInterrupt:
53    pass

  1. Set Relay Status - Set relay status to turn relay on and off.

examples/example6_set_relay_status.py
 1# SPDX-FileCopyrightText: Copyright (c) 2019-2021 Gaston Williams
 2#
 3# SPDX-License-Identifier: Unlicense
 4
 5#  This is example is for the SparkFun Qwiic Single Relay.
 6#  SparkFun sells these at its website: www.sparkfun.com
 7#  Do you like this library? Help support SparkFun. Buy a board!
 8#  https://www.sparkfun.com/products/15093
 9
10"""
11 Qwiic Relay Example 6 - example6_set_relay_status.py
12 Written by Gaston Williams, June 21st, 2019
13 The Qwiic Single Relay is an I2C controlled relay produced by sparkfun
14
15 Example 6 - Set Relay Status:
16 This program uses the Qwiic Relay CircuitPython Library to
17 set the relay status property to turn the relay on and off.
18
19
20 Default Qwiic relay address is 0x18.
21"""
22import sys
23from time import sleep
24import board
25import sparkfun_qwiicrelay
26
27# Create bus object using our board's I2C port
28i2c = board.I2C()
29
30# Create relay object
31relay = sparkfun_qwiicrelay.Sparkfun_QwiicRelay(i2c)
32
33print("Qwiic Relay Example 6 Set Relay Status")
34
35# Check if connected
36if relay.connected:
37    print("Relay connected.")
38else:
39    print("Relay does not appear to be connected. Please check wiring.")
40    sys.exit()
41
42print("Type Ctrl-C to exit program.")
43
44try:
45    while True:
46        # Set status = 1/True is the same as relay.relay_on()
47        relay.status = True
48        print("The relay status is", bool(relay.status))
49        sleep(2)
50
51        # Set status = 0/False is the same as relay.relay_off()
52        relay.status = False
53        print("The relay status is", bool(relay.status))
54        sleep(2)
55
56except KeyboardInterrupt:
57    pass