Jump to content

LIGO PRO BLE Protocol: Difference between revisions

From SOJI ELECTRONICS
[checked revision][checked revision]
Admin (talk | contribs)
Bureaucrats, Interface administrators, Administrators
1,439 edits
VisualWikitext
Create page
 
Initial Release [release]
 
(7 intermediate revisions by the same user not shown)
Line 1: Line 1:
== General Introduction ==
== General Introduction ==
<div class="dim">


''Brief introduction to the protocol per IEC/IEEE standards for wireless data protocols.''
LLS Protocol is used in LIGO RS232 / RS485 fuel level sensor with the following parameters:
* Baud rate: 2400, 4800, 9600, 19200, 38400, 115200 (can be configured by software on PC)
* Data bits: 8
* Parity: None
* Stop bits: 1
* Flow control: None


'''What to fill in:'''
LIGO fuel level sensor has 2 working modes:
* '''Protocol name and version''' — full name + version number (vd: SOJI Protocol v2.1)
# '''Slave mode:''' In this mode, the sensor will respond to all requests from the external device (master device). Each sensor in the network will be distinguished by different addresses configured with the LIGO Configurator software.
* '''Purpose''' — what data the protocol transmits and to whom
# '''Master mode:''' In this mode the sensor will automatically send data to the external device with a preset interval (message interval).
* '''Transport layer''' — Bluetooth 5.4 BLE / WiFi / LoRa / proprietary RF
* '''Frequency & modulation''' — 2.4 GHz GFSK / LoRa CSS / ...
* '''Operating mode''' — Advertising-only (one-way broadcast) / Connection-based / Mesh
* '''Compatible devices''' — list of sensors / receivers supporting this protocol
* '''Reference standards''' — IEEE 802.15.4, Bluetooth Core 5.4, etc.


'''Example structure:'''
To enable this mode on the LIGO Configurator software, do the following:
* Paragraph 1: "The [Protocol Name] is a [type] protocol defined by SOJI Electronics for [purpose]..."
* Automatic transmission: select HEX (binary) or ASCII or ASCII EXT
* Paragraph 2: "It operates over [transport] at [frequency] and is supported by [device list]..."


'''Optional sub-sections:'''
[[File:LLS-Protocol-Configurator-Automatic-Transmission.png|center|400px|thumb|Automatic transmission dropdown in LIGO Configurator]]
* === Protocol Stack === — layered diagram of protocol stack
* === Roles === — Broadcaster / Observer / Central / Peripheral
* === Security === — encryption, authentication, password protection


</div>
* Set the time of each transfer (Message interval)


== Advertising Message Format ==
[[File:LLS-Protocol-Configurator-Message-Interval.png|center|400px|thumb|Message interval setting in LIGO Configurator]]
<div class="dim">


''Byte-by-byte breakdown of the BLE advertising packet payload.''
== Exchange Protocol Description ==


'''What to fill in:'''
The LLS protocol supports two types of exchange protocols: binary (HEX) and character view (transmission of ASCII sequences). It is recommended to use binary exchange protocol.
* '''Packet overview''' — total packet length, manufacturer ID, structure summary
* '''Field table''' — every field with offset, length, value, description


'''Example field breakdown table:'''
=== Format of Binary Protocol Messages ===


{| class="wikitable" style="width:100%;"
All the commands of the binary communication protocol have the same standardized format which is given in the table:
 
{| class="wikitable"
|-
! Sequential number of the field !! Field name !! Field size, byte !! Description
|-
| style="text-align:center;" | 1 || Prefix || style="text-align:center;" | 1 || The field is a marker of the message beginning shall have prefix <code>31h</code>, and an outcoming messages shall be displayed with <code>3Eh</code> prefix by the program.
|-
| style="text-align:center;" | 2 || Network address || style="text-align:center;" | 1 || For prefix <code>31h</code> specify the network address of the recipient. <br>For prefix <code>3Eh</code> specify the network address of the sender.
|-
| style="text-align:center;" | 3 || Operation code || style="text-align:center;" | 1 || For prefix <code>31h</code> specify the code of operation which the program shall perform. <br>For <code>3Eh</code> prefix specify the code of operation to which the response is given.
|-
| style="text-align:center;" | 4 || Data || style="text-align:center;" | It depends on the operation code || Data composition and format of the field depends on the operation code.
|-
| style="text-align:center;" | 5 || Checksum || style="text-align:center;" | 1 || The field is used to control over data integrity.
|}
 
=== Single-Stage Data Reading (command 06h) ===
 
The command is designed for reading of the current data: relative level, temperature, frequency. The data are transmitted with a lower byte ahead.
 
==== Command format ====
 
{| class="wikitable" style="text-align:center;"
|-
! Offset, bytes !! Field size, bytes !! Value !! Description
|-
| 0 || 1 || <code>31h</code> || style="text-align:left;" | Prefix
|-
| +1 || 1 || <code>00h..FFh</code> || style="text-align:left;" | Network address of the recipient
|-
| +2 || 1 || <code>06h</code> || style="text-align:left;" | Operation code
|-
| +3 || 1 || <code>00h..FFh</code> || style="text-align:left;" | The checksum
|}
 
==== Response format ====
 
{| class="wikitable" style="text-align:center;"
|-
! Offset, bytes !! Field size, bytes !! Value !! Description
|-
| 0 || 1 || <code>3Eh</code> || style="text-align:left;" | Prefix
|-
| +1 || 1 || <code>00h..FFh</code> || style="text-align:left;" | Network address of recipient
|-
| +2 || 1 || <code>06h</code> || style="text-align:left;" | Operation code
|-
| +3 || 1 || −128…127 || style="text-align:left;" | Temperature in degrees Celsius
|-
| +4 || 2 || <code>0000h…FFFFh</code> || style="text-align:left;" | Relative level
|-
| +6 || 2 || <code>0000h…FFFFh</code> || style="text-align:left;" | Frequency value
|-
| +8 || 1 || <code>00h..FFh</code> || style="text-align:left;" | Checksum
|}
 
=== Periodic Data Output (command 07h) ===
 
Command is designed to switch on periodic data output.
 
After the command is processed, the sensor starts sending data periodically — level, temperature, and frequency — with the time interval prescribed by the <code>13h</code> command.
 
Turning off of the periodic data output is performed after receipt of any true command, reset of the processor or disconnection of power supply (if the data output mode is not installed by default).
 
==== Command format ====
 
{| class="wikitable" style="text-align:center;"
|-
! Offset, bytes !! Field size, bytes !! Value !! Description
|-
| 0 || 1 || <code>31h</code> || style="text-align:left;" | Prefix
|-
| +1 || 1 || <code>00h..FFh</code> || style="text-align:left;" | The Network address of the sender
|-
| +2 || 1 || <code>07h</code> || style="text-align:left;" | Operation code
|-
| +3 || 1 || <code>00h..FFh</code> || style="text-align:left;" | Checksum
|}
 
==== Response format ====
 
{| class="wikitable" style="text-align:center;"
|-
! Offset, bytes !! Field size, bytes !! Value !! Description
|-
| 0 || 1 || <code>3Eh</code> || style="text-align:left;" | Prefix
|-
| +1 || 1 || <code>00h..FFh</code> || style="text-align:left;" | Network address of recipient
|-
| +2 || 1 || <code>07h</code> || style="text-align:left;" | Operation code
|-
| rowspan="2" | +3 || rowspan="2" | 1 || <code>00h</code> || style="text-align:left;" | The command has been executed successfully
|-
| <code>01h</code> || style="text-align:left;" | The command cannot be executed
|-
| +4 || 1 || <code>00h..FFh</code> || style="text-align:left;" | Checksum
|}
 
==== Periodic data output format ====
 
{| class="wikitable" style="text-align:center;"
|-
! Offset, bytes !! Field size, bytes !! Value !! Description
|-
| 0 || 1 || <code>3Eh</code> || style="text-align:left;" | Prefix
|-
| +1 || 1 || <code>00h..FFh</code> || style="text-align:left;" | The Network address of the sender
|-
| +2 || 1 || <code>07h</code> || style="text-align:left;" | Operation code
|-
| +3 || 1 || −128…127 || style="text-align:left;" | Temperature in degrees Celsius
|-
| +4 || 2 || <code>0000h…FFFFh</code> || style="text-align:left;" | Relative level
|-
| +6 || 2 || <code>0000h…FFFFh</code> || style="text-align:left;" | Frequency value
|-
| +8 || 1 || <code>00h..FFh</code> || style="text-align:left;" | Checksum
|}
 
=== Periodic Data Output Interval Adjustment (13h command) ===
 
Command is designed to set up interval of periodic data output.
 
==== Command format ====
 
{| class="wikitable" style="text-align:center;"
|-
! Offset, bytes !! Field size, bytes !! Value !! Description
|-
| 0 || 1 || <code>31h</code> || style="text-align:left;" | Prefix
|-
| +1 || 1 || <code>00h..FFh</code> || style="text-align:left;" | Network address of the recipient
|-
| +2 || 1 || <code>13h</code> || style="text-align:left;" | Operation code
|-
| +3 || 1 || 0…255 || style="text-align:left;" | Interval of the data output in seconds
|-
| +4 || 1 || <code>00h..FFh</code> || style="text-align:left;" | Checksum
|}
 
==== Response format ====
 
{| class="wikitable" style="text-align:center;"
|-
! Offset, bytes !! Field size, bytes !! Value !! Description
|-
| 0 || 1 || <code>3Eh</code> || style="text-align:left;" | Prefix
|-
| +1 || 1 || <code>00h..FFh</code> || style="text-align:left;" | The Network address of the sender
|-
| +2 || 1 || <code>13h</code> || style="text-align:left;" | Operation code
|-
| rowspan="2" | +3 || rowspan="2" | 1 || <code>00h</code> || style="text-align:left;" | The command has been executed successfully
|-
| <code>01h</code> || style="text-align:left;" | The command cannot be executed
|-
| +4 || 1 || <code>00h..FFh</code> || style="text-align:left;" | Checksum
|}
 
=== Default Data Output Mode (command 17h) ===
 
This command determines the order of data output after the sensor is powered on or the processor is reset. After the power is on or the processor is reset, the program will send data periodically via the interface at the time interval prescribed by the <code>13h</code> command.
 
==== Command format ====
 
{| class="wikitable" style="text-align:center;"
|-
! Offset, bytes !! Field size, bytes !! Value !! Description
|-
|-
! Offset !! Length (bytes) !! Field Name !! Value / Format !! Description
| 0 || 1 || <code>31h</code> || style="text-align:left;" | Prefix
|-
|-
| 0x00 || 1 || AD Length || 0xXX || Length of the advertising data structure
| +1 || 1 || <code>00h..FFh</code> || style="text-align:left;" | Network address of the recipient
|-
|-
| 0x01 || 1 || AD Type || 0xFF || Manufacturer Specific Data (per Bluetooth Core spec)
| +2 || 1 || <code>17h</code> || style="text-align:left;" | Operation code
|-
|-
| 0x02 || 2 || Company ID || 0xXXXX (LE) || SOJI Electronics SIG-assigned Company ID
| rowspan="4" | +3 || rowspan="4" | 1 || <code>00h</code> || style="text-align:left;" | The command has been executed successfully
|-
|-
| 0x04 || 1 || Protocol ID || 0xXX || SOJI Protocol identifier
| <code>01h</code> || style="text-align:left;" | The data are output in binary form
|-
|-
| 0x05 || 1 || Frame Type || 0xXX || Frame type (data frame, status frame, ...)
| <code>02h</code> || style="text-align:left;" | The data are output in character-coded form (ASCII mode)
|-
|-
| 0x06 || N || Payload || ... || Sensor data payload (see Payload Structure below)
| <code>03h</code> || style="text-align:left;" | The data are output in character-coded form (ASCII EXT mode)
|-
|-
| 0x06+N || 2 || CRC-16 || 0xXXXX || CRC-16/CCITT checksum over Offset 0x00 to 0x05+N
| +4 || 1 || <code>00h..FFh</code> || style="text-align:left;" | Checksum
|}
|}


'''Sub-sections to consider:'''
==== Response format ====
* === Packet Overview === — total length, byte order (LE/BE), encoding
* === Field Definitions === — main field table above
* === Payload Structure === — detailed payload fields (level, temperature, battery, RSSI, etc.) with units and scaling
* === Frame Types === — enumeration of frame types if multiple exist
* === CRC / Checksum === — algorithm (CRC-16/CCITT, polynomial, init value, XOR-out)
* === Example Raw Frame === — hex dump of a real advertising packet with field annotations
* === Decoding Pseudocode === — short code snippet (C / Python) showing how to parse a frame


'''Example raw frame block:'''
{| class="wikitable" style="text-align:center;"
<syntaxhighlight lang="text">
|-
Raw bytes (hex):
! Offset, bytes !! Field size, bytes !! Value !! Description
  0E FF 5A A5 01 02 03 04 ...
|-
| 0 || 1 || <code>31h</code> || style="text-align:left;" | Prefix
|-
| +1 || 1 || <code>00h..FFh</code> || style="text-align:left;" | Network address of the recipient
|-
| +2 || 1 || <code>17h</code> || style="text-align:left;" | Operation code
|-
| rowspan="2" | +3 || rowspan="2" | 1 || <code>00h</code> || style="text-align:left;" | The command has been executed successfully
|-
| <code>01h</code> || style="text-align:left;" | The command cannot be executed
|-
| +4 || 1 || <code>00h…FFh</code> || style="text-align:left;" | Checksum
|}
 
== Description of Commands for the Text-Based Protocol ==
 
Data exchange via the text-based protocol includes receipt and sending of ASCII symbols sequence interpreted and the request and response commands.


Decoded:
=== Reading the Data ===
  AD Length    = 0x0E (14 bytes)
 
  AD Type      = 0xFF (Manufacturer Specific)
The command is designed for reading of the current data: relative level, temperature, frequency. The command is a sequence of symbols ASCII "D" and "O". After receipt of the "DO" command the program will response in the form of ASCII symbols sequence.
  Company ID  = 0xA55A (SOJI Electronics)
 
  Protocol ID  = 0x01 (SOJI Protocol)
For example, <code>F=0AF9 t=1A N=03FF.0 &lt;CR&gt;&lt;LF&gt;</code>, where F is the current frequency value, t is the current value of temperature in Celsius degrees, N is the level value. All values are in hexadecimal form.
  Frame Type  = 0x02 (Data Frame)
 
  ...
In case the frequency value exceeds <code>FFFh</code>, the data are considered invalid.
</syntaxhighlight>
 
=== Periodic Data Output ===
 
The command is designed to switch on periodic data output. After processing the command, the sensor performs periodic data output in the text-based form (ASCII codes) of the following data: relative level, temperature, frequency.
 
The data are being output periodically with an interval set up when configuring the sensor (LIGO Configurator software). In case the data output interval is set to zero, the data output won't be performed.
 
Switching on of the periodic data output is done by sending of the "DP" symbols in line. After processing of the command, the symbols line will be received. For example, <code>F=0AF9 t=1A N=03FF.0 &lt;CR&gt;&lt;LF&gt;</code>, where F is the current frequency value, t is the current value of temperature in Celsius degrees, N is the level value. Turning off of the periodic data output is performed after receipt of any true command, reset of the processor or disconnection of power supply.


'''Example decoding pseudocode:'''
== Checksum Calculation Algorithm ==
<syntaxhighlight lang="python">
def decode_soji_frame(adv_data: bytes) -> dict:
    if adv_data[1] != 0xFF:
        return None
    company_id = int.from_bytes(adv_data[2:4], 'little')
    protocol_id = adv_data[4]
    frame_type = adv_data[5]
    payload = adv_data[6:-2]
    crc = int.from_bytes(adv_data[-2:], 'little')
    # ... validate CRC, parse payload
    return { ... }
</syntaxhighlight>


</div>
The checksum is calculated using Dallas APPLICATION NOTE 27 table method: ''Understanding and Using Cyclic Redundancy Checks with Dallas Semiconductor iButton Products''. One can use the following algorithms to calculate the checksum with a polynom <code>x^8 + x^5 + x^4 + 1</code> (C language):


<syntaxhighlight lang="c" line>
U8 CRC8(U8 data, U8 crc)
{
    U8 i = data ^ crc;
    crc = 0;
    if (i & 0x01) crc ^= 0x5e;
    if (i & 0x02) crc ^= 0xbc;
    if (i & 0x04) crc ^= 0x61;
    if (i & 0x08) crc ^= 0xc2;
    if (i & 0x10) crc ^= 0x9d;
    if (i & 0x20) crc ^= 0x23;
    if (i & 0x40) crc ^= 0x46;
    if (i & 0x80) crc ^= 0x8c;
    return crc;
}
</syntaxhighlight>


<div class="noprint">
<div class="noprint">

Latest revision as of 04:37, 10 June 2026

General Introduction

LLS Protocol is used in LIGO RS232 / RS485 fuel level sensor with the following parameters:

  • Baud rate: 2400, 4800, 9600, 19200, 38400, 115200 (can be configured by software on PC)
  • Data bits: 8
  • Parity: None
  • Stop bits: 1
  • Flow control: None

LIGO fuel level sensor has 2 working modes:

  1. Slave mode: In this mode, the sensor will respond to all requests from the external device (master device). Each sensor in the network will be distinguished by different addresses configured with the LIGO Configurator software.
  2. Master mode: In this mode the sensor will automatically send data to the external device with a preset interval (message interval).

To enable this mode on the LIGO Configurator software, do the following:

  • Automatic transmission: select HEX (binary) or ASCII or ASCII EXT
Automatic transmission dropdown in LIGO Configurator
  • Set the time of each transfer (Message interval)
Message interval setting in LIGO Configurator

Exchange Protocol Description

The LLS protocol supports two types of exchange protocols: binary (HEX) and character view (transmission of ASCII sequences). It is recommended to use binary exchange protocol.

Format of Binary Protocol Messages

All the commands of the binary communication protocol have the same standardized format which is given in the table:

Sequential number of the field Field name Field size, byte Description
1 Prefix 1 The field is a marker of the message beginning shall have prefix 31h, and an outcoming messages shall be displayed with 3Eh prefix by the program.
2 Network address 1 For prefix 31h specify the network address of the recipient.
For prefix 3Eh specify the network address of the sender.
3 Operation code 1 For prefix 31h specify the code of operation which the program shall perform.
For 3Eh prefix specify the code of operation to which the response is given.
4 Data It depends on the operation code Data composition and format of the field depends on the operation code.
5 Checksum 1 The field is used to control over data integrity.

Single-Stage Data Reading (command 06h)

The command is designed for reading of the current data: relative level, temperature, frequency. The data are transmitted with a lower byte ahead.

Command format

Offset, bytes Field size, bytes Value Description
0 1 31h Prefix
+1 1 00h..FFh Network address of the recipient
+2 1 06h Operation code
+3 1 00h..FFh The checksum

Response format

Offset, bytes Field size, bytes Value Description
0 1 3Eh Prefix
+1 1 00h..FFh Network address of recipient
+2 1 06h Operation code
+3 1 −128…127 Temperature in degrees Celsius
+4 2 0000h…FFFFh Relative level
+6 2 0000h…FFFFh Frequency value
+8 1 00h..FFh Checksum

Periodic Data Output (command 07h)

Command is designed to switch on periodic data output.

After the command is processed, the sensor starts sending data periodically — level, temperature, and frequency — with the time interval prescribed by the 13h command.

Turning off of the periodic data output is performed after receipt of any true command, reset of the processor or disconnection of power supply (if the data output mode is not installed by default).

Command format

Offset, bytes Field size, bytes Value Description
0 1 31h Prefix
+1 1 00h..FFh The Network address of the sender
+2 1 07h Operation code
+3 1 00h..FFh Checksum

Response format

Offset, bytes Field size, bytes Value Description
0 1 3Eh Prefix
+1 1 00h..FFh Network address of recipient
+2 1 07h Operation code
+3 1 00h The command has been executed successfully
01h The command cannot be executed
+4 1 00h..FFh Checksum

Periodic data output format

Offset, bytes Field size, bytes Value Description
0 1 3Eh Prefix
+1 1 00h..FFh The Network address of the sender
+2 1 07h Operation code
+3 1 −128…127 Temperature in degrees Celsius
+4 2 0000h…FFFFh Relative level
+6 2 0000h…FFFFh Frequency value
+8 1 00h..FFh Checksum

Periodic Data Output Interval Adjustment (13h command)

Command is designed to set up interval of periodic data output.

Command format

Offset, bytes Field size, bytes Value Description
0 1 31h Prefix
+1 1 00h..FFh Network address of the recipient
+2 1 13h Operation code
+3 1 0…255 Interval of the data output in seconds
+4 1 00h..FFh Checksum

Response format

Offset, bytes Field size, bytes Value Description
0 1 3Eh Prefix
+1 1 00h..FFh The Network address of the sender
+2 1 13h Operation code
+3 1 00h The command has been executed successfully
01h The command cannot be executed
+4 1 00h..FFh Checksum

Default Data Output Mode (command 17h)

This command determines the order of data output after the sensor is powered on or the processor is reset. After the power is on or the processor is reset, the program will send data periodically via the interface at the time interval prescribed by the 13h command.

Command format

Offset, bytes Field size, bytes Value Description
0 1 31h Prefix
+1 1 00h..FFh Network address of the recipient
+2 1 17h Operation code
+3 1 00h The command has been executed successfully
01h The data are output in binary form
02h The data are output in character-coded form (ASCII mode)
03h The data are output in character-coded form (ASCII EXT mode)
+4 1 00h..FFh Checksum

Response format

Offset, bytes Field size, bytes Value Description
0 1 31h Prefix
+1 1 00h..FFh Network address of the recipient
+2 1 17h Operation code
+3 1 00h The command has been executed successfully
01h The command cannot be executed
+4 1 00h…FFh Checksum

Description of Commands for the Text-Based Protocol

Data exchange via the text-based protocol includes receipt and sending of ASCII symbols sequence interpreted and the request and response commands.

Reading the Data

The command is designed for reading of the current data: relative level, temperature, frequency. The command is a sequence of symbols ASCII "D" and "O". After receipt of the "DO" command the program will response in the form of ASCII symbols sequence.

For example, F=0AF9 t=1A N=03FF.0 <CR><LF>, where F is the current frequency value, t is the current value of temperature in Celsius degrees, N is the level value. All values are in hexadecimal form.

In case the frequency value exceeds FFFh, the data are considered invalid.

Periodic Data Output

The command is designed to switch on periodic data output. After processing the command, the sensor performs periodic data output in the text-based form (ASCII codes) of the following data: relative level, temperature, frequency.

The data are being output periodically with an interval set up when configuring the sensor (LIGO Configurator software). In case the data output interval is set to zero, the data output won't be performed.

Switching on of the periodic data output is done by sending of the "DP" symbols in line. After processing of the command, the symbols line will be received. For example, F=0AF9 t=1A N=03FF.0 <CR><LF>, where F is the current frequency value, t is the current value of temperature in Celsius degrees, N is the level value. Turning off of the periodic data output is performed after receipt of any true command, reset of the processor or disconnection of power supply.

Checksum Calculation Algorithm

The checksum is calculated using Dallas APPLICATION NOTE 27 table method: Understanding and Using Cyclic Redundancy Checks with Dallas Semiconductor iButton Products. One can use the following algorithms to calculate the checksum with a polynom x^8 + x^5 + x^4 + 1 (C language): 

U8 CRC8(U8 data, U8 crc)
{
    U8 i = data ^ crc;
    crc = 0;
    if (i & 0x01) crc ^= 0x5e;
    if (i & 0x02) crc ^= 0xbc;
    if (i & 0x04) crc ^= 0x61;
    if (i & 0x08) crc ^= 0xc2;
    if (i & 0x10) crc ^= 0x9d;
    if (i & 0x20) crc ^= 0x23;
    if (i & 0x40) crc ^= 0x46;
    if (i & 0x80) crc ^= 0x8c;
    return crc;
}

Cross-references to other documents.

Revision History

Loading revision history...

SOJI Electronics
Retrieved from "https://wiki.sojielectronics.com/index.php?title=LIGO_PRO_BLE_Protocol&oldid=1377"