numato-usb-relay 0.0.1

A small USB Relay example package

Python API for Numato USB Relays

This Python API can be used to control Numato USB USB Relay expanders

• Control the Relays "On" and "Off" state.
• Write to output ports
• Read from input ports
• Read integer values from ADC input ports

numato-usb-relay allows to control relay modules (ON or OFF states). This module is compatible with all Numato USB Relay series.

Requirement

The module requires the minimum configuration :

• Windows-10(64 bits) and later
• Linux 64-bits
• Python3.6 and later

License

This API is licensed under the GNU Lesser General Public License v3.0. See LICENSE for full license text.

Installation

Install the latest release:

pip install numato_usb_relay

Usage CLI

Linux :
Test whether your devices can be found running the command-line interface like python3 -m numato_usb_relay.relay. Remember to have your user in the dialout group, since the devices are registered as /dev/ttyACMx (i.e. modem devices). The default Baudrate is 921600.

Expected output:

❯ python3 -m numato_usb_relay.relay
Discovered devices:
dev: /dev/ttyACM0 | id: 00000000 | ver: 00000008 | ports: 32 | eol: '\r' 
dev: /dev/ttyACM1 | id: 12345678 | ver: A0M09.01 | ports: 16 | eol: '\r' 

Windows :
Test whether your devices can be found running the command-line interface like python -m numato_usb_relay.relay. The default Baudrate is 921600. Expected output:

❯ python -m numato_usb_relay.relay
Discovered devices:
dev: COM27 | id: 00000000 | ver: 00000008 | ports: 32 | eol: '\r' 
dev: COM5 | id: 12345678 | ver: A0M09.01 | ports: 16 | eol: '\r' 

How to use it

The command line to drive relays are :

Windows :

python -m numato_usb_relay.relay --cmd=<string to drive relays> --relays=2 --port=<port> --baudrate=<baudrate> 

Linux :

python3 -m numato_usb_relay.relay --cmd=<string to drive relays> --relays=2 --port=<port> --baudrate=<baudrate> 

Note : For all CLI commands use python3 when using in Linux Systems and python in Windows Systems.

Parameters are :

--cmd : the command to drive individual relays (default is "x")

--relays : the number of relays to drive (default is 1)

--port : the port (default is /dev/ttyUSB1 or "COM1")

--baudrate : the baudrate (default is 921600)

--name : the type of Numato Usb relay module name (default is "usb", change the name as "powered" or "ssr" or "USBR" for Powered or SSR or NL-USBR-C usb relay modules respectively).

A relay can receive two types of orders (OFF or ON). The order in the module is encoding by an ASCII character such as :

"c" : close the relay (OFF state)

"o" : open the relay (ON state)

"x" : do not change the current state of the relay

For example consider a 4 channel USB Powered Relay module :

• 4 available relays : 0, 1, 2 and 3
• baudrate is 921600
• port is COM27
• name is powered

Single Modules:

When only a Numato USb Relay module is connected, The package automatically detects the port and number of relays connected hence there is no requirement of giving these parameters in the command pattern, follow the command pattern as shown below to control the relays through CLI:

command pattern examples for 4 channel usb relay module is given here,

To turn on all relays, string command is oooo and the command line is :

python -m numato_usb_relay.relay --cmd="oooo"

To turn off all relays, string command is cccc and the command line is :

python -m numato_usb_relay.relay --cmd="cccc"

To turn on the relay 0, and it does not matter about other ones, string command is oxxx and the command line is :

python -m numato_usb_relay.relay --cmd="oxxx"

To turn on the relays 1 and 3, and it does not matter about other ones, string command is xoxo and the command line is :

python -m numato_usb_relay.relay --cmd="xoxo"

Multiple Modules:

When many Numato usb modules are connected, provide the port and relays parameter to control the right module, use the command pattern as shown below to control a 4 channel usb relay module:

python -m numato_usb_relay.relay --cmd="oooo" --relays=4 --port="COM27"

List of Commands

1. ver()
2. id_get()
3. id_set("x")
4. info()
5. relay_on("x")
6. relay_off("x")
7. relay_read("x")
8. relay_writeall("x")
9. relay_readall()
10. reset()
11. gpio_set("x")
12. gpio_clear("x")
13. gpio_read("x")
14. adc_read("x")
15. relay_poweron("x")
16. gpio_poweron("x","x")^(*3)

Note:

1. "x" is the parameter to be passed in the commands, please refer the "sending commands" section in the user manual of the connected module to send the right arguement and to understand the functioning of each command.
2. Please pass the values/arguements of commands within the double qoutes (eg. relay_read("A")).
3. Follow the commnad pattern gpio_poweron("x") for NL-USBR-C-001 module, where dedicated outputs are present, only the Gpio value is passed as the arguement.

Usage API

The API can be used like:

from numato_usb_relay.relay import Relay 

# Please change the number of Relays and COM Port accordingly.
# Please enter the name as "powered" or "ssr" or "USBR" if the module consists of Powered or SSR or NL-USBR-C Relays respectively.
Device = Relay(numberRelays=4, port="COM27", name="usb") 

# To get the version of the module
Device.ver()

# To get the Device Id 
Device.id_get()

# To turn on all the relays
Device.relay_writeall("0F")

# To get the Power-On Status of the module
Device.info()

# To turn on a single relay & read the status
Device.relay_on("0")
Device.relay_read("0")
#Device.relay_off("000")    # NL-USBR-C-001 command pattern

# Setting the Relay Power-On Value
Device.relay_poweron("0F")

# Setting the Gpio Power-On Direction & Value
Device.gpio_poweron("00","0F")
#Device.gpio_poweron("05")  # only for NL-USBR-C-001