4 - Functionalities and configuration - Spoony 1.5 – DotVision Energy

Spoony configuration is customized through XML files residing into the microSD card accessible from the device front panel. See paragraph 2.4.2 for details on how to access the microSD card.

These files can be modified in two ways:

Removing the microSD card from the device and inserting it into a computer with suitable microSD reader, or SD reader and microSD adapter,
Once device is accessible over the network, files can be modified from the Web interface directly. See paragraph 10 for details on how to modify device configuration through the Web interface.

To edit XML files onto a computer, we recommend the use of Notepad++ software.

Device’s microSD card contains the following directories:

certificates: certificate files approved for TLS connections,
db: local storage directory, files in this directory should not be modified,
firmware: firmware directory. New device firmware must be placed into this directory to update the device to a new software version. See paragraph 12 for details on firmware update procedure,
logs: device logs directory. This directory is mainly for use by DotVision to identify device issues,
measurements: local storage directory containing CSV files when CSV data storage is enabled,
system: device configuration resides within this directory,
temp: temporary storage,
usr: temporary storage,
www: Web interface content directory.

In following paragraphs, all file paths are given from microSD card’s root path.

Spoony functioning is based on multiple Services, each assuring a core functionality of the device. Device Service (main Service) is responsible for determining which Services to run at startup. Each Service has its own configuration directory, containing at least a serviceSettings.xml file.

For example, file system/services/Device/serviceSettings.xml contains Device Service configuration, while system/services/Device/Automation/serviceSettings.xml contains Automation Service configuration, which is a sub-service of Device Service.

All Services within the device are sub-Services of the Device Service, thus all configuration files are contained under the system/services/Device directory.

Services tree is best described by the following list:

Device: main Service, holds all device Services,
- Automation: Automation Service, provide device measurements (datapoints),
- Console: console Service, provide local and remote management functionalities,
- HttpServer: HTTP Web server Service,
- JsonRpc: JSON-RPC Service, providing remote procedure call,
- ModbusSerial: MODBUS RS485 server functionality,
- ModbusTCP: MODBUS TCP server functionality,
- MqttClient: MQTT client functionality,
- NetworkManager: network management and configuration,
- Ntp: Network Time Protocol time synchronization Service,
- ODM: data sampling and sending/storing, rely on two sub-Services:
  - ODMDataChunk: sampling Service,
  - ODMWebPush: storing or sending Service,
- TimeService: time management Service.

The following paragraphs describe configuration options for each Service.

Default configuration shown here may differ on your specific device if you requested pre-configuration by DotVision according to your requirements.

2 Device service

Device Service is the main Service of the device. This is where device global configuration is defined, and where other Services are enabled/disabled.

Configuration file: system/services/Device/serviceSettings.xml

Link

Configuration file organization:

Figure 1 – Device Service configuration file organization

Device options

Figure 2 – Device Service – Device options

Device characteristics can be configured from this section. Most of these characteristics are for local display onto the Web interface only. Only option friendlyName must be configured as this is the main device identifier used by other Services.

In particular, this is the device identifier sent to the remote server when ODM Service is configured for data sending, and it is also the prefix used for CSV files when ODM Service is configured for CSV data storage.

2.1 Services list

Services list contains a few settings which should not be modified. Settings which can be modified are indicated in yellow below:

Figure 3 - service Device – Services List

3 Network

Device network configuration is done from the NetworkManager Service configuration file

Configuration file: system/services/Device/NetworkManager/serviceSettings.xml

Link

Configuration file organization:

Figure 4 – NetworkManager configuration file organization

Note: wifi and wifi-ap sections may not be present in the configuration file if your device is not equipped with Wi-Fi extension.

3.1 Ethernet network configuration

Device is configured in DHCP mode by default. In this mode, IP address, Network Mask, Gateway address and DNS servers address are obtained automatically from a DHCP server. This mode is enabled as shown below:

Figure 5 – Ethernet interface DHCP configuration

To configure interface in static IP mode, the following configuration sample must be used and completed according to your network requirements:

Figure 6 – Ethernet interface static IP configuration

Please note that the device supports only IPv4 functionality at this time.

DNS servers can be omitted if your device is not using dynamic name resolution (e.g., when device is only performing local storage or sending data to a server identified directly by its IP address).

3.2 Wi-Fi network configuration

This section is only applicable to devices with Wi-Fi option.

1.3.2.1.1 Wi-Fi access point

Device has a built-in Wi-Fi AP functionality which works straight out of the box. After power-up, the device will bring a dedicated Wi-Fi AP up.

By connecting onto this access point, you should be directly redirected to the device’s Web interface home page. If it is not the case, open a Web browser and access the following address:

http://me.iofdevices.com

The Wi-Fi AP functionality is using the following network settings by default. If this configuration is incompatible with your other network interfaces (e.g., using the same subnet), you can modify those default settings from the NetworkManager configuration relevant section shown below:

Figure 7 – Wi-Fi AP interface configuration

You can also activate Wi-Fi security onto the access point by configuring a passphrase as described. Note that passphrase MUST be at least 8 characters long.

Wi-Fi AP can be completely disabled by removing the whole configuration section shown above.

3.2.2.1 Wi-Fi station configuration through Wi-Fi access point

Connection to your LAN through the Wi-Fi interface can be configured directly from the device’s Web interface, accessed through the Wi-Fi AP, especially if your LAN is using DHCP.

In this case, please refer to paragraph 5.10.1.1 for detailed procedure regarding Wi-Fi configuration. If you do not have DHCP functionality on your Wi-Fi network, we recommend using manual configuration as show in next paragraph.

3.2.2.2 Wi-Fi station configuration through configuration file

Wi-Fi STA configuration is made from the following section of the NetworkManager configuration file as shown below:

Figure 8 – Wi-Fi station configuration in DHCP mode

Indicate you Wi-Fi AP name and passphrase as required. For connecting to unsecured Wi-Fi network, passphrase can be left empty.

If your network does not provide DHCP functionality, or if you want to set static IP settings, set dhcp setting to false and indicate your network specific settings as shown below:

Figure 9 – Wi-Fi station configuration in static IP mode

4 NTP Service configuration

NTP (Network Time Protocol) Service provide time synchronization functionality. When enabled (default), your device will perform NTP requests on a regular basis to resynchronize its system clock.

Configuration file: system/services/Device/Ntp/serviceSettings.xml

Link

Configuration file organization:

Figure 10 – Ntp Service configuration

5 Automation Service configuration

5.1 Automation Service overview

Automation Service is responsible for holding and organizing device measurements, as well as measurements from external devices read through MODBUS client functionality.

Configuration File: system/services/Device/Automation/serviceSettings.xml

Link

Configuration File organization:

Figure 11 – Automation service configuration file organization

All measurements (values) available through Spoony are referred to as DataPoints. A DataPoint is a primitive object containing a Value, an Index, and a Timestamp.

Automation Service relies on two base elements: Automation Units and Automation Index.

An Automation Unit is a base element providing a list of DataPoints. Multiple Units can be configured and declared as shown in the following paragraphs.

The Automation Index is a tree of aliases used to organize datapoints from the different Units inside a single arborescence. Its syntax is described in paragraph 4.5.7.

Spoony always contains two base Automation Units:

ade7758: this Unit provides energy measurement from the internal ADE7758 energy metering IC,
outputs: this Unit provides relays outputs binary DataPoints to allow writing outputs states.

Other Automation Units are also available in option:

tic: this Unit provides DataPoints read from the TIC input wired to an external energy meter (see paragraph 4 for details regarding the TIC input),
soft: this Unit provides DataPoints computed in real-time from other available DataPoints and can perform averaging, minimum, and maximum computing,
modbus: this Unit provides DataPoints read from external devices through MODBUS protocol (RS485 or TCP).

Configuration options of each Unit type is detailed in following paragraphs.

5.2 ADE7758 Automation Unit

This Unit provides measurements taken from the internal ADE7758 energy metering IC. This Unit does not accept any setting.

The Unit must be declared as follow in the <units> section:

Figure 12 – ADE7758 Automation Unit configuration

The ADE7758 metering IC calibration can be modified from the Web interface only. Please refer to paragraph 5.10.6 for details on how to modify device calibration.

Once enabled, this Unit will expose the following DataPoints:

Path	Description	Unit
units/ade7758/FREQ	Line frequency, measured on L1	Hz
units/ade7758/IRMSA	RMS Current phase L1	A
units/ade7758/IRMSB	RMS Current phase L2	A
units/ade7758/IRMSC	RMS Current phase L3	A
units/ade7758/VRMSA	RMS Voltage phase L1	V
units/ade7758/VRMSB	RMS Voltage phase L2	V
units/ade7758/VRMSC	RMS Voltage phase L3	V
units/ade7758/WATTA	Active Power phase L1	W
units/ade7758/WATTB	Active Power phase L2	W
units/ade7758/WATTC	Active Power phase L3	W
units/ade7758/VARA	Reactive Power phase L1	VAR
units/ade7758/VARB	Reactive Power phase L2	VAR
units/ade7758/VARC	Reactive Power phase L3	VAR
units/ade7758/VAA	Apparent Power phase L1	VA
units/ade7758/VAB	Apparent Power phase L2	VA
units/ade7758/VAC	Apparent Power phase L3	VA
units/ade7758/PFA	Power Factor phase L1
units/ade7758/PFB	Power Factor phase L2
units/ade7758/PFC	Power Factor phase L3
units/ade7758/WATTHRA	Active Energy phase L1	Wh
units/ade7758/WATTHRB	Active Energy phase L2	Wh
units/ade7758/WATTHRC	Active Energy phase L3	Wh
units/ade7758/VARHRA	Reactive Energy phase L1	VARh
units/ade7758/VARHRB	Reactive Energy phase L2	VARh
units/ade7758/VARHRC	Reactive Energy phase L3	VARh
units/ade7758/VAHRA	Apparent Energy phase L1	VAh
units/ade7758/VAHRB	Apparent Energy phase L2	VAh
units/ade7758/VAHRC	Apparent Energy phase L3	VAh
units/ade7758/WATT	Total Active Power	W
units/ade7758/VAR	Total Reactive Power	VAR
units/ade7758/VA	Total Apparent Power	VA
units/ade7758/WATTHR	Total Active Energy	Wh
units/ade7758/VARHR	Total Reactive Energy	VARh
units/ade7758/VAHR	Total Apparent Energy	VAh

Figure 13 – ADE7758 Automation Unit available DataPoints

5.3 Outputs Automation Unit

This Unit provide access to the three open-drain outputs of the device through binary DataPoints. This Unit does not accept any setting.

The Unit must be declared as follow in the <units> section:

Figure 14 - Automation unit Outputs configuration

Once enabled, this Unit will expose the following DataPoints:

Path	Description	Unit
units/outputs/RELAYA	Output OUTA status	Hz
units/outputs/RELAYB	Output OUTB status	A
units/outputs/RELAYC	Output OUTC status	A

Figure 15 – Output Automation Unit available DataPoints

5.4 TIC Automation Unit

This Unit provide access to data red through the TIC interface of the device. TIC bus uses a serial protocol where data is sent in ASCII format. Please refer to relevant documentation for details regarding the protocol.

TIC Automation Unit requires a few settings as shown below:

Figure 16 – TIC Automation Unit Configuration

The list of DataPoints to be extracted from the incoming TIC frames must list all values which should be read. Values not appearing in this list will be ignored.

For each DataPoint, you must specify:

name: the local name of the DataPoint,
tag: the matching TAG in incoming TIC frames,
type: the type of data. Only uint64, uint32 and enum are supported,
values: only if type is enum, list the possible values in the incoming frames. The effective DataPoint value will be the index of the read value in this list, or -1 if the received value does not exist in the list.

Once enabled, the exposed DataPoint list will depend on DataPoint configuration of the Unit. For the above example:

Path	Description	Unit
units/tic/ADCO	ADCO
units/tic/OPTARIF	OPTARIF
units/outputs/BASE	BASE

…

5.5 Soft Automation Unit

This Unit provides computing functionalities, allowing to perform arithmetic operations between DataPoints, as well as averaging and minimum/maximum values computing over configurable periods.

Sample configuration:

Figure 17 – Soft Automation Unit configuration

Unit settings are:

period: the period, in ms, between two refresh of output values. The computing algorithm is performed once every period ms over the whole list of DataPoints. Most DataPoints are updated every 1s, so setting the period to 1s ensure all updates to DataPoints will be effectively reflected into computed output DataPoints,
offset: the time in ms to wait, after the round period (e.g., computation will be performed at 00:00:00.1, 00:00:00.2 etc.) for the input DataPoints to be up to date. Recommended setting for this value is about 1/10th of the period.

For each DataPoint entry, the following parameters are available:

name: Unit datapoint name. Output DataPoint will be available as units/soft/name,
value: arithmetic expression. Allows to take another DataPoint value (from any other unit) with DP( {Datapoint path} ),
filter: type of filtering operation. Valid values are avg (average), min (minimum), max (maximum),
sample: number of samples used for filtering operation. Setting samples to 1 effectively disables filtering as output value is updated at each sampling,
unit: Output DataPoint Unit property.

5.6 Modbus master (client) Unit

This Unit allows to retrieve data from external devices into the Spoony. Once retrieved, those values become Spoony DataPoints which can be used for computation (Soft Unit) of data sending/storage through ODM Service.

Warning: When the RS485 bus is used for MODBUS master functionality as described below, it cannot be used for MODBUS slave and the ModbusSerial (MODBUS slave) Service MUST be disabled for proper operation. MODBUS TCP functionality, however, can be simultaneously used for master and slave functions.

This paragraph covers Modbus master Unit configuration which is based on MODBUS Device Models and Update Policies files. Please refer to section 4.6 for details regarding Device Models and Update Policies files syntax and creation.

Modbus Unit requires configuration of the underlying transport first. This configuration entry goes under the <transports> configuration section and depends on the desired transport type (RS485 or TCP).

For RS485, the transport entry is configured as follows:

Figure 18 – Modbus RS485 Transport configuration

Note: Only a single RS485 transport can be declared.

For TCP, the transport entry is configured as follows:

Figure 19 – Modbus TCP Transport configuration

Once the transport section is correctly configured, the Modbus Unit can be configured and linked to the underlying transport section.

A single Modbus Unit communicates with multiple slaves and is configured as follows:

Figure 20 – Modbus Unit configuration

In the case of TCP transport, each Modbus Unit can communicate with a single host. If you need to communicate with different hosts, you will need to declare as many Transports and Modbus Units as required. The destination field should be set to 0 in most case for MODBUS TCP unless the target device has gateway functionalities.

Each declared Transport and ModbusUnit MUST have a unique name.

The DataPoints list exposed by the Unit will depend on the Unit configuration and Device Model.

Each Device Model declares a list of DataPoints identified by a unique name. Each Modbus Unit will expose those DataPoints prefixed with MODBUS destination (address) as follows:

Figure 21 – Modbus Datapoint Name format

5.7 Automation Space Index

Automation Space <index> section allows to identify all DataPoints from the Units through a customized path (Alias).

Addressing of DataPoints can be made using either their default path (units/{unit name}/{datapoint name}) or any Alias path declared into the Index.

The Index is a multi-level tree allowing to organize DataPoints easily. Default Automation Space index is shown below. DataPoints from other Units can be added to the Index as required by the end user. The Index is mainly used to organize DataPoints browsing from the Web interface. It is defined in the following manner:

Figure 22 – Default Automation Space Index configuration

6 MODBUS configuration

This section covers in detail the different MODBUS functionalities of the device. This includes MODBUS master and slave functions, over RS485 and TCP.

6.1 Overview of MODBUS functionalities

L’appareil offre 2 modes d’opération :

Modbus Slave (Server) : Ce mode permet l’accès aux DataPoints de l’appareil via Modbus RS485 ou TCP.
Modbus Master (Client) : Ce mode permet d’accéder aux données d’appareils externe compatibles Modbus pour permettre l’agrégation de données dans le Spoony.

Le mode Modbus Master est configuré depuis le service Automation comme décrit dans le paragraphe 1.5.6. Le paragraphe 0 décrit la création de fichier de modèles et de politique de mise à jour.

6.2 Modbus Slave (Server)

MODBUS slave function is available through RS485 and TCP. While both functionalities are covered by a different Device Service, those Services are very similar. This section covers similar portions of the two configuration files.

Configuration files: system/services/Device/ModbusTCP/serviceSettings.xml and system/services/Device/ModbusSerial/serviceSettings.xml

Link1 Link2

Configuration files organization:

Figure 23 – Modbus slave configuration file organization

The device’s registers mapping (<model> section) is similar for both TCP and RS485 transport and defines the mapping between exposed MODBUS registers and Automation Space DataPoints.

All available DataPoints can be exposed through MODBUS slave, including DataPoints red from other MODBUS devices, and computed DataPoints, thus offering a lot of flexibility.

The <model> section is organized as follows:

Figure 24 - Default MODBUS Device Model configuration

The Model makes a distinction between Holding registers (Read/Write capability), Input registers (Read only), Coil registers (Read/Write binary) and Discrete Inputs (Read only binary).

Each entry of type Holding or Input has the following parameters:

address: the MODBUS register address,
size: the size, in number of consecutive 16 bits MODBUS registers. All Spoony DataPoints are floating-point type and are mapped onto two consecutive registers, except for binary DataPoints (Relays outputs),
datapoint: path to the matching DataPoint, addressed by alias or by root address.

Each entry of type Coil or Discrete Input has the following parameters:

address: the MODBUS coil/discrete input address,
datapoint: path to the matching DataPoint, addressed by alias or by root address.

For compatibility reasons, while the MODBUS map may be modified by the user, DotVision recommends keeping the default MODBUS map as it is, and adding additional entries as required, for exposing additional DataPoints or creating DataPoints group of interest on consecutive addresses for example.

6.3 4.6.3 MODBUS slave (server) RS485 specificities

MODBUS slave RS485 specific settings are described below. These settings only apply to ModbusSerial Service:

Figure 25 – MODBUS slave RS485 specific configuration

6.4 MODBUS slave (server) TCP specificities

MODBUS slave TCP specific settings are described below. These settings only apply to ModbusTCP Service:

Figure 26 – MODBUS slave TCP specific configuration

6.5 Default MODBUS Table

This table describes the default MODBUS mapping of the device:

Input registers
Register address	Register name	Description
0x0000	FREQ	Line Frequency (Hz)
0x0002	VRMSA	VRMS Phase L1 (Vrms)
0x0004	VRMSB	VRMS Phase L2 (Vrms)
0x0006	VRMSC	VRMS Phase L3 (Vrms)
0x0008	IRMSA	IRMS Phase L1 (Arms)
0x000A	IRMSB	IRMS Phase L2 (Arms)
0x000C	IRMSC	IRMS Phase L3 (Arms)
0x000E	WATTA	Active power Phase L1 (W)
0x0010	WATTB	Active power Phase L2 (W)
0x0012	WATTC	Active power Phase L3 (W)
0x0014	WATT	Total Active Power (W)
0x0016	VAA	Apparent power Phase L1 (VA)
0x0018	VAB	Apparent power Phase L2 (VA)
0x001A	VAC	Apparent power Phase L3 (VA)
0x001C	VA	Total Apparent Power (VA)
0x001E	VARA	Reactive power Phase L1 (VAR)
0x0020	VARB	Reactive power Phase L2 (VAR)
0x0022	VARC	Reactive power Phase L3 (VAR)
0x0024	VAR	Total Reactive Power (VAR)
0x0026	PFA	Power Factor Phase L1
0x0028	PFB	Power Factor Phase L2
0x002A	PFC	Power Factor Phase L3
0x002C	AWATTHR	Active Energy Phase L1 (WH)
0x002E	BWATTHR	Active Energy Phase L2 (WH)
0x0030	CWATTHR	Active Energy Phase L3 (WH)
0x0032	WATTHR	Total Positive Active Energy (WH)
0x0034	AVAHR	Apparent Energy Phase L1 (VARH)
0x0036	BVAHR	Apparent Energy Phase L2 (VARH)
0x0038	CVAHR	Apparent Energy Phase L3 (VARH)
0x003A	VAHR	Total Apparent Energy (VARH)
0x003C	AVARHR	Reactive Energy Phase L1 (WH)
0x003E	BVARHR	Reactive Energy Phase L2 (WH)
0x0040	CVARHR	Reactive Energy Phase L3 (WH)
0x0042	VARHR	Total Reactive Energy (WH)
Coil registers
Register address	Register name	Description
0x0000	RELAYA	Open-drain output OUTA status
0x0001	RELAYB	Open-drain output OUTB status
0x0002	RELAYC	Open-drain output OUTC status

Figure 27 - Default Modbus address map

6.6 MODBUS master (client) RS485 and TCP

Basic MODBUS master configuration procedure is described in paragraph 4.5.6. This paragraph describes format of Device Model and Update Policies files only. These files are referenced by Modbus Automation Units and describe the content of the external MODBUS devices.

6.6.1.1 Modbus Device Model configuration file

Model configuration files are an exhaustive list of the Modbus DataPoints which MUST be read from a MODBUS device. Only DataPoints described into the Model file will be read by the Modbus Unit.

The frequency at which those readings are done is determined by the Policies configuration file described in the next paragraph.

Modbus Device Model files are usually placed under the directory system/services/Device/Automation/models and have the following format:

Figure 28 – Modbus Master Device Model file organization

Remote DataPoints are organized in Maps, where a Map is a range of MODBUS registers which will be accessed through a single MODBUS Read access. This allows high flexibility but requires some precautions.

You must always avoid creating maps which covers large span of MODBUS addresses. For example, if you want to read registers 1 and 200 from device, create two separate maps. Otherwise, this would result in a single MODBUS Read access of 200 registers, causing high load on the bus.

It is however acceptable to have a map with holes of 2-3 ignored registers within it, as it is more efficient to read those registers and ignore the returned value (which is what Spoony does) than breaking the read operation in two separate MODBUS Read operations.

A single Map is defined in the following manner:

Figure 29 – Modbus Master Device Model Map

Each Map has a few parameters which must be set properly, and a list of DataPoints.

Parameters are:

name: each Map is named. This name will serve as identifier within the Policies file and MUST be unique within the whole Maps list,
type: indicates which MODBUS register type is accessed. Valid values are holdingRegister, inputRegister, discretesInput and coil,
swap: indicates default swap mode which applies to the Map. This default swap mode can be overridden within each DataPoint settings. Valid values are none, bw (bytes and words), b (bytes) and w (words),
count: number of entries within the Map. This MUST be set to the exact number of <datapoint> entries within the Map.

Each DataPoint entry of the map then accept the following options:

address: MODBUS register address in decimal format,
size: number of consecutive MODBUS registers,
name: DataPoint name. This name is then used to identify DataPoint within the Unit as shown in Figure 38,
format: format of data within the remote MODBUS device. Valid values are int16 (signed 16 bits integer), uint16 (unsigned 16 bits integer), int32 (signed 32 bits integer), uint32 (unsigned 32 bits integer) and float (IEE 754 floating point number),
swap: byte/word swap to apply. Valid values are none, bw (bytes and words), b (bytes) and w (words),
factor: optional value. Conversion factor (multiplier) to apply for converting to floating-point type.

Once your Device Model is complete, you must create a matching Update Policies file to define when each Map will be updated.

6.6.1.2 Modbus Update Policies configuration file

Update Policies configuration file is attached to each Device Model and describe when each map within the Model must be updated.

Policies file syntax is shown below:

Figure 30 – Modbus Master Policies file organization

Policies file contains a list of Groups. Each Group MUST contains a trigger entry specifying WHEN included Maps must be updated, and a list of <add></add> entries specifying which Maps from the Model file (identified by their names) are part of the Group.

The TimeTrigger configuration is comprised of an integer, followed by unit configuration (-U) and mode configuration (-M)

Valid units are s (seconds) and m (minutes). Mode MUST always be absolute.

For example, following Trigger configuration:

30 -U:s -M:absolute

Indicates that the Maps should be updated every 30s.

Once your Device Model and Update Policies files are defined, they must be placed into the system/services/Device/Automation/models directory. They can be referenced from this location within the Modbus Unit configuration section as show in paragraph 4.5.6

7 ODM Service configuration (data storage and sending)

7.1 Generalities

The ODM Service is responsible for sampling DataPoints from the Automation Space, and either Sending or Storing them to CSV files.

Various configurations are available for data sending, which are detailed in the next paragraphs.

Storing in CSV files requires a slightly different configuration for both the sampling and storing Services and is described in a separate paragraph 4.7.2.

Architecture of the ODM Service is described onto the diagram below:

Figure 31 – ODM Service architecture

DataChunk Service is responsible for sampling DataPoints on a regular basis and building DataChunks.

DataChunks are a DotVision proprietary data format for holding Timeseries data. Two versions of the DataChunk Service are available, but only version 2 can be used for data sending.

DataChunk version 2 specifications are detailed in Chapter 6

7.2 Configuration for local CSV storage

Version 1 of the DataChunk Service is now depreciated for use with DataPush Services others than CSV storage Service. For all other modes of operation than CSV storage, refer to paragraph 4.7.3.

CSV files generated in this mode will be saved to the measurements directory and named with the following pattern

{MyLittleSpoony}_YYYY-MM-DD_HH-mm.csv

Figure 32 – CSV files naming convention

With:

{Friendly Name}: device’s friendly name as configured in Device Service configuration. See paragraph 2 for details.
YYY-MM-DD_HH-mm: date and time of beginning of period

7.2.1.1 ODM Service configuration

ODM Service MUST be configured to use DataChunk version 1 and CsvLogService as follows.

Configuration file: system/services/Device/ODM/serviceSettings.xml

Link

Figure 33 – ODM Service main configuration file for CSV data storage mode

7.2.1.2 ODMWebPush Service configuration (CsvLogService type)

When using local CSV storage mode, ODMWebPush Service is of type CsvLogService and use the following configuration file format.

Configuration file: system/services/Device/ODM/ODMWebPush/serviceSettings.xml

Link CSV

Figure 34 – ODMWebPush configuration file for CSV data storage mode

Following parameters are accessible:

metrics: duration of output files. Integer followed by unit (s for second or h for hour). A new file will be created each time the metrics expires. In this example, a new file is created every day at 00:00 UTC,
decimal_separator: character to use as decimal separator in the output files
separator: character to use as field separator in the output files.

Parameter path is the output directory where CSV files will be created and should not be modified.

7.2.1.3 ODMDataChunk Service (V1) configuration

Local CSV storage mode rely on version 1 of the DataChunk Service. This version has less available options than version 2 but is better suited to a CSV output format as all DataPoints are sampled at the same frequency.

Configuration file: system/services/Device/ODM/ODMDataChunk/serviceSettings.xml

Link V1 DataChunk

Figure 35 – ODMDataChunk Service version 1 configuration for CSV data storage mode

This file specifies essentially one setting:

samplingPeriod: sampling period expressed in seconds.

Then follows the list of DataPoints into the <datapoints> section.

Each <datapoint> entry contains the following parameters:

path: path to the DataPoint, absolute path of Alias,
alias: optional name which will appear in CSV files header line for the matching column. If this parameter is omitted, DataPoint’s name will be used instead.

7.3 Configuration for Data sending

For modes other than local storage, DataChunk Service should be configured in version 2. ODM Service main configuration file must be configured as follow.

Configuration file: system/services/Device/ODM/serviceSettings.xml

Link

Figure 36 – ODM main Service configuration file for Data sending mode

7.3.1.1 DataChunk Service (version 2) configuration

DataChunk Service version 2 allows flexible data sampling and aggregation functions (averaging, minimum and maximum computation) over DataPoints.
Configuration file: system/services/Device/ODM/ODMDataChunk/serviceSettings.xml

Link V2 DataChunk

Figure 37 – DataChunk Service version 2 configuration for Data Sending mode

The sampling period given in Service settings defines the sending period (interval between DataChunks) and the default sampling period for all datapoints. Each Datapoint can override the default sampling period If required, allowing for higher or lower sampling rates than the default sampling period.

Each DataPoint entry is then written as follow:

Figure 38 – DataChunk Service version 2, datapoint entry format

DataPoint entries accept the following parameters:
- path: DataPoint path, alias or full path,
- unit: output DataChunk unit. DataPoint are grouped by Units in the output DataChunk. See detailed DataChunk messages specifications for more information,
- alias: alias name in output DataChunk. If omitted, DataPoint name is used instead,
- period: option to override the default sampling period. DatachunkV2 data format allows each DataPoint to have its own sampling period. This parameter is expressed in ms,
- agg_period: option to enable aggregation functionality. If this value is present and different from 0, average, minimum and maximum values will be computed. Computed value is updated from samples took every agg_period This agg_period field should be a sub-multiple of the configured sampling period for this DataPoint. Average value is sent as Value in the output DataChunk, minimum and maximum are sent as min and max within the extension field,
- agg_offset: only active if agg_period is present and different from 0. Indicates time offset in ms before sampling. This allows waiting a few milliseconds until all DataPoints are up to date before performing aggregation.
Precisions regarding the agg_period and agg_offset fields:

The effective output rate of the related DataPoint will be either the period parameter specified for this DataPoint, or the global samplingPeriod by default.

The agg_period field indicates the frequency at which the aggregation algorithm should be executed. For example, if period is 10000 (10s) and agg_period is 1000 (1s), average, minimum and maximum values will be calculated from 10 samples measured every 1s.

agg_offset allows waiting a few ms after the entire agg_period before sample, effectively waiting for the DataPoint value to be updated.

DataPoints’ values are usually updated every 1s, and update can take up to 5ms. For most cases, agg_offset should be set to 5ms.

When some Modbus DataPoints are present, DataPoint update can take more than 5ms, thus resulting in a need for a longer agg_offset (generally 100 to 200ms depending on number of Modbus DataPoints addressed).

7.3.1.2 WebPush Service (sending configuration)

WebPush Service receives DataChunk messages from the DataChunk Service and is responsible for sending them according to the specific configuration.

Latest firmware revisions of the device only support MQTT data sending. For help on previous revisions and other protocols, or compatibility of other protocols with the latest firmware revisions of the device, please contact DotVision.

Configuration file: system/services/Device/ODM/ODMWebPush/serviceSettings.xml

Link MQTT

Figure 39 - WebPush Service configuration for Data sending mode

Note: MqttClient Service MUST also be properly configured and activated for WebPush Service to work. Refer to section 4.8 for details on MQTT client configuration.
DataChunks are sent to the remote server over MQTT in the format specified in Chapter 6.

8 MQTT client configuration

8.1 Overview of MQTT client functionalities

Spoony’s MQTT client is a MQTT 3.1 client supporting TCP and TLS transports. All MQTT CONNECT options are fully configurable.

Please refer to the latest MQTT 3.1 documentation from https://mqtt.org/ for detailed specifications of the MQTT protocol.

MQTT client must be properly configured to allow ODM Service (when configured for MQTT data sending) as well as JsonRpc Service to work.

DotVision provides full-featured cloud-based and on-premises MQTT broker and data storage solutions. Please contact DotVision for any request regarding device infrastructure.

8.2 MqttClient configuration

MQTT client is fully configured from MqttClient Service configuration file.

Configuration file: system/services/Device/MqttClient/serviceSettings.xml

Link

Figure 40 – MqttClient Service configuration file

Following settings are available:

host: required. Specifies scheme (tcp or tls) followed by host and port in the form {scheme}://{host}:{port}

Note: When using TLS scheme for connection, relevant root certificate in X509 format MUST be placed in the certificates’ directory.

clientId: optional. Specifies a static client identifier if required. When omitted, device GUID will be used instead. Please note that most MQTT Brokers will not allow two simultaneous connections with the same client identifier,
version: always 0, MQTT version announced in CONNECT request. Do not modify,
username: optional. Specifies username if required for your MQTT broker,
password: optional. Specifies password if required for your MQTT broker,
readTimeout: optional. Maximum time in ms to wait for server responses. Defaults to 2000ms,
willTopic: optional. Last Will topic,
willMessage: optional. Last Will message,
willQos: optional. Last Will QOS,
keepAliveInterval: optional. Specifies the keep alive interval for PING requests,
cleanSession: optional. Defaults to true.

Note: optional values can be left empty, commented, or omitted.

9 HTTP server

9.1 HTTP server overview

HTTP server functionality is responsible for serving HTML Web pages to your Web browser, as well as hosting the device’s API to allow interaction with your device from your Web browser.

HTTP server configuration should not be modified. If you have any request for specific HTTP server configuration, please contact DotVision.

10 JSON-RPC

10.1 JSON-RPC functionality overview

JsonRpc Service provides Json-RPC functionality to access some device functionalities.

All current HTTP API will be available through Json-RPC in future firmware revisions. Json-RPC allows a higher level of standardization of API functions than regular HTTP API, with a more uniform interface.

JsonRpc Service exposes Json-RPC methods through HTTP and MQTT, allowing seamless integration of local and remote devices with a uniform interface.

Please refer to dedicated document “JSON-RPC over MQTT implementation by BluePanda Devices – Spoony specific methods” for details on Json-RPC interface with DotVision devices.

10.2 JSON-RPC configuration

JsonRpc Service configuration holds a single configuration parameter allowing to define MQTT topic’s root path for Json-RPC requests. This parameter has no effect for Json-RPC over HTTP binding.

Configuration file: system/services/Device/JsonRpc/serviceSettings.xml

Link

Figure 41 – JsonRpc Service configuration file

11 Console Service

Console Service is for use by DotVision maintenance and support team and provides low level access to device through serial communication, TCP, and optionally remote TLS connection.

This Service is configured to connect with DotVision Remote Management server by default.

This connection allows DotVision support team to access your device’s configuration remotely upon request. This requires a prior valid network configuration of your device, and an access to the Internet through your network.

This remote connection is fully secured using TLS and can be permanently disabled from the Console Service configuration file if required.

Please note however that this connection allows DotVision support team to give you the best support by providing access to your device configuration, often allowing issue resolution within minutes. DotVision support team will never access your device unless specifically requested by yourself. This connection allows access to your DotVision device only, no access is possible to other devices on your network.

Configuration file: system/services/Device/Console/serviceSettings.xml

Link

Figure 42 – Console Service configuration file

12 Device firmware update

Device firmware can be updated by placing the new device firmware file (.hex or .bin file) into the firmware directory on the microSD card before rebooting the device.

On reboot, the device will automatically check the new firmware and update itself accordingly.

Please note that in some cases, firmware update may require update of a few configuration files for the device to work properly. Refer to specific firmware release notes provided by DotVision for more information.

Two ways of uploading the new firmware to the device can be used and are detailed in the next paragraphs.

12.1 Firmware upload using direct access to the MicroSD card

This is the preferred way for uploading device firmware, but it requires physical access to the device.

Cut device power and extract microSD card from the device, as shown in paragraph 2.4.2,
Insert microSD card into your computer and copy firmware file to the firmware directory,
Install microSD card back into the device and power the device.
After two minutes, the device will restart with updated firmware. Installed firmware version can be checked from the device information page. See 5.5.

12.2 Firmware upload using the embedded Web interface

As an alternative, new firmware file can be uploaded to the device using the embedded Web interface. See chapter 5.10.4 for detailed explanation on how to upload a file to the device using the Web interface, and how to reset device to install new firmware.

12.3 Device Factory Reset

Device can be restored to Factory default state by erasing the full content of the microSD card and replacing it with default firmware archive provided by DotVision.

Cut device power and extract microSD card from the device, as shown in paragraph 2.4.2,
Format microSD Card using FAT32 file system. Fast format can be safely used,
Extract the whole content of the ZIP archive to the root of the microSD card. MicroSD card root directory should look like the following illustration:

Figure 43 – SD card content view after factory reset

1. Install microSD card back into the device and power the device
2. After two minutes, the device will restart with updated firmware. Installed firmware version can be checked from the device information page. See 5.5.

Figure 1 – Device Service configuration file organization

Figure 2 – Device Service – Device option.

Figure 3 - Device Service – Services List.

Figure 4 – NetworkManager configuration file organization.

Figure 5 – Ethernet interface DHCP configuration.

Figure 6 – Ethernet interface static IP configuration.

Figure 7 – Wi-Fi AP interface configuration.

Figure 8 – Wi-Fi station configuration in DHCP mode.

Figure 9 – Wi-Fi station configuration in static IP mode.

Figure 10 – Ntp Service configuration.

Figure 11 – Automation service configuration file organization.

Figure 12 – ADE7758 Automation Unit configuration.