Overview
Device is physical device or Node.js process, internally using values that needs to be accessed and/or modified from other processes. It can be defined and configured using libraries appropriate for platform you are going to use.

Device can use fixed configuration or built-in discovery service to figure out where should it connect to, or how to reestablish broken connection.

When device connects server for the first time, server generates unique identifier (UUID). Device stores it in permanent memory and use to identify itself from now on. Basing on what was defined in code, device generates manifest and send it to server as stringified JSON object. Manifest contains device id, name, declared Gate Values etc.

Once connection is established, device can use Server Storage to save or retrieve static data (like configuration params, persistent states etc.)

Some implementation details may differ between libraries. See Arduino and Node.js sections for library-specific information.

Common device properties:
name - string that will be displayed in user interface as device name
group - string defining which group device initially belongs to
info - string reserved for user-defined information on this device (i.e. custom id to assist finding specific device within controller's model). Not used by any system component
factory - object containing factory methods to generate Gate Values for this device
ServerStorage - object containing methods to interact with Server Storage
start() - method starting device
stop() - method stopping device
isReady() - returns true if device is connected to server, false otherwise
Gate Values
Gate value is a data wrapper able to synchronize wrapped value with other system components interacting with it. Gate Values can be created both by Node.js and Arduino device libraries. There are several data types available. All of them are created through factory object and have following common properties:
id - automatically assigned string that uniquely identifies specific Gate Value within device
direction - enum (Node.js) or string (Arduino) defined during creation of Gate Value. Can be "output" (value is read-only for other system components) or "input" (can be modified by other system components)
type - read-only string assigned by factory. Identifies type of data
value - current value (data type depends on type of Gate Value). Is automatically updated when other system component updates it and send when device use setValue method
onRemoteUpdate - function that will be called whenever other system component modifies value
subscribed - read-only boolean informing if value is subscribed by any other system component
valueName - string that will be displayed in user interface as value name
visibility - string defining where user interface should initially display this Gate Value. Can be "main" (default option - displayed on devices dashboard), "settings" (displayed in settings modal) and "hidden" (user interface will not display this value on devices dashboard). Data pipe can be created regardless of visibility field value
info - string reserved for user-defined information on this Gate Value (i.e. custom id to assist finding specific value within controller's model). Not used by any system component
Each Gate Value type have it's own optional configuration properties. Below is summary of available data types:
GateBoolean
labelTrue - string displayed by user interface when value is true
labelFalse - string displayed by user interface when value is false
isButton - if set to true, user interface will display this value as button (value becomes true when button is pressed, false when released)
GateNumber
(applies to both integer and float numeric types)
minimum - minimum value that can be set on this Gate Value
maximum - maximum value that can be set on this Gate Value
If both minimum and maximum are set, user interface displays value as slider instead of ordinary number
GateString
minimumLength - hint for user interface on how much space should it reserve to display this string
GateSelect
(value of GateSelect is an index of selected option from values array)
values - array of strings (names of options)
nothingSelectedLabel - name for "undefined" option selected
Server Storage
Server Storage is built-in persistence module that allows you to store some data centrally, within Local Server. Data format for stored information is string. Default location to store data for device within Local Server root directory is ./ServerStorage/<device id>. Below is summary of methods within ServerStorage object to interact with Server Storage:
get(key: string, directory?: string)
Used to retrieve stored data
key - name of file to read from
directory (optional) - custom file location. If not specified, file will be retrieved from default location
set(key: string, value: string, directory?: string)
Used to write data to Local Storage (overwrites previous data if file exists)
key - name of file to write to
value - data to be stored
directory (optional) - custom file location. If not specified, file will be written to default location
append(key: string, value: string, directory?: string)
Used to write data to Local Storage (appends to previous data if file exists)
key - name of file to write to
value - data to be appended
directory (optional) - custom file location. If not specified, file will be written to default location
remove(key?: string, directory?: string)
Used to erase data from Local Storage
key (optional) - name of file to remove. If not specified, entire default directory will be removed
directory (optional) - custom file location. If not specified, file will be removed from default location
Server Storage Example
See more videos on our YouTube channel