Jump to content

LIGO AIR 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.''
LIGO AIR Protocol utilizes '''Bluetooth Low Energy (BLE)''' to transmit structured fuel sensor data in advertising packets at regular intervals. Data includes fuel level, battery voltage of sensor, temperature, etc. For long-range applications, '''LIGO AIR Adapter''' is recommended to boost reception.


'''What to fill in:'''
In addition to its native protocol, LIGO AIR supports both the '''Escort''' and '''Mielta''' protocols, enabling seamless protocol switching without requiring additional integration effort. Users can configure the desired protocol via the mobile application.
* '''Protocol name and version''' — full name + version number (vd: SOJI Protocol v2.1)
* '''Purpose''' — what data the protocol transmits and to whom
* '''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:'''
* 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:'''
* === Protocol Stack === — layered diagram of protocol stack
* === Roles === — Broadcaster / Observer / Central / Peripheral
* === Security === — encryption, authentication, password protection
 
</div>


== Advertising Message Format ==
== Advertising Message Format ==
<div class="dim">


''Byte-by-byte breakdown of the BLE advertising packet payload.''
Structure of '''Manufacturer Data''' field in advertising message (same for any type of peripheral unit).


'''What to fill in:'''
'''Example Manufacturer Data:''' <code>0x0CFFFC0D024D0100241F000600</code>
* '''Packet overview''' — total packet length, manufacturer ID, structure summary
* '''Field table''' — every field with offset, length, value, description
 
'''Example field breakdown table:'''


{| class="wikitable" style="width:100%;"
{| class="wikitable" style="width:100%;"
|-
|-
! Offset !! Length (bytes) !! Field Name !! Value / Format !! Description
! Sequence number of bytes !! Description !! Example
|-
|-
| 0x00 || 1 || AD Length || 0xXX || Length of the advertising data structure
| 0 || Length of field || <code>0x0C</code>
|-
|-
| 0x01 || 1 || AD Type || 0xFF || Manufacturer Specific Data (per Bluetooth Core spec)
| +1 || Type of field (Manufacturer data) || Always <code>0xFF</code>
|-
|-
| 0x02 || 2 || Company ID || 0xXXXX (LE) || SOJI Electronics SIG-assigned Company ID
| +2 || Company ID || <code>0x0DFC</code>
|-
|-
| 0x04 || 1 || Protocol ID || 0xXX || SOJI Protocol identifier
| +4 || Hardware ID (type of device) || <code>0x02</code> — LIGO Air |
|-
| +5 and further || Payload (sensor parameters) || <code>0x4D0100241F000600</code>
|}
 
In order to distinguish between types of hardware, the '''Hardware ID''' byte is used (see list of hardware below). The Hardware ID byte defines a set of useful parameters from the peripheral unit, their size, and order.
 
{| class="wikitable"
|-
|-
| 0x05 || 1 || Frame Type || 0xXX || Frame type (data frame, status frame, ...)
! Byte of Hardware ID !! Type of Hardware
|-
|-
| 0x06 || N || Payload || ... || Sensor data payload (see Payload Structure below)
| <code>0x02</code> || LIGO Air
|-
|-
| 0x06+N || 2 || CRC-16 || 0xXXXX || CRC-16/CCITT checksum over Offset 0x00 to 0x05+N
| <code>0x03</code> || LIGO Air Pro
|}
|}


'''Sub-sections to consider:'''
''The list of hardware may be expanded.''
* === 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:'''
'''Payload data format of LIGO AIR (Hardware ID <code>0x02</code>) and LIGO AIR Pro (Hardware ID <code>0x03</code>).'''
<syntaxhighlight lang="text">
Raw bytes (hex):
  0E FF 5A A5 01 02 03 04 ...


Decoded:
LIGO Air and LIGO Air Pro have the same payload data format. The structure of the payload is listed in the table below:
  AD Length    = 0x0E (14 bytes)
  AD Type      = 0xFF (Manufacturer Specific)
  Company ID  = 0xA55A (SOJI Electronics)
  Protocol ID  = 0x01 (SOJI Protocol)
  Frame Type  = 0x02 (Data Frame)
  ...
</syntaxhighlight>


'''Example decoding pseudocode:'''
{| class="wikitable" style="width:100%;"
<syntaxhighlight lang="python">
|-
def decode_soji_frame(adv_data: bytes) -> dict:
! Sequence number of bytes !! Parameter type !! Parameter length (bytes) !! Range !! Unit of measurement
    if adv_data[1] != 0xFF:
|-
        return None
| 0 || Fuel level || 2 || 0 to 1023 (option), <br>0 to 4095 (default), <br>or 0 to 65535 (option, liters) || Arbitrary units
    company_id = int.from_bytes(adv_data[2:4], 'little')
|-
    protocol_id = adv_data[4]
| +2 || Reserved || 1 || N/A || N/A
    frame_type = adv_data[5]
|-
    payload = adv_data[6:-2]
| +3 || Built-in battery voltage || 1 || 0 to 255 || Volt × 10
    crc = int.from_bytes(adv_data[-2:], 'little')
|-
    # ... validate CRC, parse payload
| +4 || Temperature || 1 || −128 to 127 || Celsius degrees
    return { ... }
|-
</syntaxhighlight>
| +5 || Reserved || 1 || N/A || N/A
|-
| +6 || Firmware version || 1 || 0 to 255 || Version number
|-
| +7 || Operation Mode || 1 || 0 and 1 || 0: Working Mode <br>1: Storage Mode
|}


</div>
'''Example Payload data:''' <code>0x4D0100241F000600</code>
{| style="border-collapse:collapse;margin:0 auto;text-align:center;font-family:Arial,sans-serif;font-size:11pt;"
|-
| style="border:none;background:transparent;" |
| colspan="7" style="border:none;background:transparent;padding:0 0 6px 0;font-size:50pt;font-family:Consolas,'Courier New',monospace;font-weight:bold;letter-spacing:1px;text-align:center;" | <span style="color:#222">0x</span><span style="color:#5E7440">4D01</span><span style="color:#C99D3F">00</span><span style="color:#3170A8">24</span><span style="color:#1F2D52">1F</span><span style="color:#6E408A">00</span><span style="color:#1A1A1A">06</span><span style="color:#7BC571">00</span>
|-
| style="border:none;background:transparent;" |
! style="background:#5E7440;color:#fff;padding:10px 18px;font-weight:bold;min-width:80px;" | 4D01
! style="background:#C99D3F;color:#fff;padding:10px 18px;font-weight:bold;min-width:50px;" | NA
! style="background:#3170A8;color:#fff;padding:10px 18px;font-weight:bold;min-width:50px;" | 24
! style="background:#1F2D52;color:#fff;padding:10px 18px;font-weight:bold;min-width:50px;" | 1F
! style="background:#6E408A;color:#fff;padding:10px 18px;font-weight:bold;min-width:50px;" | NA
! style="background:#1A1A1A;color:#fff;padding:10px 18px;font-weight:bold;min-width:50px;" | 06
! style="background:#7BC571;color:#fff;padding:10px 18px;font-weight:bold;min-width:50px;" | 00
|-
| style="border:none;background:transparent;" |
| style="border:1px solid #d0d0d0;padding:8px 12px;background:#fafafa;" | Fuel level
| style="border:1px solid #d0d0d0;padding:8px 12px;background:#fafafa;" | Reserved
| style="border:1px solid #d0d0d0;padding:8px 12px;background:#fafafa;" | Battery voltage
| style="border:1px solid #d0d0d0;padding:8px 12px;background:#fafafa;" | Temperature
| style="border:1px solid #d0d0d0;padding:8px 12px;background:#fafafa;" | Reserved
| style="border:1px solid #d0d0d0;padding:8px 12px;background:#fafafa;" | Firmware version
| style="border:1px solid #d0d0d0;padding:8px 12px;background:#fafafa;" | Operation Mode
|-
| style="text-align:right;padding:6px 14px 6px 0;font-style:italic;color:#333;border:none;background:transparent;white-space:nowrap;" | Convert to little-endian (hex)
| style="padding:6px 12px;" | 014D
| style="padding:6px 12px;" | NA
| style="padding:6px 12px;" | 24
| style="padding:6px 12px;" | 1F
| style="padding:6px 12px;" | NA
| style="padding:6px 12px;" | 06
| style="padding:6px 12px;" | 00
|-
| style="text-align:right;padding:6px 14px 6px 0;font-style:italic;color:#333;border:none;background:transparent;white-space:nowrap;" | Convert to decimal
| style="padding:6px 12px;" | 333
| style="padding:6px 12px;" | NA
| style="padding:6px 12px;" | 36
| style="padding:6px 12px;" | 31
| style="padding:6px 12px;" | NA
| style="padding:6px 12px;" | 006
| style="padding:6px 12px;" | 0
|-
| style="text-align:right;padding:6px 14px 6px 0;font-style:italic;color:#333;border:none;background:transparent;white-space:nowrap;" | Convert to value
| style="padding:6px 12px;" | 333 (unit or liter)
| style="padding:6px 12px;" | NA
| style="padding:6px 12px;" | 3.6 Volt
| style="padding:6px 12px;" | 31 ºC
| style="padding:6px 12px;" | NA
| style="padding:6px 12px;" | 0.0.6
| style="padding:6px 12px;" | Working mode
|}


<div class="noprint">


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

Revision as of 10:55, 24 June 2026

General Introduction

LIGO AIR Protocol utilizes Bluetooth Low Energy (BLE) to transmit structured fuel sensor data in advertising packets at regular intervals. Data includes fuel level, battery voltage of sensor, temperature, etc. For long-range applications, LIGO AIR Adapter is recommended to boost reception.

In addition to its native protocol, LIGO AIR supports both the Escort and Mielta protocols, enabling seamless protocol switching without requiring additional integration effort. Users can configure the desired protocol via the mobile application.

Advertising Message Format

Structure of Manufacturer Data field in advertising message (same for any type of peripheral unit).

Example Manufacturer Data: 0x0CFFFC0D024D0100241F000600

Sequence number of bytes Description Example
0 Length of field 0x0C
+1 Type of field (Manufacturer data) Always 0xFF
+2 Company ID 0x0DFC
+4 Hardware ID (type of device)
+5 and further Payload (sensor parameters) 0x4D0100241F000600

In order to distinguish between types of hardware, the Hardware ID byte is used (see list of hardware below). The Hardware ID byte defines a set of useful parameters from the peripheral unit, their size, and order.

Byte of Hardware ID Type of Hardware
0x02 LIGO Air
0x03 LIGO Air Pro

The list of hardware may be expanded.

Payload data format of LIGO AIR (Hardware ID 0x02) and LIGO AIR Pro (Hardware ID 0x03).

LIGO Air and LIGO Air Pro have the same payload data format. The structure of the payload is listed in the table below:

Sequence number of bytes Parameter type Parameter length (bytes) Range Unit of measurement
0 Fuel level 2 0 to 1023 (option),
0 to 4095 (default),
or 0 to 65535 (option, liters)		 Arbitrary units
+2 Reserved 1 N/A N/A
+3 Built-in battery voltage 1 0 to 255 Volt × 10
+4 Temperature 1 −128 to 127 Celsius degrees
+5 Reserved 1 N/A N/A
+6 Firmware version 1 0 to 255 Version number
+7 Operation Mode 1 0 and 1 0: Working Mode
1: Storage Mode

Example Payload data: 0x4D0100241F000600

0x4D0100241F000600
4D01 NA 24 1F NA 06 00
Fuel level Reserved Battery voltage Temperature Reserved Firmware version Operation Mode
Convert to little-endian (hex) 014D NA 24 1F NA 06 00
Convert to decimal 333 NA 36 31 NA 006 0
Convert to value 333 (unit or liter) NA 3.6 Volt 31 ºC NA 0.0.6 Working mode

Revision History

Loading revision history...

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