====== RM module work description ======
==== Jooby Development ====
* [[https://github.com/jooby-dev|API for interacting with Jobby devices. Other documentation]]
* [[https://github.com/jooby-dev/jooby-docs|Message documentation]]
* [[https://github.com/jooby-dev/jooby-codec|Message encoders/decoders]]
* [[https://jooby-dev.github.io/jooby-gui/|Message encoders/decoders GUI (Demo)]]
* [[https://github.com/jooby-dev|API for interacting with Jobby devices. Other documentation]]
* [[https://github.com/jooby-dev/jooby-docs/blob/main/docs/analog/commands/readme.md|Command and Parameter Examples]]
===== Beginning of work =====
It is necessary to know the module factory parameters to instal module in NS correctly (they are available in specification):
* Activation method in the LoraWAN network - **ABP** (Activation by personalization) or **OTAA** (Over the Air Activation)
* Keys **APPSKEY[16]**, **NETSKEY[16]** - **ABP** or **APPKEY[16]** - **OTAA**
===== Time and date =====
The Radio module and server times need to be synchronized. It is necessary to correct the modulating time when it leaves the server. Possible deviation no more than 30 seconds.
The time is transmitted as a 4-byte counter. This is the time in seconds since the year 2000. The module time must be synchronized with the server time.
The time can be set using the commands: **SET_TIME** and **CORRECT_TIME**. The **SET_TIME** command is for initial time setting and for adjustments greater than +/-128 seconds. Adjusting the time backwards may result in the loss of hourly data.
Further, the server must correct the module time if it deviates from the server time. The recommended allowable time deviation is no more than 30 seconds; if it is exceeded, the time is corrected using the **CORRECT_TIME** command.
===== Battery =====
Once a day, the module measures the battery parameters: battery voltage without load and battery voltage under resistor load (150 Ohm for modules on WLE). These data and the calculated internal resistance value are transmitted once a day also.
Based on the measurement results, it is possible to start the battery depassivation process. In this case, the **DEPASS_DONE** event is logged.
===== Magnetic field sensor =====
A magnetic field sensor is installed in the module.
This sensor is used to send current pulse counter to server.
In case of short magnetic influence (more than 2 sec and less than 20 sec), the current pulse counter data **GET_CURRENT** for **HARD_TYPE 1,2** and **GET_CURRENT_MUL** for **HARD_TYPE 12**... will be sent to the server.
{{:en:rdc:devices:7.jpg?direct&300|}}
===== Activation/Deactivation =====
The module is activated after the **Jooby Splitter 1x4PU/1x2PU** is connected to the module port. The sensor is polled continuously. Activation means that the module starts sending data frames via the radio. Before activation, the module's radio is switched off. When **INSERT** and **ACTIVATE** events have occurred, **NEW_EVENT** frames with **INSERT** and **ACTIVATE** events are transmitted, and the time of the event is transmitted in the data of these events. Also, the command **GET_CURRENT** transmits the current data of the pulse counter. If **Jooby Splitter 1x4PU/1x2PU** is disconnected from the module, it will be deactivated after 30 seconds. The **NEW_EVENT** frame with the events **REMOVE** and **DEACTIVATE** will be sent to the server, the time of the event is transmitted in the data of these events. The **GET_CURRENT** command also sends the current pulse counter data.
===== Consumption data =====
Once activated, the module sends consumption data regularly. By default, the module transmits hourly consumption data at an interval of about 4 hours + a pseudo-random component ranging from 0 to 17 minutes. The frequency of sending data can be changed, but the period cannot be less than 10 minutes and more than 36 hours.
You can set the type of data to be transferred. It is possible to transfer current, hourly, daily data. It is also possible to transmit hourly and daily data simultaneously (in one frame). To select the type of data to be transmitted, use parameter 5 (Type of data to be output). Hourly data is stored in the archive, the maximum archive depth is 6 months. Daily consumption data is also stored in the archive, the maximum depth is 2 years. The depth of the archives does not change configurationally.
===== Absolute data. Commands, Parameters =====
* [[en:rdc:Command_Parameter_Examples|Command and Parameter Examples]]
The device supports absolute data mode. This mode is set so that the current readings of the meter can be easily obtained from the data transmitted by the device. In this mode, the device uses a different set of commands to communicate consumption data.
To set the initial readings of the meter, you must use the //impulse coefficient - IPK//, which is a parameter of the meter and indicates the amount of resource per pulse.
To set the absolute data transmission mode, it is necessary to transfer the impulse coefficient IPK and the initial readings of the meter, expressed taking into account the //impulse coefficient// ''INITIAL_METER_DATA = INITIAL_CONSUMPTION/IPK''. As well as the current value of the pulse counter. The value of the pulse counters can be obtained at the moment of activation or initiate the transfer of current data using a slider, a magnet, pressing a button, setting a connector (tamper closing). If necessary, these operations can be repeated.
==== Setting parameters ====
**For example (SET_PARAMETERS = 0x03 with TYPE_PARAMETERS = 23):**
* IPK (pulse factor) = 100 liters per 1 pulse
* Initial readings INITIAL_CONSUMPTION = 12.5 m3
* The current value of the pulse counter START_COUNTER = 0x5033
With such initial data, it is necessary to set INITIAL_METER_DATA to 12.5/0.1 = 125.
To set the parameters of the absolute data mode, use the command **SET_PARAMETERS = 0x03** with **TYPE_PARAMETERS = 23**.
| 7 | 6 | 5 | 4 | 3 | 2 | 1 | 0 |
| 0 | 0 | 0 | CMD SET_PARAMETERS = 0x03 |||||
| CMD_LENGTH = 10 ||||||||
| TYPE_PARAMETERS = 23 ||||||||
| INITIAL_METER_DATA[4] ||||||||
| IPK[1] ||||||||
| START_COUNTER[4] ||||||||
**Message format:**
|Command 1|
|Command 2|
|...|
|Command N|
|**LRC**|
The **LRC** is calculated by performing an XOR operation on the content of the message with the start value ''0x55''. [[https://toolslick.com/math/bitwise/xor-calculator|XOR Calculator]]
**Message example:**
|Hex dump with LRC ''030A170000007D6400005033551''||
|03|SET_PARAMETERS|
|17|TYPE_PARAMETERS 23|
|0A|LENGTH (0x0a = 10 Dec)|
|0000007D|INITIAL_METER_DATA (0x0000007D = 125 Dec)|
|64|IPK (0x64 = 100 Dec)|
|00005033|START_COUNTER (0x5033 = 20531 Dec)|
|551|LRC|
If the value of the START_COUNTER field is set to 0xFFFFFFFF, it means that the current value of the pulse counter is taken as this parameter.
==== Transfer mode ====
To enable absolute data transfer mode, use the command **SET_PARAMETERS = 0x03** c **TYPE_PARAMETERS = 24**.
| 7 | 6 | 5 | 4 | 3 | 2 | 1 | 0 |
| 0 | 0 | 0 | CMD SET_PARAMETERS = 0x03 |||||
| CMD_LENGTH = 2 ||||||||
| TYPE_PARAMETERS = 24 ||||||||
| ABS_DATA_EN=1 ||||||||
Example:
hex dump: 03021801
Options **TYPE_PARAMETERS = 23** and **TYPE_PARAMETERS = 24** can be set with one message.
Example:
hex dump: 030A170000007D640000503303021801+LRC
or
hex dump: 030A170000007D64FFFFFFFF03021801+LRC
The command **SET_PARAMETERS = 0x03** with **TYPE_PARAMETERS = 29** is used to set the parameters of the absolute data mode of a multichannel sensor. **CHANNEL number field added to this command**.
| 7 | 6 | 5 | 4 | 3 | 2 | 1 | 0 |
| 0 | 0 | 0 | CMD SET_PARAMETERS = 0x03 |||||
| CMD_LENGTH = 11 ||||||||
| TYPE_PARAMETERS = 29 ||||||||
| CHANNEL ||||||||
| INITIAL_METER_DATA[4] ||||||||
| IPK[1] ||||||||
| START_COUNTER[4] ||||||||
Example:
hex dump: 030B1D02000001010A00005033 + LRC
030A - SET_PARAMETERS = 0x03, len = 11 dec
1D - TYPE_PARAMETERS = 29
02 - CHANNEL = 0x02 = 2 канал (начиная с 0)
00000101 - INITIAL_METER_DATA = 0x00000101 = 129 dec
0A - IPK = 0x0A = 10 dec
00005033 - START_COUNTER = 0x5033 = 20531 dec
If the value of the START_COUNTER field is set to 0xFFFFFFFF, it means that the current value of the pulse counter is taken as this parameter.
To enable the absolute data transfer mode, use the command **SET_PARAMETERS = 0x03** with **TYPE_PARAMETERS = 30**.
| 7 | 6 | 5 | 4 | 3 | 2 | 1 | 0 |
| 0 | 0 | 0 | CMD SET_PARAMETERS = 0x03 |||||
| CMD_LENGTH = 3 ||||||||
| TYPE_PARAMETERS = 30 ||||||||
| CHANNEL ||||||||
| ABS_DATA_EN=1 ||||||||
Example:
hex dump: 03031E0201
The execution of the command is confirmed by the response ''hex dump: 03021D0103021E01'', which confirms the successful installation of the parameters.
Also, after that, the device will start issuing absolute data of the meter.
This means that for modules **HARD_TYPE=1,2** instead of **DATA_DAY**, **DATA_HOUR_DIFF** and **GET_CURRENT** commands transmitted periodically without request, **ABS_DATA_DAY**, * commands will be transmitted *ABS_HOUR_DIFF** and **EX_ABS_CURRENT**.
And for **HARD_TYPE=12** modules, the **DATA_DAY_MUL**, **DATA_HOUR_MUL** and **GET_CURRENT_MUL** commands will specify channels for which the absolute data mode is not set, and in the **EX_ABS_DAY_MUL** and * commands *EX_ABS_HOUR_MUL** and **EX_ABS_CURRENT_MUL** will indicate the channels for which the absolute data mode is enabled.
In the messages, meter readings will be received, taking into account the impulse coefficient.
Example:
If the received field value METER_DATA = 0x80 = 128 dec, then this corresponds to the readings of the meter - METER_CONSUMPTION = METER_DATA*IPK = 128*100=12.8m3
==== Implementation in the device ====
* **INITIAL_CONSUMPTION** - initial readings of the meter, at the time of activation
* **IPK** - impulse coefficient of the device, which determines the compliance of the consumed resource per 1 impulse
* **INITIAL_METER_DATA** = INITIAL_CONSUMPTION/IPK
* **START_COUNTER** - readings of the pulse counter at the time of activation, from the activation message
* **CURRENT_COUNTER** - current readings of the pulse counters in the device
* **METER_CONSUMPTION** - current meter readings. METER_CONSUMPTION = METER_DATA*IPK
The device sends data in messages **METER_DATA** = INITIAL_METER_DATA + (CURRENT_COUNTER-START_COUNTER).
For example:
Start readings of the meter INITIAL_CONSUMPTION = 41.1 m3(41100 dm3, IPK=100 (100 dm3 per pulse), current readings of the impulse counter CURRENT_COUNTER = 4580, starting readings of the impulse counter START_COUNTER=5. As a result: METER_DATA = 41100/100 + (4580 -5)=4986.
As a result, we obtain the current readings of the meter: METER_CONSUMPTION = 4986*100 = 498600 dm3 = 498.6 m3.
===== "Reporting data type" and "Day checkout_hour" =====
* The default ''Reporting data type'' is ''0'' - (hour)
* The default ''Day checkout hour'' is ''0'' - (00:00)
For example, to receive ''hour and day data'' at ''6:00'', you need to set the following parameters:
**TYPE_PARAMETERS = 5** ([[https://github.com/jooby-dev/jooby-docs/blob/main/docs/analog/parameter-types.md#reporting-data-type|Reporting data type]]) **DATA_TYPE = 3** (hour and day) и **TYPE_PARAMETERS = 4** ([[https://github.com/jooby-dev/jooby-docs/blob/main/docs/analog/parameter-types.md#day-checkout-hour|Day checkout hour]]) **HOUR = 6** (06:00)
**1. set ''reporting data type'' to ''hour and day'':**
|0x03|set parameters|
|0x02|lenght|
|0x05|parameter - data type|
|0x03|hour and day|
|0x52|LRC|
Message hex dump with LRC: ''03 02 05 03 52''
**Answer from server:**
|0x03|set parameters|
|0x02|lenght|
|0x05|parameter - Data Type|
|0x01|parameter has been Set correctly|
|0x50|LRC|
Answer message hex dump with LRC: ''03 02 05 01 50''
**2. Set ''day checkout hour'' to ''6:00'':**
|0x03|set parameters|
|0x02|lenght|
|0x04|parameter - day checkout hour|
|0x06|hour|
|0x56|LRC|
Message hex dump with LRC: ''03 02 04 06 56''
**Answer from server:**
|0x03|set parameters|
|0x02|lenght|
|0x04|parameter - day checkout hour|
|0x01|parameter has been set correctly|
|0x51|LRC|
Answer message hex dump with LRC: ''03 02 04 01 51''
===== Events =====
[[https://github.com/jooby-dev/jooby-docs/blob/main/docs/analog/basics.md#device-events|Device events]]
All events are recorded in the archive. Archive capacity - not less than 256 events and not more than 512 events. The event log records the time of the event, the event ID, and the **LAST_EVENT** sequence number. The event number is incremented with each entry. The event number is passed to the server with the **LAST_EVENTS** command, which is added to every UPLINK frame sent without a request. There is no priority for messages in the archive. Events are recorded in a cycle. Archives can be requested from the most recent to the oldest and from a specific time.
^ Event ^ Code ^ Description ^
|**MAGNIT_ON**|0x01|Fixation of magnetic influence for more than 20 seconds|
|**MAGNIT_OFF**|0x02|Removal of magnetic influence|
|**ACTIVATE**|0x03|The module has been activated|
|**DEACTIVATE**|0x04|Module deactivation. Termination of transmission of frames on the air|
|**BATTERY_ALARM**|0x05|The sensor has reset due to low battery voltage. Outdated|
|**INSERT**|0x07|Fixing the installation of the module in the gas meter|
|**REMOVE**|0x08|Fixing the removal of the module from the gas meter|
|**COUNTER_OVER**|0x09|Pulse counter overflow. The number of pulses has exceeded 4294967295|
|**SET_TIME**|0x0A|Fixing the module time setting event|
|**DEPASS_DONE**|0x0E|Fixing the depassivation of the battery.|
===== Commands =====
^ HARD_TYPE=1,2 |^ HARD_TYPE=12 ||
| **UPLINK without request** ||||
| DATA_DAY = 0x20 | Data of the counter of impulses of the sensor for accounting hour | DATA_DAY_MUL=0x16 | Data of counters of pulses of the multichannel sensor for accounting hour. |
| DATA_HOUR_DIF = 0x40 | Hourly data of impulses counter with output of reference counter and counter accumulation in consecutive hours | DATA_HOUR_DIF_MUL=0x17 | Data of impulses counter of the multichannel sensor for accounting hour. |
| LAST_EVENTS = 0x60 | Last unread event | LAST_EVENTS = 0x60 | Last unread event. |
| GET_CURRENT=0x07 | Command for issuing current readings of the sensor pulse counter | GET_CURRENT_MUL=0x18 | Command for issuing current readings of the pulse counter of a multichannel sensor. |
| | | EX_ABS_HOUR_MUL=0x1F-0x0A | The command to receive absolute data in the format of a multi-channel pulse counter. |
| | | EX_ABS_DAY_MUL=0x1F-0x0B | The command to receive absolute data of daily consumption in the format of a multi-channel impulse counter. |
| TIME2000 = 0x09 | Sensor current time | TIME2000 = 0x09 | Sensor current time |
| NEW_STATUS=0x14 | Sensor status | NEW_STATUS=0x14 | Sensor status. |
| NEW_EVENT=0x15 | An event has occurred | NEW_EVENT=0x15 | An event has occurred. |
| **Commands coming from the NS server in DOWNLINK frames** ||||
| SET_TIME_2000 = 0x02 | Correction of time in the sensor. Four bytes in the command parameters are a signed number that determines the Time2000 time correction value | SET_TIME_2000 = 0x02 | Correction of time in the sensor. Four bytes in the command parameters are a signed number that determines the Time2000 time correction value. |
| CORRECT_TIME2000=0x0C | Similar to the SET_TIME_2000 command. In the command data, the correction sequence number and one sign byte of the correction value. The command is applied only if the sequence number differs from the current one in the sensor | CORRECT_TIME2000=0x0C | Similar to the SET_TIME_2000 command. In the command data, the correction sequence number and one sign byte of the correction value. The command is applied only if the sequence number differs from the current one in the sensor. |
| GET_CURRENT = 0x07 | Request to read the current value of the pulse counter | GET_CURRENT_MUL = 0x18 | Request to read the current values of the multichannel pulse counter. |
| SET_PARAMETERS = 0x03 | Setting parameters in the sensor | SET_PARAMETERS = 0x03 | Setting parameters in the sensor. |
| GET_PARAMETERS = 0x04 | Request set parameters in the sensor | GET_PARAMETERS = 0x04 | Request set parameters in the sensor. |
| GET_ARCHIVE_HOURS = 0x05 | Request to read the archive of hourly samples of the pulse counter | GET_ARCHIVE_HOURS_MUL=0x1A | Request to read the archive of hourly samples of the multichannel pulse counter. |
| GET_ARCHIVE_DAYS = 0x06 | Request to read the archive of daily (at 0 hours) pulse counter samples | GET_ARCHIVE_DAYS_MUL = 0x1B | Request to read the archive of daily (for accounting hour) samples of a multichannel pulse counter. |
| GET_ARCHIVE_EVENTS=0x0B | Request to read the event archive | GET_ARCHIVE_EVENTS=0x0B | Request to read the event archive |
| SOFT RESET = 0x19 | Software reset command. | SOFT RESET = 0x19 | Software reset command. |
| GET_LMIC_VERSION=0x1F-0x02 | LMIC version query command | GET_LMIC_VERSION=0x1F-0x02 | LMIC version query command. |
| | | EX_ABS_ARCH_HOUR_MUL=0x1F-0x0C | The command to receive the archive of absolute data of hourly consumption in the format of a multi-channel impulse counter. |
| | | EX_ABS_ARCH_DAY_MUL=0x1F-0x0D | The command to receive the archive of absolute data of daily consumption in the format of a multichannel impulse counter. |
| | |EX_ABS_CURRENT_MUL=0x1F-0x0F| |
===== Parameter types =====
[[https://github.com/jooby-dev/jooby-docs/blob/main/docs/analog/parameter-types.md#parameter-types|Description of parameter types on Jooby Development]]
| **№ ** | **Type/Value** |
| **1** | [[https://github.com/jooby-dev/jooby-docs/blob/main/docs/analog/parameter-types.md#reporting-data-interval|Reporting data interval]] |
| **4** | [[https://github.com/jooby-dev/jooby-docs/blob/main/docs/analog/parameter-types.md#day-checkout-hour|Day checkout hour]] |
| **5** | [[https://github.com/jooby-dev/jooby-docs/blob/main/docs/analog/parameter-types.md#reporting-data-type|Reporting data type]] |
| **8** | [[https://github.com/jooby-dev/jooby-docs/blob/main/docs/analog/parameter-types.md#priority-data-delivery-type|Priority data delivery type]] |
| **9** | [[https://github.com/jooby-dev/jooby-docs/blob/main/docs/analog/parameter-types.md#activation-method|Activation method in the LoRaWAN network]] |
| **10** | [[https://github.com/jooby-dev/jooby-docs/blob/main/docs/analog/parameter-types.md#battery-depassivation-info|Battery depassivation info]] |
| **11** | [[https://github.com/jooby-dev/jooby-docs/blob/main/docs/analog/parameter-types.md#battery-minimal-load-time|Battery minimal load time]]. BATTERY_ACTIVE_TIME - The minimum required battery load time per day to prevent passivation. |
| **18** | [[https://github.com/jooby-dev/jooby-docs/blob/main/docs/analog/parameter-types.md#rx2-config|RX2 config]] - For all types of modules. Setting the operation parameters of the second reception window. |
| **22** | DELTA_TIME_EN |
| **23** | [[https://github.com/jooby-dev/jooby-docs/blob/main/docs/analog/parameter-types.md#absolute-data|METER_BASE_DATA]] |
| **24** | [[https://github.com/jooby-dev/jooby-docs/blob/main/docs/analog/parameter-types.md#enable-absolute-data|Enable absolute data]] |
| **25** | [[https://github.com/jooby-dev/jooby-docs/blob/main/docs/analog/parameter-types.md#serial-number|Serial number]] |
| **26** | [[https://github.com/jooby-dev/jooby-docs/blob/main/docs/analog/parameter-types.md#geolocation|Geolocation]] |
| **28** | [[https://github.com/jooby-dev/jooby-docs/blob/main/docs/analog/parameter-types.md#extra-frame-interval|Extra frame interval]] |
| **29** | [[https://github.com/jooby-dev/jooby-docs/blob/main/docs/analog/parameter-types.md#absolute-data-multi-channel|METER_BASE_DATA_MC]] - Absolute data mode's parameters installation for multi-channel module |
| **30** | [[https://github.com/jooby-dev/jooby-docs/blob/main/docs/analog/parameter-types.md#enable-absolute-data-multichannel|ABSOLUTE_DATA_EN_MC]] - Parameter is used to enable absolute data for multichannel device |
| **31** | [[https://github.com/jooby-dev/jooby-docs/blob/main/docs/analog/parameter-types.md#pulse-channels-scan-configuration|Pulse channels scan configuration]] |