Jump to content

LIGO PRO BLE Protocol: Difference between revisions

From SOJI ELECTRONICS
[checked revision][checked revision]
Newer edit →
Admin (talk | contribs)
Bureaucrats, Interface administrators, Administrators
2,029 edits
VisualWikitext
Create page
Tag: Recreated
 
Initial Release [release]
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:


'''What to fill in:'''
* Baud rate: 2400,4800,9600,19200,38400,115200 (can be configured by software on PC)
* '''Protocol name and version''' — full name + version number (vd: SOJI Protocol v2.1)
* Data bits: 8
* '''Purpose''' — what data the protocol transmits and to whom
* Parity: None
* '''Transport layer''' — Bluetooth 5.4 BLE / WiFi / LoRa / proprietary RF
* Stop bits: 1
* '''Frequency & modulation''' — 2.4 GHz GFSK / LoRa CSS / ...
* Flow control: None
* '''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:'''
LIGO fuel level sensor has 2 working modes:
* Paragraph 1: "The [Protocol Name] is a [type] protocol defined by SOJI Electronics for [purpose]..."
* Paragraph 2: "It operates over [transport] at [frequency] and is supported by [device list]..."


'''Optional sub-sections:'''
# '''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
* === Protocol Stack === — layered diagram of protocol stack
# '''Master mode:''' In this mode the sensor will automatically send data to the external device with a preset interval (message interval)
* === Roles === — Broadcaster / Observer / Central / Peripheral
* === Security === — encryption, authentication, password protection


To enable this mode on the LIGO Configurator software, do the following:
* Automatic transmission: select HEX (binary) or ASCII or ASCII EXT
<div style="text-align:center;">
[[File:LLS-Protocol-Configurator-Automatic-Transmission.png|frameless|219px]]
<div style="font-style:italic; color:#555;">Automatic transmission setting in LIGO Configurator</div>
</div>
* Set the time of each transfer (Message interval)
<div style="text-align:center;">
[[File:LLS-Protocol-Configurator-Message-Interval.png|frameless|228px]]
<div style="font-style:italic; color:#555;">Message interval setting in LIGO Configurator</div>
</div>
</div>


== Advertising Message Format ==
== Exchange Protocol Description ==
<div class="dim">
 
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:
 
{| 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 31h, and an outcoming messages shall be displayed with 3Eh prefix by the program.
|-
| style="text-align:center;" | 2 || Network address || style="text-align:center;" | 1 || For prefix 31h specify the network address of the recipient. <br>For prefix 3Eh specify the network address of the sender.
|-
| style="text-align:center;" | 3 || Operation code || style="text-align:center;" | 1 || For prefix 31h specify the code of operation which the program shall perform For Eh 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 || 31h || style="text-align:left;" | Prefix
|-
| +1 || 1 || 00h..FFh || style="text-align:left;" | Network address of the recipient
|-
| +2 || 1 || 06h || style="text-align:left;" | Operation code
|-
| +3 || 1 || 00h..FFh || style="text-align:left;" | The checksum
|}
 
==== Response format: ====
 
{| class="wikitable" style="text-align:center;"
|-
! Offset, bytes !! Field size, bytes !! Value !! Description
|-
| 0 || 1 || 3Eh || style="text-align:left;" | Prefix
|-
| +1 || 1 || 00h..FFh || style="text-align:left;" | Network address of recipient
|-
| +2 || 1 || 06h || style="text-align:left;" | Operation code
|-
| +3 || 1 || -128…127 || style="text-align:left;" | Temperature in in degrees Celsius
|-
| +4 || 2 || 0000h…FFFFh || style="text-align:left;" | Relative level
|-
| +6 || 2 || 0000h…FFFFh || style="text-align:left;" | Frequency value
|-
| +8 || 1 || 00h..FFh || style="text-align:left;" | Checksum
|}
 
=== Periodic Data Output (command 07h) ===
 
Command is designed to switch on periodic data output.


''Byte-by-byte breakdown of the BLE advertising packet payload.''
After the command is processed, the sensor starts sending data periodically — level, temperature, and frequency — with the time interval prescribed by the 13h command.


'''What to fill in:'''
Turning off of the periodic data output is performed after receipt of any true command, reset of the processor or disconnection of power power supply (if the data output mode is not istalled by default).
* '''Packet overview''' — total packet length, manufacturer ID, structure summary
* '''Field table''' — every field with offset, length, value, description


'''Example field breakdown table:'''
==== Command format ====


{| class="wikitable" style="width:100%;"
{| class="wikitable" style="text-align:center;"
|-
|-
! Offset !! Length (bytes) !! Field Name !! Value / Format !! Description
! Offset, bytes !! Field size, bytes !! Value !! Description
|-
|-
| 0x00 || 1 || AD Length || 0xXX || Length of the advertising data structure
| 0 || 1 || 31h || style="text-align:left;" | Prefix
|-
|-
| 0x01 || 1 || AD Type || 0xFF || Manufacturer Specific Data (per Bluetooth Core spec)
| +1 || 1 || 00h..FFh || style="text-align:left;" | The Network address of the sender
|-
|-
| 0x02 || 2 || Company ID || 0xXXXX (LE) || SOJI Electronics SIG-assigned Company ID
| +2 || 1 || 07h || style="text-align:left;" | Operation code
|-
|-
| 0x04 || 1 || Protocol ID || 0xXX || SOJI Protocol identifier
| +3 || 1 || 00h..FFh || style="text-align:left;" | Checksum
|}
 
==== Response format ====
 
{| class="wikitable" style="text-align:center;"
|-
|-
| 0x05 || 1 || Frame Type || 0xXX || Frame type (data frame, status frame, ...)
! Offset, bytes !! Field size, bytes !! Value !! Description
|-
|-
| 0x06 || N || Payload || ... || Sensor data payload (see Payload Structure below)
| 0 || 1 || 3Eh || style="text-align:left;" | Prefix
|-
|-
| 0x06+N || 2 || CRC-16 || 0xXXXX || CRC-16/CCITT checksum over Offset 0x00 to 0x05+N
| +1 || 1 || 00h..FFh || style="text-align:left;" | Network address of recipient
|-
| +2 || 1 || 07h || style="text-align:left;" | Operation code
|-
| rowspan="2" | +3 || rowspan="2" | 1 || 00h || style="text-align:left;" | The command has been executed successfully
|-
| 01h || style="text-align:left;" | The command cannot be executed
|-
| +4 || 1 || 00h..FFh || style="text-align:left;" | Checksum
|}
 
==== Periodic data output format ====
 
{| class="wikitable" style="text-align:center;"
|-
! Offset, bytes !! Field size, bytes !! Value !! Description
|-
| 0 || 1 || 3Eh || style="text-align:left;" | Prefix
|-
| +1 || 1 || 00h..FFh || style="text-align:left;" | The Network address of the sender
|-
| +2 || 1 || 07h || style="text-align:left;" | Operation code
|-
| +3 || 1 || -128…127 || style="text-align:left;" | Temperature in in degrees Celsius
|-
| +4 || 2 || 0000h…FFFFh || style="text-align:left;" | Relative level
|-
| +6 || 2 || 0000h…FFFFh || style="text-align:left;" | Frequency value
|-
| +8 || 1 || 00h..FFh || style="text-align:left;" | Checksum
|}
|}


'''Sub-sections to consider:'''
=== Periodic Data Output Interval Adjustment (13h command) ===
* === 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:'''
Command is designed to set up interval of periodic data output.
<syntaxhighlight lang="text">
Raw bytes (hex):
  0E FF 5A A5 01 02 03 04 ...


Decoded:
==== Command format ====
  AD Length    = 0x0E (14 bytes)
 
  AD Type      = 0xFF (Manufacturer Specific)
{| class="wikitable" style="text-align:center;"
  Company ID  = 0xA55A (SOJI Electronics)
|-
  Protocol ID  = 0x01 (SOJI Protocol)
! Offset, bytes !! Field size, bytes !! Value !! Description
  Frame Type  = 0x02 (Data Frame)
|-
  ...
| 0 || 1 || 31h || style="text-align:left;" | Prefix
</syntaxhighlight>
|-
| +1 || 1 || 00h..FFh || style="text-align:left;" | Network address of the recipient
|-
| +2 || 1 || 13h || style="text-align:left;" | Operation code
|-
| +3 || 1 || 0…255 || style="text-align:left;" | Interval of the data output in seconds
|-
| +4 || 1 || 00h..FFh || style="text-align:left;" | Checksum
|}
 
==== Response format ====
 
{| class="wikitable" style="text-align:center;"
|-
! Offset, bytes !! Field size, bytes !! Value !! Description
|-
| 0 || 1 || 3Eh || style="text-align:left;" | Prefix
|-
| +1 || 1 || 00h..FFh || style="text-align:left;" | The Network address of the sender
|-
| +2 || 1 || 13h || style="text-align:left;" | Operation code
|-
| rowspan="2" | +3 || rowspan="2" | 1 || 00h || style="text-align:left;" | The command has been executed successfully
|-
| 01h || style="text-align:left;" | The command cannot be executed
|-
| +4 || 1 || 00h..FFh || 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 13h command.
 
==== Command format ====
 
{| class="wikitable" style="text-align:center;"
|-
! Offset, bytes !! Field size, bytes !! Value !! Description
|-
| 0 || 1 || 31h || style="text-align:left;" | Prefix
|-
| +1 || 1 || 00h..FFh || style="text-align:left;" | Network address of the recipient
|-
| +2 || 1 || 17h || style="text-align:left;" | Operation code
|-
| rowspan="4" | +3 || rowspan="4" | 1 || 00h || style="text-align:left;" | The command has been executed successfully
|-
| 01h || style="text-align:left;" | The data are output in binary form
|-
| 02h || style="text-align:left;" | The data are output in character-coded form (ASCII mode)
|-
| 03h || style="text-align:left;" | The data are output in character-coded form (ASCII EXT mode)
|-
| +4 || 1 || 00h..FFh || style="text-align:left;" | Checksum
|}
 
==== Response format ====
 
{| class="wikitable" style="text-align:center;"
|-
! Offset, bytes !! Field size, bytes !! Value !! Description
|-
| 0 || 1 || 31h || style="text-align:left;" | Prefix
|-
| +1 || 1 || 00h..FFh || style="text-align:left;" | Network address of the recipient
|-
| +2 || 1 || 17h || style="text-align:left;" | Operation code
|-
| rowspan="2" | +3 || rowspan="2" | 1 || 00h || style="text-align:left;" | The command has been executed successfully
|-
| 01h || style="text-align:left;" | The command cannot be executed
|-
| +4 || 1 || 00h…FFh || 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.
 
=== 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 &lt;CR&gt;&lt;LF&gt;, where F is the current frequency value, t is the current value of temperature in Celcius 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 cofiguring 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 &lt;CR&gt;&lt;LF&gt;, where F is the current frequency value, t is the current value of temperature in Celcius 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 <code>x^8 + x^5 + x^4 + 1</code> (C language):


'''Example decoding pseudocode:'''
<syntaxhighlight lang="c" line>
<syntaxhighlight lang="python">
U8 CRC8(U8 data, U8 crc)
def decode_soji_frame(adv_data: bytes) -> dict:
{
     if adv_data[1] != 0xFF:
     U8 i = data ^ crc;
        return None
    crc = 0;
     company_id = int.from_bytes(adv_data[2:4], 'little')
     if (i & 0x01) crc ^= 0x5e;
     protocol_id = adv_data[4]
    if (i & 0x02) crc ^= 0xbc;
     frame_type = adv_data[5]
     if (i & 0x04) crc ^= 0x61;
     payload = adv_data[6:-2]
     if (i & 0x08) crc ^= 0xc2;
     crc = int.from_bytes(adv_data[-2:], 'little')
     if (i & 0x10) crc ^= 0x9d;
     # ... validate CRC, parse payload
     if (i & 0x20) crc ^= 0x23;
     return { ... }
    if (i & 0x40) crc ^= 0x46;
     if (i & 0x80) crc ^= 0x8c;
     return crc;
}
</syntaxhighlight>
</syntaxhighlight>


</div>


<div class="noprint">


<div class="noprint">
== Related Documents ==
== Related Documents ==
''Cross-references to other documents.''
''Cross-references to other documents.''

Revision as of 10:56, 24 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

Error creating thumbnail: Unable to save thumbnail to destination

Automatic transmission setting in LIGO Configurator
  • Set the time of each transfer (Message interval)

Error creating thumbnail: Unable to save thumbnail to destination

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 Eh 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 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 power supply (if the data output mode is not istalled 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 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 Celcius 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 cofiguring 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 Celcius 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=2064"