EVOK version 1.11
http://your-unipi-device-ip:8080
Please note that this documentation is deprecated and is intended just for a basic introduction to the REST API endpoint structure. We are working hard on the new one :-). Thank you for understanding.
Overview
Welcome to the UniPi EVOK Documentation
EVOK is the primary Web API for NEURON and UniPi 1.1 devices. It provides a RESTful interface over HTTP, a JSON-RPC interface, a WebSocket interface a SOAP interface and a bulk JSON interface to UniPi devices.
Evok is still in active development, so any testing, feedback and contributions are very much welcome and appreciated.
APIs included in EVOK:
- RESTful WebForms API
- RESTful JSON API
- Bulk request JSON API
- WebSocket API
- SOAP API
- JSON-RPC API
EVOK also supports sending notifications via webhook.
Installation process for the 2.0 EVOK version
In order to install EVOK on Neuron you will need an SD card with a standard Raspbian Jessie or Raspbian Stretch image. It is also necessary to enable SSH on the image by creating an empty file named "ssh" in the boot partition of your SD card (the partition should be visible on all systems which support FAT16, which includes Windows, Linux and OSX among others).
Detailed installation instructions can be found on our github repository.
Installation process for the legacy version
Access to GPIOs is done using the fantastic PIGPIO library. Make sure to install it first before use.
Legacy Evok also requires a few other python libraries that are not installed on Raspbian by default:
- python-ow
- tornado
- toro
- modified version of tornardorpc available in this repo tornadorpc_evok
- jsonrpclib
Download the latest release from our repository via wget (alternatively you can clone the repository using git):
wget https://github.com/UniPiTechnology/evok/archive/v.1.0.2.tar.gz
tar -zxvf v.1.0.2.tar.gz && mv evok-* evok
Please note that the folder that you downloaded the package into is not used later and can be safely deleted after the installation. Configuration files are installed directly into /etc/, /opt/ and /boot/
Run the installation script using the following instructions
cd evok
chmod +x install-evok.sh uninstall-evok.sh
sudo ./install-evok.sh
Instructions for use
The EVOK API can be accessed in several different ways. This documentation covers primarily the HTTP-based methods (WebForms, REST JSON, Bulk JSON) of doing so.
If you wish to read more about WebSocket, JSON-RPC or SOAP, you will find sections covering it in rest of the introductory documentation, but the documentation will not be as exahaustive as for the other three, in part because the nature of these protocols doesn't lend itself for easy representation in an HTTP API documentation framework.
Unfortunately, due to the nature of the documentation interface, the individual device endpoints could not be sorted alphabetically. The easiest way to find the applicable URIs is by putting the device name listed in Internal Devices into the filter box at the top left corner of the screen.
Note regarding device addressing
The sub-devices of your Neuron or UniPi 1.1 unit are addressed using an internal id scheme. On the UniPi 1.1 this is specified by the user himself, whereas for Neuron the addressing scheme is based on the physical numbering on the device. Each Neuron is composed of several groups, each of which has it's own id; the actual device circuit id is composed of the group id and the device index (i.e. 3rd DO of the second group is addressed as /do/3_03).
For RS485 the addressing scheme is slightly more complex, and is described in more detail in the Extensions section.
There is also the posibility of aliasing device names, to allow devices to be given permanent names. There are several restrictions to aliases:
- All aliases must begin with al_
- Every alias needs to globally unique, not just within it's own class
- Aliases can only contain alphanumeric characters, underscores and dashes. This is to allow devices to addressed via the alias using the REST APIs (i.e. setting an alias for a relay 1_01 to "al_bedroom_light" will allow it to be addressed both as /rest/relay/al_bedroom_light as well as /rest/relay/1_01)
Invalid aliases will be rejected by the API, with the previous alias remaining.
WebForms (legacy) API
The REST WebForm-based api is found in the Rest section on the left. It is the oldest API available in EVOK, and should be compatible with legacy applications based on EVOK.
POST requests to the WebForm/Rest API do not have a body, with all the information encoded using URI arguments, e.g. to set the variable "value" to 1, one would send the request to the following URI:
localhost:8080/rest/ai/1_01?value=1
Unlike the JSON API(s), the WebForms API does not perform explicit request format verification.
The return format of the WebForm API is a json dictionary, specification details for which are available in the individual enpoint sections listed to the left of this article.
JSON REST API
The JSON REST API is in most respects identical to the WebForm API, but instead of receiving input in the request URI it accepts a JSON dictionary containing the request data. This makes it more convenient for certain applications, while still following REST principles for device addressing.
Bulk API
The Bulk API can be used to send multiple queries and commands with a single message. This results in potentially orders of magnitude lower latency compared to the REST APIs; however in order to do this it foregoes following the traditional REST URI scheme.
Aside from being able to process multiple requests equivalent to standard GET/POST operations in a single requests, it also implements an optional set-based addressing scheme. This allows the user to e.g. set all the relays in group 2 to a given value, reset every digital input counter on the Neuron but not on any connected extensions, or read all the counters in group 3.
Debugging
When reporting a bug or posting questions to our forum please set proper logging levels in /etc/evok.conf, restart your device and check the log file (/var/log/evok.log). For more detailed log information you can also run evok by hand. To do that you need to first stop the service by executing the
systemctl stop evok
command and then run it manually as root user
sudo python /opt/evok/evok.py
and look through/paste the output of the script.
Installing the Master (development) version
If you wish to install the latest development version of EVOK you can use the following commands; please note that there may be potentially undiscovered issues or unfinished features.
To install the EVOK Master first connect to your Neuron using SSH (there is a large number of clients you can use, for windows we recommend using PUTTY). The default username for Raspbian is "pi" and the default password is "raspberry". After you connect to your Neuron execute the following commands:
sudo su
wget https://github.com/UniPiTechnology/evok/archive/master.zip
unzip master.zip
cd evok-master
bash install-evok.sh
The installation script should take care of everything else, but be aware there may be some issues with limited and/or broken functionality. Please report any bugs you find on the github repository.
Developer Note
Do you feel like contributing to EVOK, or perhaps have a neat idea for an improvement to our system? Great! We are open to all ideas. Get in touch with us via email to info at unipi DOT technology
License
Apache License, Version 2.0
Raspberry Pi is a trademark of the Raspberry Pi Foundation
Description
Frequently Asked Questions (FAQ)
1. How do I add UniPi UART extension device to a Neuron running EVOK?
You will need to connect to your Neuron via SSH, and edit the file /etc/evok.conf. Therein you will find a commented-out section (prepended with the ; character) which demonstrates how to add extension devices to Neuron; we are specifically interested in the following section:
1) ;[EXTENSION_1]
2) ;global_id = 2 ; Mandatory, REQUIRED TO BE UNIQUE
3) ;device_name = xS10 ; Mandatory
4) ;modbus_uart_port = /dev/extcomm/0/0 ; Mandatory
5) ;neuron_uart_circuit = 1_01 ; Optional, allows associating extensions with specific Neuron UART-over-Modbus ports (not possible for non-Modbus UART ports, e.g. /dev/ttyUSB0 or /dev/ttyS0)
6) ;allow_register_access = True ; Optional, False default, is mandatory with third-party devices
7) ;address = 1 ; Optional, 1 default
8) ;scan_frequency = 10 ; Optional, 10 default
9) ;scan_enabled = True ; Optional, True default
10) ;!!Do not uncomment this line!! ; Note that the following settings will be inherited by other devices sharing the same port, i.e. /dev/extcomm/0/0
11) ;baud_rate = 19200 ; Optional, NEEDS UNIPI IMAGE TO WORK! USE API TO CONFIGURE UART MANUALLY IF USING STANDARD RASPBIAN
12) ;parity = N ; Optional, NEEDS UNIPI IMAGE TO WORK! USE API TO CONFIGURE UART MANUALLY IF USING STANDARD RASPBIAN
13) ;stop_bits = 1 ; Optional, NEEDS UNIPI IMAGE TO WORK! USE API TO CONFIGURE UART MANUALLY IF USING STANDARD RASPBIAN
In order to create a simple extension setup you should uncomment lines 1), 2), 3), 4), 5); as well as fill in the name of your device into 3). Following device names are possible:
- xS10
- xS30
- xS40
- xS50
You can find the name of your extension by looking at the lettering on the top of your device, or on the label on its side.
You will also need to setup the dip switches on the device, such that the device is set into UART mode 8N1 19200 address 1. The procedure for doing so differs between the devices, but should be easy to discern by looking at the laser-etched legend on top of the device. Note that for the xS50 there are no dip switches for setting speed or parity, only address.
To setup more devices simply create a copy of the section below the first one. You will have to change the bracketed name, global_id and use a different port or address.
2. How do I add a third-party UART Modbus device to a Neuron running EVOK?
There are two separate files which need to be changed for a custom Modbus device to function - the hardware definition and the EVOK configuration file.
You can find an example hardware configuration file in /etc/hw_definitions/CUSTOM MODBUS DEVICE.yaml The definitions are stored in YAML format, with two sections - Modbus register definitions and device definitions. Both must be filled in correctly for the device to function. The example file has comments describing the structure of the file.
The second part of the configuration is in the /etc/evok.conf file. There are commented-out sections (prepended with the ; character) which demonstrate how the custom modbus device should be added to EVOK.
Note that third-party device support is available purely as direct Modbus register access. While conceptually it is possible that a device which matches exactly the implementation of one of our internal devices may function in a non-purely-Modbus mode (the ULEDs in particular have the most potential in this regard), it is very unlikely.
3. Can I use EVOK with operating system/platform X?
Currently we officially support the following Linux distributions with EVOK: Raspbian Jessie and Raspbian Wheezy. In the near future we also plan to release official UniPi Debian packages and a UniPi distribution containing EVOK.
EVOK must also be executed on a UniPi device to function; but, as it is an API, you can connect to it from any of the number of systems which support one of the EVOK communication protocols.
4. Can I use EVOK purely as a Modbus API?
While EVOK is designed to function as an interpretative interface to Modbus, it is possible to use in purely Modbus mode.
To activate Modbus register access you will need to change the allow_register_access key in the device section of the EVOK configuration file. See the Confguration documentation section for more informations regarding the file and the options within.
If you wish to remove the internal representations entirely, you may do so by editing the hardware configuration file directly. Follow the advice in point 1. of this FAQ to see how it's done.
Configuration
If you wish to manually change the default evok configuration, you can do so by editing the "/etc/evok.conf" and "/etc/evok-nginx.conf" files.
The configuration files use the standard Python ini format, with comments indicated by semicolons (i.e. in order to activate a commented-out section remove the semicolon comment marks from the beginning of each line).
/etc/evok.conf
This is the primary evok configuration file. It consists of two parts - the main section and the device section.
Main section
The main section (delimited by empty lines and beginning with a line consisting of [MAIN]) contains general EVOK settings which do not pertain to specific devices. The section contains the following keys:
- config_version = X.Y
- This key specifies the minor (X) and major (Y) version of the configuration format; there shouls be no need to manually change this variable and it is in fact recommended not to do so.
- use_schema_verification = [False|True]
- This key enables verification of input and output according to a strict JSON schema, based on which the main part of this documentation was generated.
- Enabling output verification results in an order of magnitude higher latency than normal, and should only be used for testing purposes.
- log_level = [INFO|DEBUG|WARNING|ERROR|CRITICAL]
- This key determines the minimum severity of messages to be stored in the EVOK system log.
- The log can be retrieved via a POST request to Complete State (see the endpoint documentation on the left for more details).
- log_file = XYZ [DEFAULT: /var/log/evok.log]
- This key points to the location of the EVOK log file.
- EVOK uses automatic timestamps and file rotation to allow multiple logs to be saved.
- It is recommended that the log file location is kept somewhere within the /var/ top-level folder.
- port = XYZX [DEFAULT: 8080]
- This is the primary port used by the EVOK API
- Changing this value without changing all the other occurences of it in /etc/evok-nginx.conf will stop the web interface from working
- The SOAP interface uses separate port, as does the sample web interface
- webhook_enabled = [False|True]
- This key enables webhook notification, which sends either a POST or GET request whenever device state changes (this is further confgurable by the keys below) to a specified address
- Capturing webhook requires a custom server implementation to listen to the messages, see what's webhook (external link) for more details
- webhook_address = http://XYZ.XY/xyz
- The consumer endpoint for the webhook. The address should point to a properly-configured webserver which can recieve GET (and optionally POST) requests
- webhook_device_mask = [DEFAULT: ["input", "wd"]]
- This is a mask encoded as a JSON array, which contains the REST paths of devices which should be sent via WebHook.
- It may be helpful to omit AO,AI and REGISTER, as values these devices may fluctuate
- webhook_comple_events = [False|True]
- This key causes EVOK to send POST rather than GET messages to the webhook endpoint specified above. The POST messages will contain device state of the devices changes in the body of the request.
- wifi_control_enabled = [False|True]
- This key allows EVOK to control the internal WiFi adapter within Neuron.
- In order to work properly, the UniPiAP system needs to be installed as well (the installation scripts asks the user whether it should or should not be installed)
- This key enables the "WiFi Adapter" endpoints and devices
- soap_server_enabled = [False|True]
- This key enables the internal EVOK SOAP server.
- The server contains two services, which are described in more detail in the appropriate endpoints in the section on the left, as well as the SOAP Basics section of the documentation
- SOAP cannot run on the same port as the primary API!
- soap_server_port = [DEFAULT: 8081]
- This key specifies which port the SOAP server should run on
- This port cannot be the same as the main API port or the web interface port
- If the soap_server_enabled key above is False, then this port will not be used and will be left free.
Device sections
The device sections are each delimited by empty lines at the beginning and the end, with the first line denoting the section name in square brackets.
The section names consist of a device type name written in ALL CAPS, along with an undescore and a unique device index, e.g. [NEURON_1].
The default configuration files should contain an explanation as to the device section format. It should only be necessary to change the device sections in the case of the following:
- New UART Modbus extensions/devices have been added
- New 1Wire relays or inputs have been added
- UNIPI 1.1 only: an i2c extension board has been added
/etc/evok-nginx.conf
This file is used to configure the sample EVOK-consuming web server running on Nginx. The configuration will be generated by the installation script, and should only be changed if necessary. One particular time when the file needs to be changed is if the primary EVOK API port changed as well (the port is listed above). This can be easily accomplished by replacing all the instances of the previous API port number with the desired new API port number.
In order to deactivate the EVOK NGINX web interface, delete the file which this file (actually a symlink) points to; /etc/nginx/sites-enabled/evok.
Hardware definitions
For details on the hardware definition files, please see the Extensions section of this documentation.
Internal devices controlled via EVOK
EVOK allows users to retrieve data from, and manipulate with, the following internal devices:
- Analog inputs
Analog inputs are used to read control signals transmitted via varying low amounts of output current, voltage or resistance. Resistance measurement is available only on Neuron.
The capabilities of the Analog inputs vary between our models; the modes and tolerances supported can be retrieved via a GET request to the device, described in the Get Analog Input State endpoint on the left.
To configure the analog inputs, send a POST request to the device instead; the available commands can be seen in the Change Analog Input State endpoint on the left.
On the UniPi 1.1 these are implemented via PWM, which can additionally be manually controlled using UniPi 1.1-specific arguments.
- Analog outputs
Analog outputs are used to generate control signals by varying output voltage or current. On Neuron some of the analog outputs can also be used for measuring resistance.
The capabilities of the Analog outputs vary between our models; the modes and tolerances supported can be retrieved via a GET request to the device, described in the Get Analog Input State endpoint on the left.
To configure the analog outputs, send a POST request to the device instead; the available commands can be seen in the Change Analog Output State endpoint on the left.
- Digital inputs
Digital inputs are used to to read control signals transmitted via digital logic. On Neuron they can also be used to trigger DirectSwitch (i.e. very-low-latency switching) behaviour.
The capabilities of the Digital inputs vary between our models; supported counter modes, DirectSwitch modes and debounce settings (the suppression of harmonics from edge events) can be retrieved via a GET request to the device, described in the Get Input State endpoint on the left.
To configure the configurable properties of digital inputs, send a POST request to the device; the commands available can be seen in the Change Input State endpoint on the left.
- Relay-based and Transistor-based (digital) outputs
Digital outputs are used to generate control signals and interrupt small amounts of current via circuit interruption. For this reason they have to be connectod to an external power source to operate. On Neuron, some of the transistor-based digital outputs can also be used for PWM modulation
The capabilities of the Digital outputs vary between our models; the transistor type (physical - i.e. a relay, or digital - i.e. transistor-based), timing modes and available PWM settings can be retrieved via a GET request to the device, described in the Get Output State endpoint on the left.
To configure the configurable properties of digital outputs, send a POST request to the device; the commands available can be seen in the Change Output State endpoint on the left.
- UART ports
UART port devices are used to configure serial port properties for Neuron. Serial ports allow for 2-way communication with external systems, though an important caveat is that only one protocol may be used on a single link. Our Neuron extensions are accessed via serial ports, via the oft-used Modbus protocol.
Only ports which are directly implemented in Neuron hardware are represented (not external ones made available through e.g. USB devices). Regardless of this, however, Modbus extensions/devices can still be connected to external UARTS and will be visible in EVOK.
The capabilities of the UART ports may vary between our models, mainly in terms of the transmission modes and timings supported. The UART settings available can be retrieved via a GET request to the device, described in the Get UART State endpoint on the left.
To configure the configurable properties of UART ports, send a POST request to the device; the commands available can be seen in the Change UART State endpoint on the left.
- User-configurable LEDs
User-configurables LEDs (henceforth referred to as ULEDs) are light-based indicators, which can be used to signal important information from your application to the user. They are controlled in a manner similar to the digital outputs and marked with letters "X1" up to "X[n]" (for [n] LEDs) on your Neuron device.
To configure the configurable properties of ULEDs, send a POST request to the device; the commands available can be seen in the Change User LED State endpoint on the left.
- Board Watchdog
The Board Watchdog (henceforth referred to as Watchdog) is used to ensure the continous operation of the device. It works by restarting parts of the device if they become unresponsive; this is then indicated to the user by the "value" flag of the Watchdog device changing to "1". The Watchdog feature is only available on Neuron
The Watchdog can also be used to set up a default state for the device. This is done by configuring the device into the desired state, and then setting the "nv_save" property to 1.
To configure the configurable properties of board watchdogs, send a POST request to the device; the commands available can be seen in the Change Watchdog State endpoint on the left.
- WiFi Adapter (optional)
Provided that the WiFi Adapter device support is installed and enabled within the EVOK configuration file, this device can be used to create an access point for access over local wireless. It is turned off by default; as is the routing of packets via Masquerade to the ethernet connection. The latter can be turned on via the "eth0_masq" property, while the adapter itself is turned on via the "ap_state" property
Note that any WiFi operations may take some time to perform; orders of magnitude more than other EVOK operations.
The SSID and key are intentionally set to predefined values, as the device is not intended to act as a secure access point/router! The values are SSID: UNIPICONFIG and wpa_passphrase: unipi.technology. The values can be changed in /opt/unipiap/etc/hostapd.conf
To configure the configurable properties of the WiFi Adapter, send a POST request to the device; the commands available can be seen in the Change WiFi Adapter State endpoint on the left.
- Lighting Controller (on the M603)
Allows sending commands to a standard digital lighting bus, with broadcast commands exported to the web GUI.
Light detection is only rudimentary, and requires re-addressing devices from scratch every time.
Using UniPi REST Endpoints
In order to make use of our REST Endpoints POST methods, one has to pass a body encoded with "x-www-form-urlencoded". This body has the following format:
key1=value1&key2=value2&key3=value3
That is to say, the format is the same as for encoding arguments as they would be passed inside the URL.
Here is an example for sending a POST request to change digital output state via CURL:
curl --request POST --url 'http://localhost:8080/rest/output/1_01/' --data 'value=1'
Sample Web Interface
EVOK includes a simple web interface which can be used to issue commands to your Neuron and UniPi device and to read the current state of the various device sensors. While it is intended to act primarily as a way of demonstrating how to implement a web interface for communicating with EVOK, it is capable of of performing and configuring all the functionality of Neuron devices.
We offer a number of ways to control your Neuron and UniPi devices, the simplest of which is using a web browser to visit:
http://your.pi.ip.address:web-interface-port
If EVOK came pre-installed with your image it will be available on port 88.
The sample web interface is using websocket to receive all events from the UniPi and controls the UniPi device via the REST api.
SOAP Basics
SOAP is an XML-based communication protocol which features strict data format specification. It's primary advantage is ease of use given appropriate tools, and strict format verification for inputs and outputs. Among the disadvantages is a relatively higher latency than REST/JSON/WebSocket and the need for external libraries and/or tools to provide access to it. The SOAP ecosystem is very large however, and as such there are libraries available for a wide variety of systems and programming languages.
SOAP must be enabled in the EVOK configuration file and needs to use a separate port, as it does not use the HTTP protocol in the same manner as the rest of EVOK.
The specification (WSDL file) for any given service can be obtained by visiting the web service URI with the ?wsdl query parameter, e.g. "127.0.0.1:8081/UniPiQueryService?wsdl".
There is a large number of SOAP clients which you can use to try SOAP out, e.g. SoapUI by SmartBear.
Device types come from the following list (and otherwise correspond to the device path in the Rest API):
'relay', 'input', 'ai', 'ao', 'ee', 'sensor', 'i2cbus', 'adchip', 'owbus', 'mcp', 'gpiobus', 'pca9685', 'ds2408', 'unipi2', 'uart', 'neuron', 'board', 'misc_output', 'led', 'watchdog', 'register', 'wifi', 'light_channel', 'light_device'
and the "circuit" is the device name as specified in the configuration file.
As an example for UniPi 1.1:
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:unip="http://192.168.1.146:8081/UniPiQueryService">
<soapenv:Header/>
<soapenv:Body>
<unip1:SoapQueryInputList xmlns:unip1="http://127.0.1.1:8081/UniPiQueryService">
<!--1 or more repetitions:-->
<single_query>
<device_circuit>1</device_circuit>
<device_type>relay</device_type>
</single_query>
</unip1:SoapQueryInputList>
</soapenv:Body>
</soapenv:Envelope>
An example for setting relays:
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:unip="http://127.0.1.1:8081/UniPiCommandService">
<soapenv:Header/>
<soapenv:Body>
<unip:SoapCommandInputList>
<!--1 or more repetitions:-->
<single_command>
<device_circuit>1</device_circuit>
<device_type>relay</device_type>
<!--1 or more repetitions:-->
<property_item>
<property_name>value</property_name>
<property_value>"0"</property_value>
</property_item>
</single_command>
<single_command>
<device_circuit>2</device_circuit>
<device_type>relay</device_type>
<!--1 or more repetitions:-->
<property_item>
<property_name>value</property_name>
<property_value>"1"</property_value>
</property_item>
</single_command>
<single_command>
<device_circuit>3</device_circuit>
<device_type>relay</device_type>
<!--1 or more repetitions:-->
<property_item>
<property_name>value</property_name>
<property_value>"1"</property_value>
</property_item>
</single_command>
</unip:SoapCommandInputList>
</soapenv:Body>
</soapenv:Envelope>
WebSocket
WebSocket is a duplex communication protocol for TCP. Our implementation is based on sending a stream of event messages to the server, which notify the user of status changes to the internal devices.
All EVOK messages over the websocket protocol are sent in standard JSON string format, e.g. one would send {"cmd":"set", "dev":"relay", "circuit":"1", "value":"1"} to set the Relay 1 to on.
There are three different 'commands' available over WebSocket: 'all', 'filter', 'set'
- 'all', which has no arguments and will return a list of all devices in the same format as the Get Complete State endpoint;
- 'filter', which has one argument ("devices" which is an array of device types to filter for, e.g. {"cmd":"filter", "devices":["ai", "input"]}) and will limit the list of devices which should send events;
- 'set', which has three arguments ("dev" which is a device type string, "circuit", which is a device circuit string and "val" which is the desired value to set e.g. {"cmd":"set", "dev":"relay", "circuit": "1_01", "value":1}) and sets a specific device property to a specified value
To recieve the event messages register your client at the URL ws://your.unipi.ip.address/ws, (the Websocket Handshake/Upgrade endpoint). Once the connection is established you can send the commands specified above to your device.
Please look through the Sample Web Interface file 'wsbase.js' in the www/js/ folder for a more extensive example of WebSocket use.
Example Python application using WebSocket
import websocket
import json
import logging
logging.basicConfig()
# Replace this with your Neuron IP Address
url = "ws://127.0.0.1:8080/ws"
def on_message(ws, message):
obj = json.loads(message)
for single_obj in obj:
dev = single_obj['dev']
circuit = single_obj['circuit']
value = single_obj['value']
print "Value: " + str(value) + " Device: " + str(dev) + " Circuit: " + str(circuit)
print message
def on_error(ws, error):
print error
def on_close(ws):
print "Connection closed"
def on_open(ws):
# Turn on filtering
ws.send(json.dumps({"cmd":"filter", "devices":["ai", "input"]}))
# Turn on DO 1.01
ws.send(json.dumps({"cmd":"set", "dev":"relay", "circuit": "1_01", "value":1}))
# Query for complete status
ws.send(json.dumps({"cmd":"all"}))
#receiving messages
ws = websocket.WebSocketApp(url, on_open = on_open, on_message = on_message, on_error = on_error, on_close = on_close)
ws.run_forever()
```python
1Wire Devices
1Wire is a universal protocol for communication with a variety of standardised devices. Unfortunately, the individual devices do not have a common data framework, and require individual handling to behave correctly. For this reason EVOK supports only the following 1Wire devices:
- DS18B20
- DS18S20
- DS2438
- DS2408
- DS2406
- DS2404
- DS2413
Some of these device (2408, 2406, 2404 and 2413) are only control chips for additional hardware (relays, digital inputs) and as such require individual configuration. You can find more details regarding this in the Configuration section.
Extensions and custom ModBus devices
EVOK is able to communicate over serial lines with external slave devices which support the Modbus RTU protocol. Modbus is a popular protocol for mid-latency device control, particularly in the building automation sector.
For Neuron Extensions this means their internal devices will be available much the same as they would if they were included in the control unit, albeit with lower latency. The device circuits will be prefixed with UART_[UART_ADDRESS]_[DEVICE_ID].
Hardware Definition Files
Hardware definitions files specify the Modbus devices supported by EVOK. Notably, this does not include 1Wire devices and the UniPi 1.1 boards. The files can be found in the '/etc/hw_definitions' folder, and use the YAML data format.
The files consist of two sections "modbus_register_blocks" and "modbus_features". Each device also has a specified "type", which is the name it's referred by in other parts of EVOK.
modbus_register_blocks
The modbus_register_blocks top-level-key is an array of objects representing groups of Modbus registers. Each group is then read in a single Modbus message and cached by EVOK. The fewer groups are defined the less the communication bus will be congested. Modbus groups have the following properties:
- board_index
- This key is used primarily for SPI communication. In SPI it serves as the chipselect value, and specifies which internal device group/PCB the register group refers to. Use value of 1 for UART devices
- start_reg
- The first register of the Modbus group, e.g. for a device with a group of registers 0-20 one would use 0, as that is the first register of the group.
- count
- The number of registers within the group. Each group is sequential; it is not possible to "skip" a register within a single group. To read the the registers 0-20 one would use the value of 21 (as Modbus register addresses are 0-indexed).
- frequency
- This key defines how many cache read cycles must pass before the group is read. The value of 1 means that the group is read every cycle; higher values of n mean that the group will be read every nth cycle.
- type (optional, new from v.2.0.7b)
- This key determines whether the register block exists in the "input" or "holding" register namespace. As such it can have the following values "input" and "holding". In its absence the value of holding is assumed.
modbus_features
The modbus_features top-level-key is an array of objects representing internal devices which are contained within the modbus groups above.
There are several device types, however the only type that can be safely used in custom hardware definitions is the REGISTER type, which is described further below. The other device types each have a specific format, which can be inferred from the hardware definitions which are supplied with EVOK, however we do not support the use of these device types in custom definitions.
REGISTER internal devices act in a manner similar to the modbus_register_blocks above. Each Modbus register group should ideally have a corresponding REGISTER internal device. The REGISTER internal devices have the following format:
- type
- This key is used to determine the internal device type. Use the value of REGISTER here.
- major_group
- This key should be the same as the corresponding board_index key above. Use the value of 1 for UART devices.
- count
- The number of registers within the group. This key should be the same as the corresponding count key above.
- start_reg
- The first register of the Modbus group. This key should be the same as the corresponding start_reg key above.
- reg_type (optional, new from v.2.0.7b)
- This key determines whether the register exists in the "input" or "holding" namespace. As such it can have the following values "input" and "holding". In its absence the value of holding is assumed.
External websites
Neuron datasheets
Neuron datasheets can be found on our corporate file server.
Where can I buy a Neuron?
You can purchase Neuron devices from our e-shop, or from any of our numerous retail partners.
Further documentation
You can find more details regarding Neuron and UniPi at our company website.
It includes a full-featured public forum, an e-shop where you can purchase more of our devices, and extensive documentation.
JSON Remote-Procedure Calls
Python using JsonRPC
You can also control the UniPi using the jsonrpclib Python library. See the list of all the available methods below.
from jsonrpclib import Server
s=Server("http://your.pi.ip.address/rpc")
s.relay_set(1,1)
s.relay_get(1)
s.relay_set(1,0)
s.relay_get(0)
s.ai_get(1)
Perl using JsonRPC
A simple example of controlling the UniPi via RPC:
use JSON::RPC::Client;
my $client = new JSON::RPC::Client;
my $url = 'http://your.pi.ip.address/rpc';
$client->prepare($url, ['relay_set']);
$client->relay_set(1,1);
There is also a websocket client library for Perl to get more control.
List of available devices:
relay- relayinputordi- digital inputai- analog inputao- analog outputee- onboard eepromsensor- 1wire sensor- the rest can be found in devices.py
List of available methods:
- Digital Inputs
input_get(circuit)- get all information of input by circuit numberinput_get_value(circuit)- get actual state f input by circuit number, returns 0=off/1=oninput_set(circuit)- sets the debounce timeout
- Relays
relay_get(circuit)- get state of relay by circuit numberrelay_set(circuit, value)- set relay by circuit number according value 0=off, 1=onrelay_set_for_time(circuit, value, timeout)- set relay by circuit number according value 0=off, 1=on for time(seconds) timeout
- Analog Inputs
ai_get(circuit)- get value of analog input by circuit numberinput_get
- Analog Output
ao_set_value(circuit, value)- set the value(0-10) of Analog Output by circuit number
- 1-Wire bus
owbus_scan(circuit)- force to scan 1Wire network for new devices
- 1-Wire sensors
sensor_get(circuit)- returns all information in array [value, is_lost, timestamp_of_value, scan_interval] of sensor by given circuit or 1Wire addresssensor_get_value(circuit)- returns value of a circuit by given circuit or 1Wire address
More methods can be found in the source files evok.py and owclient.py.
json
This endpoint will return a polymorphic array of device states. The following state models are included:
- 1Wire Device model
- Analog Input state model
- Analog Output state model
- Input state model
- Relay state model
- Register state model
- Neuron state model
- UART state model
- ULED state model
- Watchdog state model
- WiFi state model (if enabled)
rest
rpc
UniPiQueryService
SOAP endpoints require the internal SOAP server to be enabled!
The internal SOAP server **must*** use it's own port, not the API port!*
SOAP endpoints require the internal SOAP server to be enabled!
The internal SOAP server **must*** use it's own port, not the API port!*
UniPiCommandService
SOAP endpoints require the internal SOAP server to be enabled!
The internal SOAP server **must*** use it's own port, not the API port!*
SOAP endpoints require the internal SOAP server to be enabled!
The internal SOAP server **must*** use it's own port, not the API port!*
bulk
The Bulk API is used for batch communication with EVOK using JSON objects. It should be used primarily for performing commands or queries on more than one subdevice, for which it will have considerably higher reaction time and lower latency than any other method exposed by EVOK.
For more details on how to use the bulk API please see the notes below, or the Bulk API section on the Introduction page.