From wiki.ginstr.com
Revision as of 13:01, 23 January 2021 by Wikiadmin (talk | contribs) (operations)
Jump to: navigation, search

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, such as “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