- 1 ginstr IoT firmware parameter documentation
- 1.1 Software update principle
- 1.2 Power management principle
- 1.3 Periphery access class description
- 1.4 Memory, logs and data collection
- 1.5 BLE access class description
- 1.6 Configuration class description
- 1.6.1 Architecture and logic description
- 1.6.2 Enumerations
- 1.6.3 Public methods
ginstr IoT firmware parameter documentation
Software update principle
Firmware update principle
As general rule all ginstr IIoT devices ever sold must have same firmware version.
So in case a new firmware version will be released to PROD, ALL ever sold ginstr IIoT devices must get this firmware.
This means, that one firmware version must be able to handle all hardware variants that might be produced over time
(e.g. new GSM modem because former GSM modem is no longer available on the market).
Configuration update principle
Configuration updating is performed on-demand with help of a configuration application, whether from the server. After production, the firmware has no pre-defined configuration file and stores only initial default configuration attributes, which is used to perform the connection to the ginstr service Wi-Fi access point. The initial configuration is performed by pushing the configuration file to the IIoT device with the help of the configuration application.
Power management principle
To provide the way to manage the power consumption, the schematics allows to power on/off elements, stacked into 5 separate groups of the periphery:
base periphery, group A, group B, group C, GSM/GNSS module power line (and both GSM/GNSS submodules).
Base periphery includes (cannot not be managed separately):
- temperature sensor
- power management monitor
- shift register, which manages other periphery groups
Group A includes (can be managed separately):
- 4.0V power line
- LoRa power
- GSM sub module power-on
- GNSS sub module power-on
- battery probe
- Group B multiplexer power supply
- Group C multiplexer power supply
Group B includes (can be managed separately):
- Multiplexed digital-outs for the custom-defined ports, used in the extension boards
- Multiplexed analogue / digital IN ports, used for the extension boards
Group C includes (can be managed separately):
- led indication access
Periphery access class description
A lot of onboard periphery works through multiplexers: 4051 for digital and analog inputs and 74HC595 for outputs.
"MuxDriver" class provides convenient access to the available onboard periphery with respect to multiplexors usage.
The MuxDriver class provides the following enumerations:
|BATTERY_TYPE_PROG||22||Set the battery type|
|D_BLUE_LED||21||bicolor led blue part power supply ER|
|D_RED_LED||20||bicolor led blue part power supply|
|AMBER_LED||19||amber led power supply|
|WHITE_LED||18||white led power supply|
|BLUE_LED||17||blue led power supply|
|READ_A||16||4051 multiplexer trigger for A channel addressing|
|READ_B||15||4051 multiplexer trigger for B channel addressing|
|READ_C||14||4051 multiplexer trigger for C channel addressing|
|MUXOUT_1||13||custom digital output|
|POWER_GROUP_B||7||Power management group B|
|POWER_GROUP_C||6||Power management group C|
|BATTERY_TYPE_PROBE||5||Digital out which controls the battery type probe|
|GSM_ON_OFF||4||GSM module power-up / shutdown signal|
|GSM_POWER||3||GSM module power|
|GNSS_POWER||2||GNSS module power|
|LORA||1||LoRa module power supply|
|HV_POWERBUS||0||GSM/GNSS module power supply|
|port_reg (detailed ports table)|
|AMBER_LED_PORT||1||amber led power supply|
|WHITE_LED_PORT||2||white led power supply|
|BLUE_LED_PORT||3||blue led power supply|
|D_BLUE_LED_PORT||4||bicolor led blue part power supply|
|D_RED_LED_PORT||5||bicolor led blue part power supply|
|HV_POWERBUS||6||4.0V bus power supply|
|GNSS_POWER||7||GNSS module power supply|
|GSM_ON_OFF||8||GSM module power on / off signal|
|GSM_POWER||9||GSM module power supply|
|LORA_POWER||10||LoRa module power supply|
|POWER_GROUP_B||11||Power supply for the power management group B|
|POWER_GROUP_C||12||Power supply for the power management group C|
|MUXOUT_1_PORT||13||Configurable multiplexed ports outputs|
|MUXIN_1_PORT||18||Configurable multiplexed ports inputs|
|PINPORT_1_PORT||26||Configurable physical pins|
Set the power state of auxiliary periphery group A
void periphery_power_A(power_state a);
This method turns on/off the power on the main group of the auxiliary periphery used on this board.
Without powering on, it will be impossible to use multiplexed inputs / outputs and manage GSM/LoRa power.
This method is a part of a power management system, used on the board.
Set the power state of auxiliary periphery group B
void periphery_power_B(power_state a);
This method turns on/off the power on the B group of the auxiliary periphery.
Set the power state of auxiliary periphery group C
void periphery_power_C(power_state a);
This method turns on/off the power on the C group of the auxiliary periphery.
Update the multiplexed periphery state
The method is used in the main cycle loop to update the state of multiplexers.
Without its regular updating, the periphery output states will not be updated and the input multiplexer data would not be read.
Reset the state of multiplexers to default values (everything is off)
The method is used for resetting the states of outputs for the off states. For inverted channels (LoRa, for example) the default logic level is HIGH.
Set the power type flag device
void set_battery_flag(bool rechargable);
The method sets the onboard flip-flop device to control the battery management path
Set the indication LEDs
void set_indication(mux_reg a, power_state val | bool val);
The method provides the way to set the selected LED on or off. This method is a simplified alias to set_muxout method, with disabled inversion by default
Set the state of multiplexer outputs with respect to inverted / non-inverted mode
void set_muxout(mux_reg a, power_state val, inversion inv);
The method provides the way to manage multiplexed ports with inversion mode defining
Set the value of physical ports
void set_physical(uint8_t a, power_state val, inversion inv);
Set the state of listed and available physical outputs with respect to inverted / non-inverted mode
Power UP the 4.0 V bus, to powerup the SIM868 module
void power_bus(power_state a);
This method used for SIM868 module power management. After method execution, the separated step-up/step-down converter is powered on or off.
Set the power state of GSM module
void GSM_power(power_state a);
This method used for SIM868 GSM power management.
Set the power state of GNSS module
void GNSS_power(power_state a);
This method used for SIM868 GNSS power management.
Set the power state of LoRa module
void LoRa_power(power_state a);
This method used for LoRa power management. After method execution, the p-channel MOSFET turns power on or off.
Get the ADC value from 4051 multiplexer
float get_adc_value(byte channel);
This method returns the value of ADC channel from 4051 multiplexer input.
To avoid the inaccuracy of the readings, the multiplexed ADC update rate is one reading per 30 mS.
Get the digital values interpretation from 4051
bool get_dig_value(byte channel, float threshold=0.8);
This method is a wrapper for get_adc_value.
It returns true if the read voltage is bigger than the threshold value. The default threshold value is 0.8V
Get the current values from the power sensor
Get the voltage values from the power sensor
Begin and set-up the G-sensor routine
bool g_sensor_begin(float sample_rate, int g_range);
This method is used when the g-sensor is setting up.
sample_rate - the sampling in samples per seconds (Hz).
Highest frequency - bigger accuracy and power consumption.
This parameter supports the following values: 0.781, 1.563, 3.125, 6.25, 12.5, 25, 50, 100, 200, 400, 800, 1600.
g_range - the range of sensibility. This parameter supports the following values in g: 2, 4, 8, 16.
Set the G-Sensor threshold
bool set_G_interrupt(int threshold, int duration);
This method is used to set up the threshold of g-sensor interrupt generation.
threshold - the sensibility threshold. Value can be from 1 to 4096. lower threshold value - better sensibility;
duration - the movement duration of the event In ms. Can be from 1 to 255;
Get the X acceleration value from the G-sensor
Get the Y acceleration value from the G-sensor
Get the Z acceleration value from the G-sensor
Get the temperature value from a temperature sensor in C
Get the temperature value from a temperature sensor in F
Blinking the LED
Powering on the custom digital output
Powering on the modems
Reading the ADC data
Reading the digital data
Reading the accelerometer data
Reading the temperature data
Memory, logs and data collection
Error logs generation and reading
Data logs generation and reading
Helper methods for memory manipulation
BLE access class description
The BLE access class provides the features to use the ESP32 Bluetooth functionality with GATT profile to interact with the onboard periphery, configuration core and the logging core.
The main purpose of this class is to provide the features for direct control and device configuration.
Configuration class description
The configuration class provides the features for complex device setup, which includes:
- registers reading/writing
- interacting with the filesystem
- configuration XML file parsing and configuration structure creating
- setting up the periphery with custom conditions
Architecture and logic description
Configuration tree structure and XML
Please find here a configuration XML file sample.
The XML configuration file provides the data structure which configures the device with features needed for the exact specific case in a very broad range:
from the telemetry transmission case to use cases connected with programmable logic controller usage.
The XML document must use the standards of this document type.
The configuration file consists of one root element and multiple logical blocks with a tree-like structure inside the root element.
List of sections, used for configuration:
|Section name||Section description|
|configData||Inside this block, the config attributive information is described|
|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.
|modemDevices||Communication devices entities description|
|sensorDevices||Onboard sensors description and default configurations|
|durationPatterns||Description of duration patterns for the operations such as indication blinking and button-triggered functions|
|dataTransmision||List of data entities and their attributes, which shall be sent to the ginstr server|
|ledIndication||List of led indication signals|
|deviceActions||List of device action entities in which can 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 can work with the same target and can contain multiple conditions
|deviceActions||This section is used for port function configuration|
|ginstrServer||ginstr server connection set up|
|watchdog||Configuration of the watchdog timeout|
|button||Functions attached to button pressing patterns|