RM module work description

Jooby Development API for interacting with Jobby devices. Other documentation Message documentation Message encoders/decoders Message encoders/decoders GUI (Demo) API for interacting with Jobby devices. Other documentation

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.

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

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. 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 (Reporting data type) DATA_TYPE = 3 (hour and day) и TYPE_PARAMETERS = 4 (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

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

Description of parameter types on Jooby Development

№	Type/Value
1	Reporting data interval
4	Day checkout hour
5	Reporting data type
8	Priority data delivery type
9	Activation method in the LoRaWAN network
10	Battery depassivation info
11	Battery minimal load time. BATTERY_ACTIVE_TIME - The minimum required battery load time per day to prevent passivation.
18	RX2 config - For all types of modules. Setting the operation parameters of the second reception window.
22	DELTA_TIME_EN
23	METER_BASE_DATA
24	Enable absolute data
25	Serial number
26	Geolocation
28	Extra frame interval
29	METER_BASE_DATA_MC - Absolute data mode's parameters installation for multi-channel module
30	ABSOLUTE_DATA_EN_MC - Parameter is used to enable absolute data for multichannel device
31	Pulse channels scan configuration