# Device settings
Some technology-specific fields are essential for the agent when setting up a ELCO Spider67 Mobile device (a.k.a., thing) in the IoTHub.
# Thing
A thing is a digital representation of a physical device (commonly termed "digital-twin").
TIP
ELCO Spider67 Mobile devices (i.e., things) have a special treatment in our IoTHub. As soon as the agent and the device are connected to the same MQTT broker. Then, the agent will automatically register your device (and its properties, see below). Optionally, you can also register the device in the IoTHub before turn it on, but be aware that you must correctly input the list of identifiers labeled on the side of your device.
# Configuration
The configuration defines connection-related settings for communicating with the device. Here, essential technology-specific fields are:
interval: The interval specifies the time (in milliseconds) used by the device for sending data. This means, the device will do its best to cyclically send data in the given time frame.identifiers: This defines the list of identifiers used to recognize the device. This list is usually labeled on the side of the device and contains the International Mobile Equipment Identity (IMEI) number, the Integrated Circuit Card ID (ICCID), among others.
WARNING
When the device is created by the agent, the initial list of identifiers is given by device itself. Please, be extremely careful if you register your device manually or if you update the list of identifiers. The first identifier (i.e., the IMEI) is particularly important because it will be used for communicating the agent with the device via MQTT; thus, if you set a wrong identifier the communication can be broken.
modules: The modules define a collection of individual configurable slots (either digital or analog) named channels. Find below the list of valid modules:
| Module | Description |
|---|---|
| CH8_DI_M12 | 8 channels input module with M12 connector |
| CH8_DO_M12 | 8 channels output module with M12 connector |
| CH8_DUP_M12 | 8 channels input&output configurable module with M12 connector |
| CH8_DI_M8 | 8 channels input module with M8 connector |
| CH8_DO_M8 | 8 channels output module with M8 connector |
| CH8_DUP_M8 | 8 channels input&output configurable module with M8 connector |
| CH3_AI_INPUT | 3 channels analog current input with M12 connector |
| CH3_AV_INPUT | 3 channels analog voltage input with M12 connector |
| CH4_AI_INPUT | 4 channels analog current input with M12 connector |
| CH4_AV_INPUT | 4 channels analog voltage input with M12 connector |
| CH3_AI_OUTPUT | 3 channels analog current output with M12 connector |
| CH3_AV_OUTPUT | 3 channels analog voltage output with M12 connector |
| CH4_AI_OUTPUT | 4 channels analog current output with M12 connector |
| CH4_AV_OUTPUT | 4 channels analog voltage output with M12 connector |
WARNING
The list of attached modules matches the physical connections on the device; thus, this information comes from the device itself, and it should not alter by the user.
firmware: This specifies the current firmware version executed on the device.
WARNING
This information comes from the device itself, and it should not alter by the user.
# Properties
Properties represent all items that the agent should monitor; this means reading or writing data from or into them, respectively.
# Predefined
For ELCO Spider67 Mobile devices there are some predefined technology-specific properties:
CSQ: This property informs about the current device's quality signal.configured_logic: This property holds the latest configured logic image. If the device is restarted, the logic contained in this property will be automatically sent to the device.channel_status: This property informs about the current status of the device's channels. It displays a list of the channel ids with their corresponding statuses. Here, valid channel statuses are:
| Status | Description |
|---|---|
| NORMAL | The channel is working normally |
| SHORT | The channel is receiving an abnormal input |
| OVERLOAD | The channel is receiving an excessive input |
| DAMAGED | The channel is not working or responding |
# Attributes
Each property representing a physical channel contains the following technology-specific fields:
module: This field defines the source (parent) module from where the agent created the property (i.e., a reference to one of the modules contained in the thing's configuration).channelId: This field defines the internal representation of the property in the agent. This channel id is a unique identifier in the form ofmodule_X.channel_YwhereXis the correlative numbering of the parent module in the configuration, andYis the correlative number of the physical channel.
For instance, if the configuration has the following modules list: CH8_DUP_M12, CH8_DUP_M12, and CH3_AI_INPUT. Then, the corresponding channel identifiers are as follows:
| CH8_DUP_M12 | CH8_DUP_M12 | CH3_AI_INPUT |
|---|---|---|
| module_0.channel_0 | module_1.channel_0 | module_2.channel_0 |
| module_0.channel_1 | module_1.channel_1 | module_2.channel_1 |
| module_0.channel_2 | module_1.channel_2 | module_2.channel_2 |
| module_0.channel_3 | module_1.channel_3 | |
| module_0.channel_4 | module_1.channel_4 | |
| module_0.channel_5 | module_1.channel_5 | |
| module_0.channel_6 | module_1.channel_6 | |
| module_0.channel_7 | module_1.channel_7 |
Here, each channel identifier (i.e., each module_X.channe_Y) represents a different property (i.e., a physical channel of the device).
channelType: This field specifies how a particular channel is configured to work. Here, channels can be set for handling a precise type of input. These types are divided in different categories depending on the parent module:
Valid types for digital channels (i.e., created from digital modules):
| Channel Type | Description |
|---|---|
| UNIVERSAL | The channel can be used as input and output |
| INPUT | The channel is input only |
| OUTPUT | The channel is output only |
Valid types for analog current channels (i.e., create from analog modules which operate current inputs):
| Channel Type | Description |
|---|---|
| ANCHOFF | The channel is disabled (i.e., not configured) |
| AN_0_20mA | The channel operates from 0mA to 20mA |
| AN_4_20mA | The channel operates from 4mA to 20mA |
| AN_20_20mA | The channel operates from -20mA to +20mA |
| AN_0_24mA | The channel operates from 0mA to 24mA |
| AN_24_24mA | The channel operates from -24mA to 24mA |
Valid types for analog voltage channels (i.e., create from analog modules which operate voltage inputs):
| Channel Type | Description |
|---|---|
| ANCHOFF | The channel is disabled (i.e., not configured) |
| AN_0_10V | The channel operates from 0V to +10V |
| AN_10_10V | The channel operates from -10V to +10V |
| AN_0_5V | The channel operates from 0V to 5V |
| AN_5_5V | The channel operates from -5V to +5V |
WARNING
Please note that the analog channels reports only raw values. For instance, if you set an analog channel as type AN_5_5V, the property will not display values between -5 and 5 but the value of the original analog signal instead.
# Actions
Actions are interaction affordances that allow to invoke specific functions on the device or retrieve information from it. Here, essential technology-specific actions are:
manual_configuration: Use this action to manually send the current configuration to the device.fota_update: Use this action for requesting a Firmware Over-The-Air (FOTA) update. This will restart the device and download the latest firmware version.logic_image: Use this action for setting and sending a new logic image to the device. This defines a set (array) of logic instructions which will be automatically processed by the device when certain conditions (operations) are satisfied.
The general structure of a logic image is as follows:
| Input | Operation | Output |
|---|---|---|
module_[X].channel_[0-7] | -(O)- | module_1.channel_[0-7] |
Here, input and output are represented by the identifier of a specific channel. Moreover, you can replace -(O)- for one of the following valid operations (depending on the type of the input channel):
| Operation | Type |
|---|---|
-(=)- or -(==)-: The output should have the same value as the input | Digital |
-(!=)- or -(<>)-: The output should have the opposite value than the input | Digital |
-(>X)-: If the input is higher than X the output should be active | Analog |
-(<X)-: If the input is lower than X the output should be active | Analog |
WARNING
Currently, only module_1 can be used as output of logic images.
raw_logic: Use this action for setting and sending a new logic image without the previously described notation. This defines an array of logic instruction which will be automatically processed by the device with certain conditions are satisfied.
The general structure of a rae logic image is as follows:
| Raw field | Size (bytes) | Description |
|---|---|---|
| Version | 4 | Logic version |
| Input | 1 | Correlative number of the input channel |
| Output | 1 | Correlative number of the output channel |
| Type | 1 | Logic type (0: analog, 1: digital) |
| Operation | 1 | Rule (0: not equal or less than, 1: equal or higher than |
| Threshold | 2 | Boundary condition (only applicable for analog logics) |
The correlative notation of input and outputs is inferred from the position of the parent modules in the thing's configuration. For instance, if the configuration has the following modules list: CH8_DUP_M12, CH8_DUP_M12, and CH3_AI_INPUT. Then, the corresponding correlative numeration of the channels (represented in parentheses) is as follows:
| CH8_DUP_M12 | CH8_DUP_M12 | CH3_AI_INPUT |
|---|---|---|
| module_0.channel_0 (0) | module_1.channel_0 (8) | module_2.channel_0 (16) |
| module_0.channel_1 (1) | module_1.channel_1 (9) | module_2.channel_1 (17) |
| module_0.channel_2 (2) | module_1.channel_2 (10) | module_2.channel_2 (18) |
| module_0.channel_3 (3) | module_1.channel_3 (11) | |
| module_0.channel_4 (4) | module_1.channel_4 (12) | |
| module_0.channel_5 (5) | module_1.channel_5 (13) | |
| module_0.channel_6 (6) | module_1.channel_6 (14) | |
| module_0.channel_7 (7) | module_1.channel_7 (15) |
erase_logic: Use this action for removing every logic image previously sent to the device.
# Events
Events are transition states that describe particular conditions or relevant changes in the interaction between the agent and the device. Here, essential technology-specific events are:
configuration_delivery: This event notifies when the configuration was delivered to the device. If an error occurred during the transmission, it is also notified by this event.changed_identifiers: This notifies when the device's identifiers have been changed.