# Python API for Numato Ethernet Relay/GPIO Modules

This Python API can be used to control [Numato Ethernet Relay expanders](https://numato.com/product-category/automation/relay-modules/ethernet-relay/), [Numato Ethernet GPIO expanders](https://numato.com/product-category/automation/gpio-modules/ethernet-gpio/) and [Numato PoE Relay expanders](https://numato.com/product-category/automation/relay-modules/power-over-ethernet-relay/).

* Controlling the Relays "On" or "Off" state
* Configure ports as input or output port
* Write to output ports
* Read from input ports
* Read integer values from ADC input ports

numato-eth allows to control relay modules (ON or OFF states) and gpio states. This module is compatible with all Numato ethernet-relay and gpio, PoE - relay and gpio 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](https://www.gnu.org/licenses/lgpl-3.0.html) for full license text.


## Installation
Install the latest release:
```
pip install numato_eth
```

## Usage CLI
Expected output:

Linux :
```
❯ python3 -m numato_eth.eth --deviceIP=<ip> --username=<username> --password=<password>
Device IP: 192.168.10.5 | id: 00000000 | ver: 00000005 | ports: 16 | eol: '\r\n'
```
Windows :
```
❯ python -m numato_eth.eth --deviceIP=<ip> --username=<username> --password=<password>
Device IP: 192.168.10.5 | id: 00000000 | ver: A0M06.01 | ports: 16 | eol: '\r\n'
```
<br/>

## How to use it
The command line to drive relays are :

Windows :
```
python -m numato_eth.eth --deviceIP=<ip> --username=<username> --password=<password> --cmd=<string to drive relays> --relays=8 
```

Linux :
```
python3 -m numato_eth.eth --deviceIP=<ip> --username=<username> --password=<password> --cmd=<string to drive relays> --relays=8  
```

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

\
Parameters are :

`--deviceIP` : the ip (default is 192.168.1.0) to connect the module

`--username` : the username (default is admin)

`--password` : the password (default is admin)

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

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

`--gpios` : the number of gpios (default is 8, if the module is gpio module)

\
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 8 channel PoE Relay module :

- 8 available relays : 0, 1, 2, 3, 4, 5, 6, 7 and 8
- ip is 192.168.10.5
- username and password is admin

\
command pattern examples for 8 channel Ethernet Relay module is given here,

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

```
python -m numato_eth.eth --deviceIP=192.168.10.5 --username=admin --password=admin --cmd="oooooooo" --relays=8
```

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

```
python -m numato_eth.eth --deviceIP=192.168.10.5 --username=admin --password=admin --cmd="cccccccc" --relays=8
```

To turn on the relay 0,1,2,3 and it does not matter about other ones, string command is `ooooxxxx` and the command line is :

```
python -m numato_eth.eth --deviceIP=192.168.10.5 --username=admin --password=admin --cmd="ooooxxxx" --relays=8
```

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

```
python -m numato_eth.eth --deviceIP=192.168.10.5 --username=admin --password=admin --cmd="xoxoxoxo" --relays=8
```

`Note` : There is no command line interface command to control gpio modules.
<br/>

## List of Commands
1. ver()
2. info()
3. id_get()
4. id_set("x")
5. usr_get()
6. usr_set("x")
7. pass_get()
8. pass_set("x")
9. reset()
10. relay_on("x")
11. relay_off("x")
12. relay_read("x")
13. relay_readall()
14. relay_writeall("x")
15. gpio_set("x")
16. gpio_clear("x")
17. gpio_read("x")
18. gpio_status("x")
19. gpio_iomask("x")
20. gpio_iodir("x")
21. gpio_writeall("x")
22. gpio_readall()
23. adc_read()
24. notify_get()
25. notify_set("x")
26. reboot()
27. gpio_setup("x","x")
<br/>

`Note`: 
1. "x" is the parameter to be passed in the commands, please refer the **"Sending Commnads"** section in the user manual of the module for sending the right arguement and to understand the functioning of each command. Relay commands and some of the gpio commands are module specific.
2. gpio_setup("x","x") command is only available for GPIO modules.
<br/>

## Usage API

The API can be used like:

`Note` : Refer the **"Sending Commnads"** document of the module to be controlled and pass the proper commands.

``` python
from numato_eth.eth import Eth_Module 

# Please change the number of Relays/Gpios and credentials (ipaddress, username, password) accordingly.
Device = Eth_Module(deviceIP="192.168.10.5", username="admin", password="admin", numberRelays=16)  //For gpio modules numberGpios=8

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

# To get the Device Id 
Device.id_get()

# To turn on all relays
Device.relay_writeall("ffff")

# To set a single Gpio & read the status
Device.gpio_set("0") 
Device.gpio_read("0")

#To turn on a single relay
Device.relay_on("F")
#Device.relay_off("014")  //For PoE module

#To Setup the gpio pin as In/Out in gpio modules
# To change the direction of any port
Device.gpio_setup([0],"OUT")       // [ ports ] and IN/OUT : direction
Device.gpio_setup([1,3,8],"OUT")

# Enable notify
Device.notify_set(1)  // 0 - Disable and 1 - Enable notify feature

```
