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 address
• restPort - Port of EVOK REST API - Default is 80
• wsPort - 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, eg ao
• 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 API
• state - 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 API
• state - 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 API
• state - 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 API
• state - 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 API
• circuit - Circuit as defined on the API
• value - 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 API
• device - Last stored data from devices() 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.

Licence

The MIT License (MIT)