Detailed XML structure description

Root sections table

Configuration XML sample

Section name	Section description
button	Functions attached to button pressing patterns
communicationPriorities	Priorities for communication interface usage. If the device with higher priority is unable to get the network or transmit the data, then the lower priority device is used for this purpose.
configData	Inside this block, the config attributive information is described
dataTransmission	List of data entities and their attributes, which should be sent to the ginstr server
deviceActions	List of device action entities in which could be described the conditions and the data sources for custom actions Example: “turn MUXOUT_3_PORT on IF condition is true” or “send a report with a message if conditions are true”. Different actions could work with the same target and contain multiple conditions
devicePorts	This section is used for port functions configuration
durationPatterns	Description of duration patterns for the operations such as indication blinking and button-triggered functions
ginstrServer	Connection set up
ledIndication	List of led indication signals
modemDevices	Communication devices entities description
operations
sensorDevices	Onboard sensors description and default configurations
watchdog	Configuration of the watchdog timeout

Root sections description

configData

This section is used for sharing the attributive information, which belongs to the configuration’s file origin and target device. This section could be used for basic version control and verification.

Name	Datatype	Description
createdTimestamp	Integer	Time of the config file creation in unix format
targetModel	String	The name of configured device; there might be multiple suitable models
versionAuthor	String	The sign of config file author/editor
versionName	String	The name of current configuration

communicationPriorities

This section is used for the communication channel priorities definition.

A communication channel is provided by a modem defined in section modemDevices.

Example:
in case wifi communication channel has priority 3 and gprs communication channel has priority 5, then the firmware will first try to transmit the data thru wifi and only in case this will not work the device will try to transmit data thru gprs.

If the priorities of multiple communication channels are equal, then the device will try to transmit the data simultaneously thru all communication channels with same priority.
Priority can be 1..9 - lower number means higher priority.

A modem device must be activated in section modemDevices; otherwise it will not be used for data transmission at all.

For following communication channels a priority can be set:

Communication channel	Datatype	Description
ble	Integer	Bluetooth modem priority
gprs	Integer	GRPS modem priority
lora	Integer	LoRa modem priority
wifi	Integer	WIFI modem priority

modemDevices

This section describes the available communication devices.
The section itself is a list of ```device``` entities.
Each device entity has it’s own general and device-specific attributes.

Modem device entity attributes

Name	Datatype	Description
name	String	System name of the device. This parameter will be used for reports
communicationChannel	String	The type of the modem. This parameter is vital for the right device-specific attributes recognition and physical device setup.
model	String	Attributive information used for reports and validation
detectAntenna	Boolean
active	Boolean	This flag defines the physical availability of the radio module. If this flag is false, the device would be newer powered ON, until switching this flag to true.
forOperationEnabled	Boolean	This flag defines if the physically available device is used for data transmission.
deviceSpecificAttributes	XML Section	The content of the device-specific attribute section could vary on each device a lot. It contains the settings which depend on the device type.

Example for modem device attributes

<device>
   <name> GSM Modem </name>
   <communicationChannel>gprs</communicationChannel>
   <model> SIM868 </model>
   <detectAntenna> false </detectAntenna>
   <active> true </active>
   <forOperationEnabled> true </forOperationEnabled>
   <deviceSpecificAttributes>
      <useHttps> true </useHttps>
      <simPin> </simPin>
      <useGprs> true </useGprs>
      <internetAccessUserName> </internetAccessUserName>
      <internetAccessPassword> </internetAccessPassword>
   </deviceSpecificAttributes>
</device>

Examples of the modem deviceSpecificAttributes section

For the GSM modem:

<deviceSpecificAttributes>
   <useHttps> true </useHttps>
   <simPin> </simPin>
   <useGprs> true </useGprs>
   <internetAccessUserName> </internetAccessUserName>
   <internetAccessPassword> </internetAccessPassword>
 </deviceSpecificAttributes>

For the WIFI modem:

<deviceSpecificAttributes>
   <forSetupSsid> ENAiKOON-Technik </forSetupSsid>
   <forSetupPassword> EN2020ik </forSetupPassword>
   <forSetupEnabled> true </forSetupEnabled>
   <forOperationSsid> </forOperationSsid>
   <forOperationPassword> </forOperationPassword>
</deviceSpecificAttributes>

sensorDevices

This section describes the available sensor devices.
The section itself is a list of sensor device entities, similar to modem devices.
Each sensor device entity has its own general and device-specific attributes.

The following sensors are supported:

Sensor type	Description
temperature sensor
G-sensor

Name	Datatype	Description	Obligatory	Default
name	String	System name of the sensor. This parameter will be used for reports. Any name is allowed.	yes	"sensor"
type	String	The type of the sensor. This parameter is vital for the right device-specific attributes recognition and physical device setup. For valid sensor types see table above.	yes	---
active	String	This flag defines the physical availability of the sensor device	no	false
errorValue	Integer	This value is used in cases of device failure to provide failure detection and filtering abilities.	???	???
deviceSpecificAttributes	XML Section	This section contains sensor-specific settings. Also, the section contains the keys names for writing values into the global register system. By these keys, the sensors data could be obtained for condition-based device actions and reporting.	???	???

Example for a sensor device entity:

<device>
   <name> Temperature Sensor Cryo </name>
   <type> temperature </type>
   <active> false </active>
   <errorValue> 777 </errorValue>
   <deviceSpecificAttributes>
      <registerKey></registerKey>
      <elementType>NTC</elementType>
      <thermistorResistance>1000</thermistorResistance>
      <thermistorCorrection>0.0</thermistorCorrection>
   </deviceSpecificAttributes>
</device>

Examples of the sensor deviceSpecificAttributes section

For the G-sensor:

<deviceSpecificAttributes>
   <registerKey_x> g_sens_x </registerKey_x>
   <registerKey_y> g_sens_y </registerKey_y>
   <registerKey_z> g_sens_z </registerKey_z>
   <interruptSensibility> 1000 </interruptSensibility>
   <interruptTimeout> 3 </interruptTimeout>
   <samplingRate> 3 </samplingRate>
   <sensorRange> 2 </sensorRange>
</deviceSpecificAttributes>

For the temperature sensor:

<deviceSpecificAttributes>
   <registerKey> temperature_1 </registerKey>
   <elementType>NTC</elementType>
   <thermistorResistance>100000</thermistorResistance>
   <thermistorCorrection>0</thermistorCorrection>
</deviceSpecificAttributes>

durationPatterns

The duration patterns are used for user interaction purposes. The described section allows the device-specific timing definition for each duration variable.

The duration patterns section is a list of defined patternGroups. Each pattern group has its own settings and belongs to the defined events/device type.

Currently there are 2 pattern groups:

• for indicating events thru LEDs (blinking patterns)
• for button events (different press patterns will execute different events)

Pattern group entity

Name	Datatype	Description
name	String	Unique name of the pattern group
durations	XML Section	This section contains the duration entities

The duration entities section describes the timing for each “duration symbol”.
By concatenating these “symbols” different custom patterns can be formed, like “SsSsLlSs”.
The defined timing values allow pattern parsing and execution.

Name	Datatype	Pattern symbol	Unit	Description
L-duration	Integer	L	milliseconds	long duration, element is active (e.g. button is pressed, LED is on)
l-duration	Integer	l	milliseconds	long duration, element is not active (e.g. button is not pressed, LED is off)
M-duration	Integer	M	milliseconds	medium duration, element is active (e.g. LED is on); not available for buttons
m-duration	Integer	m	milliseconds	medium duration, element is not active (e.g. LED is off); not available for buttons
S-duration	Integer	S	milliseconds	short duration, element is active (e.g. button is pressed, LED is on)
s-duration	Integer	s	milliseconds	short duration, element is not active (e.g. button is not pressed, LED is off)

Example for the L-M-S-l-m-s duration definition:

<durationPatterns>
    <patternGroup>
        <name>button</name>
        <durations>
            <L-duration> 500 </L-duration>
            <l-duration> 500 </l-duration>
            <S-duration> 100 </S-duration>
            <s-duration> 100 </s-duration>
        </durations>
    </patternGroup>
   
    <patternGroup>
        <name>indication</name>
        <durations>
            <L-duration> 1000 </L-duration>
            <l-duration> 1000 </l-duration>
            <S-duration> 100 </S-duration>
            <s-duration> 100 </s-duration>
            <M-duration> 500 </M-duration>
            <m-duration> 500 </m-duration>
        </durations>
    </patternGroup>
</durationPatterns>

Example for creating a LED blinking pattern

<led>
   <name> Amber LED</name>
   <ledOperatingTimeAfterColdstartSecond> 600 </ledOperatingTimeAfterColdstartSecond>
   <portRegister>AMBER_LED_PORT</portRegister>
   <ledSignals>
       <signal>
           <status> wifiIsOff </status>
           <blinkingPattern> s </blinkingPattern> 
       </signal>
       <signal>
           <status> wifiTryingToConnectToRouter </status>
          <blinkingPattern> Ss </blinkingPattern>
       </signal>
       <signal>
           <status> wifiTryingToConnectToGinstrServer </status>
           <blinkingPattern> Mm </blinkingPattern>
       </signal>
       <signal>
           <status> wifiCommunicationWithGinstrServerIsEstablished </status>
           <blinkingPattern> Ll </blinkingPattern>
       </signal>
       <signal>
           <status> wifiModemNotFound </status>
           <blinkingPattern> Ls </blinkingPattern>
       </signal>
   </ledSignals>
</led>

Example for creating a button press pattern

<button>
   <sendTemperature> Ss </sendTemperature>
   <restartDevice> Ls </restartDevice>
   <clearBufferedData> LsSs </clearBufferedData>
   <wakeDeviceUp> Ll </wakeDeviceUp>
   <showBatteryStatus> SsSs </showBatteryStatus>
</button>

dataTransmission

This section contains the sending rules and the list of entities, each of which describes the telemetry payload which could be sent to the server.

Name	Datatype	Description
sendAfterCollectingXRecords	Integer	Counter based threshold value of the number of collected records. As soon as the defined number of records is collected, the transmission action starts. In the meantime the data is stored in non-volatile flash memory, so data will not be lost when restarting the device. 0 means, that the data will not be stored in flash. It will be sent immediately from RAM. This protects the flash memory. In case data transmission to the server fails then the record will be stored in flash.
sendBufferedDataAfterXSeconds	Integer	Time-based threshold value for data sending (seconds). 'sendBufferedDataAfterXSeconds' parameter supersedes 'sendAfterCollectingXRecords' parameter.
dataTransmisionPayloads	XML Section	Section with the list of payload entities.

Payload entity attributes:

Name	Datatype	Description
name	String	Name of the record
registerKey	String	Name of the register, which stores the value. Some payloads can use pre-defined or event-based values (timestamp, communication device, EventTriggeringThisRecord, etc)
send	Boolean	Enable / disable this record
dataType	String	The payload data type, string or number, dateTime
decimals	Integer	Decimal places
columnName	String	The name of the column in the ginstr database

ledIndication

This section describes how each indication led acts in response to system statuses.

The ledIndication section is a group of led indication entities, each of which has its own unique settings.

LED indication entity settings

Name	Datatype	Description
name	String	Name of the LED indicator
portRegister	String	Name of the physical port register used by MuxDriver class to link the entity with the hardware LED port Following LED colours assigned to ports: GREEN_LED_PORT = green BLUE_LED_PORT = blue AMBER_LED_PORT = amber D_RED_PORT = dark red WHITE_LED_PORT = white ???? one is missing
ledOperatingTimeAfterColdstartSecond	Integer	Timeout after which the led indication will be disabled for power saving purposes. 0 means that the LEDs will never be disabled.
ledSignals	XML Section	Section with list of potential statuses and the blinking pattern of the related LED per status

List of ledSignals entity attributes

Name	Datatype	Description
status	String	The status name, which triggers the blinking of an LED; Following statuses are defined: GSM: gsmIsOff gsmTryingToConnectToNetwork gsmTryingToConnectToGinstrServer gsmConnectedToGinstrServer gsmSimError gsmModemNotFound BLE: bleIsOff bleTryingToConnectToSmartphone bleTryingToConnectToGinstrApp bleCommunicationWithGinstrAppIsEstablished bleTargetIdNotFoundError bleModemNotFound WiFi: wifiIsOff wifiTryingToConnectToRouter wifiTryingToConnectToGinstrServer wifiCommunicationWithGinstrServerIsEstablished wifiModemNotFound LoRa: loraIsOff loraTryingToConnectToGateway loraCommunicationWithGatewayIsEstablished loraModemNotFound System: noSerialNumber noValidRtcTime batteryIsLow dataInbufferWaitingForTransmissionToGinstrServer rtcIsNotOperational rtcIsNotSet 3D-G-sensorMotionDetected unknownError
blinkingPattern	String	The “duration symbol” pattern. Example: LlSs

deviceActions

This section allows defining the custom rules-based device events.

Each “device action” supports: multiple condition-based rules custom action target custom data source

In sum, this approach allows creating flexible device configurations for any use-case.

The deviceActions section contains the list of active entities.

Device action entity attributes

Name	Datatype	Description
name	String	name of the action
type	String	Action type. this attribute supports the values, described in the next table
portName	String	name of the port registered in the devicePorts section. This field is used only In the case of supporting action type configured.
targetRegister	String	key of the memory register to link the action with the global register variable. This field is used only In the case of supporting action type configured.
actionMultiCondition	XML Section	In this section the list of condition rules is defined

Action types for the “type” attribute

Name	Description
REPORT	Send the report with a defined message
WRITE_LOG	Write into the error log with a defined message
WRITE_REG	Write data into the memory register
WRITE_PORT	Write to the physical port
DEEP_SLEEP	Turn device into deep sleep mode
REBOOT	Reboot the device

Multi-condition section operator groups description

The actionMultiCondition content has a structure that allows defining the conditions combination logic with help of “logical operator sections”.

The condition groups inside the AND section would generate TRUE output only in the case if all condition entities in this AND section would return TRUE.

The condition groups inside the OR section would generate TRUE output in the case if ANY of nested condition groups or separated entities would return TRUE.

This approach allows getting the flexible and universal condition-based events only with the help of a configuration file, which is useful in the case of complex control applications.

Name	Datatype	Description
AND	XML Section	The section will return TRUE if ALL nested entities will return true
OR	XML Section	The section will return TRUE if ANY of nested entities will return true

Condition types

The conditional entities provide multiple condition types, which allows working with different data sources

Name	Description
ON_TIMER	timer-based condition could have also 2 sub-types: interval-based event, and datetime-based event
REG_VALUE	condition based on the specified register value
PORT_DIG_VALUE	condition based on the digital IN port value
PORT_ADC_VALUE	condition based on the ADC port value
ON_REBOOT	condition triggered on the reboot event
ON_WAKEUP	condition triggered on the wakeup event

Register's value-based conditional entity attributes

Name	Datatype	Description
conditionType	String	Condition type (REG_VALUE, in this case)
registerKey	String	The register’s key name
comparedValue	Float	value, which would be used for comparison
conditionOperator	String	Conditional operator used for values comparison. Available values are: “<”, “<=”,“>”, “>=”, “==”, “!=”
valueHysteresis	Float	The hysteresis value

ADC value-based conditional entity attributes

Name	Datatype	Description
conditionType	String	Condition type (PORT_ADC_VALUE, in this case)
portName	String	Name of the port specified in the devicePorts section
comparedValue	Float	value, which would be used for comparison
conditionOperator	String	Conditional operator used for values comparison. Available values are: “<”, “<=”,“>”, “>=”, “==”, “!=”
valueHysteresis	Float	The hysteresis value

Digital-Input value-based conditional entity attributes

Name	Datatype	Description
conditionType	String	Condition type (PORT_DIG_VALUE, in this case)
portName	String	Name of the port specified in the devicePorts section
comparedValue	String	HIGH / LOW
conditionOperator	String	“==”, “!=”

Timer-based conditional entity attributes

Name	Datatype	Description
conditionType	String	Condition type (ON_TIMER, in this case)
timerType	String	The type of a timer-based event. Datetime-based, or interval-based ( TIMER / INTERVAL
startTime	Integer	Start time in unix format (This attribute uses only with timerType of TIMER)
endTime	Integer	End time in unix format (This attribute uses only with timerType of TIMER)
interval	Integer	Interval in seconds
period	Integer	Period in seconds
repetitive	Boolean	If true, the event would be repeated

devicePorts

This section provides the way for hardware ports custom configuration. In this section should be defined only ports that are used in the customer-specified application. There is no need to list and define all device ports.

The devicePorts section contains a list of port entities.

Port entity attributes

Name	Datatype	Description
name	String	The unique port name, which is used in actions and conditions definitions.
portRegister	String	Physical port register name, used to link this entity with the MuxDriver class
type	String	Port configuration type. The port could be set up in multiple ways. The list of setting types is shown in the next table.
inversion	Boolean	This attribute defines if the port uses the inverted logic (ON on LOW)
pullMode	String	This attribute defines the internal GPIO pullup or pulldown, if available (UP / DOWN)
defaultState	String	default state of the port (ON / OFF)
pwmSettings	XML Section	The section with PWM setup settings
readSettings	XML Section	The section allows to set-up the port value writing into the memory register by the key name.
irqSettings	XML Section	The section allows to set-up interrupt events

Port types

Name	Description
INPUT_DISCRETE	Plain digital input. In this case, the port will return only a boolean value.
INPUT_ANALOG	Analog input mode
INPUT_INTERRUPT	Interrupt mode. Port could be configured for pulses counting or for a single-event generation.
OUTPUT_DISCRETE	Digital Out mode
OUTPUT_PWM	PWM output mode

Write port attributes

Name	Datatype	Description
writeValueToRegister	Boolean	If true, the register will be linked with actual port value
writeRegisterName	String	Unique name of the register

Interrupts handling

The irqSettings section contains the attributes which allow to set-up the interrupt-generating port:

Name	Datatype	Description
interruptTrigger	String	Type of triggering events: ON_HIGH or ON_LOW
interruptFX	String	Action type: could be COUNTER or ACTION. If COUNTER is defined, the port entity will return the number of the pulses counted during the defined time period. If ACTION defined, the port will return TRUE directly after trigger shots.
counterSettings	XML Section	This section helps to define features for COUNTER type setup

Interrupt COUNTER type settings

Name	Datatype	Description
timingMS	Integer	The time in mS during which the pulses are counting
smoothFactor	Integer	Running average factor. If 0 - smoothing is OFF

ginstrServer

This section includes the attributes used for ginstr server communication

Name	Datatype	Description
urlForSerialNumberCreation	String	API url
urlForLoadingConfigurationFile	String	API url
ginstrSsoUserName	String	sso username
ginstrSsoPassword	String	sso password
urlForPostingData	String	API url
ginstrTableForSensorData	String	Sensor data table name
ginstrTableForAlertsData	String	Alerts data table name

watchdog

This section provides the attribute for the watchdog setup

Name	Datatype	Description
waitingTimeForMainProcessorMilliSeconds	Number	Watchdog timeout value

button

This section is used for button-press patterns configuring

Name	Datatype	Description
sendTemperature	String	Pattern defined to recognise the sendTemperature event
restartDevice	String	Pattern defined to recognise the restartDevice event
clearBufferedData	String	Pattern defined to recognise the restartDevice event
wakeDeviceUp	String	Pattern defined to recognise the wakeDeviceUp event
showBatteryStatus	String	Pattern defined to recognise the showBatteryStatus event

operations

Name	Datatype	Description
temperatureSendIntervalSeconds
ifMotionTemperatureSendIntervalSeconds
buttonWakeUpDurationSeconds
maxWakeupDurationSeconds
stillAliveFrequency		seconds 1 hour = 3600 seconds 1 day = 86400 seconds

GNSS

???

Wires in external cable

???

How to switch off components for power saving

???

Batteries

• types
• charging
• replacement