unipi-evok v0.1.1
UniPi Evok
Node JS wrapper for UniPi EVOK REST and WebSocket API as documented at EVOK Documentation.
Note this only supports EVOK API v2.0
Installation
npm i unipi-evok
Usage
A number of examples can be found within the examples directory.
At it's most basic level we can connect to the UniPi using:
const evok = require('../lib/api')
const unipi = new evok({
host: 'IP_ADDRESS',
restPort: 80
wsPort: 8080
})
unipi
.on('connected', () => {
// logic once connected here
})
.connect()
Properties
host
- DNS hostname or IP addressrestPort
- Port of EVOK REST API - Default is 80wsPort
- Port of EVOK WebSocket API - Default is 8080
Client Methods
Note internal methods are not documented.
connect()
Fetch a list of all devices to be stored under unipi.devices()
then connect to the WebSocket server on the UniPi.
Example
unipi.connect()
close()
Example
unipi.on('connected', () => {
// logic when connected
// now close the connection
unipi.close()
})
restUrl()
Return a string of the base REST URL.
Example
unipi.restUrl() // http://localhost:80
wsUrl()
Return a string of the base WebSocket URL.
Example
unipi.wsUrl() // http://localhost:8080
get(url)
Return a promise after performing a GET request.
Arguments
url
- Relative URL on the EVOK API
Example
unipi.get('/rest/all')
.then((devices) => {
// devices = array of objects
})
post()
TODO
send(message)
Send JSON object via the WebSocket
Arguments
message
- JSON object
Example
unipi.send({
cmd: 'set',
dev: 'relay',
circuit: '2_01',
value: '1'
})
API Methods
This is the default class which extends client.js.
connect()
Extends the client.js connect method by first fetching a list of devices via the REST API.
devices()
Example
unipi.devices() // array of objects returned from the API
device(dev, circuit)
Find a device from the list of devices
Arguments
dev
- Device as defined on EVOK API, egao
circuit
- Circuit as defined on EVOK API
Example
let device = unipi.device('relay', '2_05')
inputs()
Digital inputs filtered from the device list.
Example
unipi.connect()
input(circuit)
TODO
relays()
Relays filtered from the device list.
Example
unipi.relays() // array of objects
relay(circuit, state)
Either get the current state of the relay or set a new state. Note this will not return the state when setting.
Arguments
circuit
- Circuit as defined on the APIstate
- Optional state of true/false
Examples
Get the state
unipi.relay('2_01') // true/false
Set the state
unipi.relay('2_01', true)
digitalOutputs()
Digital outputs filtered from the device list.
Example
unipi.digitalOutputs() // array of objects
digitalOutput(circuit, state)
Either get the current state of a digital output or set a new state. Note this will not return the state when setting.
Arguments
circuit
- Circuit as defined on the APIstate
- Optional state of true/false
Examples
Get the state
unipi.digitalOutput('2_01') // true/false
Set the state
unipi.digitalOutput('2_01', true)
leds()
LEDs filtered from the device list.
Example
unipi.leds() // array of objects
led(circuit, state)
Either get the current state of a LED or set a new state. Note this will not return the state when setting.
Arguments
circuit
- Circuit as defined on the APIstate
- Optional state of true/false
Examples
Get the state
unipi.led('2_01') // true/false
Set the state
unipi.led('2_01', true)
analogueInputs()
Analogue inputs filtered from the device list.
Example
unipi.analogueInputs() // array of objects
analogueInput()
TODO
analogueOutputs()
Analogue outputs filtered from the device list.
Example
unipi.analogueOutputs() // array of objects
analogueOutput(circuit, state)
Either get the current state of an analogue output or set a new state. Note this will not return the state when setting.
Arguments
circuit
- Circuit as defined on the APIstate
- Optional value between 0-10 (no validation on this)
Examples
Get the state
unipi.analogueOutput('2_01') // true/false
Set the output to 5v
unipi.analogueOutput('2_01', 5)
owDevices
TODO
set(dev, circuit, state)
Shorthand method for setting values on the WebSocket API.
Arguments
dev
- Dev as defined on the APIcircuit
- Circuit as defined on the APIvalue
- Boolean or float
Example
Set a relay on
unipi.set('relay', '2_01', true)
Events
Module events
Created by this module.
connect
Emitted on connect of the WebSocket.
connectFailed
Emitted when we failed to connect to the WebSocket
message
When any message is received via the WebSocket.
Example
unipi.on('message', (message) => {
// message = [{
// modes: [ 'Voltage', 'Current', 'Resistance' ],
// value: 2.1998616187837583,
// glob_dev_id: 1,
// dev: 'ao',
// circuit: '1_01',
// unit: 'V',
// mode: 'Voltage'
// }]
})
error
Emitted when theres an error.
close
Emitted when the WebSocket connection is closed.
EVOK Events
By default we emit events based on the type of device which has made a change.
Arguments
device
- Latest data emitted from EVOK APIdevice
- Last stored data fromdevices()
prior to event, note this may be null in some cases
Note these do not necessarily mean the value changed, nor should they be considered 100% reliable as race conditions may occur.
Example
unipi.on('message', (device, devicePrevious) => {
console.log(device) // latest data from the EVOK API
console.log(devicePrevious) // null or previous data stored in our local array of devices prior to message
})
input
When a digital input message is received.
relay
When a relay message is received.
digitalOutput
When a digital output message is received.
ai
When analogue input message is received.
ao
When analogue output message is received.
led
When LED message is received.
wd
When a watchdog message is received
neuron
uart
wifi
Notes
This is currently a work in progress.