|
|
| Line 1: |
Line 1: |
| == General Introduction == | | == General Introduction == |
| <div class="dim">
| |
|
| |
|
| ''Brief introduction to the protocol per IEC/IEEE standards for wireless data protocols.''
| |
|
| |
| '''What to fill in:'''
| |
| * '''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.''
| |
|
| |
| '''What to fill in:'''
| |
| * '''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%;"
| |
| |-
| |
| ! Offset !! Length (bytes) !! Field Name !! Value / Format !! Description
| |
| |-
| |
| | 0x00 || 1 || AD Length || 0xXX || Length of the advertising data structure
| |
| |-
| |
| | 0x01 || 1 || AD Type || 0xFF || Manufacturer Specific Data (per Bluetooth Core spec)
| |
| |-
| |
| | 0x02 || 2 || Company ID || 0xXXXX (LE) || SOJI Electronics SIG-assigned Company ID
| |
| |-
| |
| | 0x04 || 1 || Protocol ID || 0xXX || SOJI Protocol identifier
| |
| |-
| |
| | 0x05 || 1 || Frame Type || 0xXX || Frame type (data frame, status frame, ...)
| |
| |-
| |
| | 0x06 || N || Payload || ... || Sensor data payload (see Payload Structure below)
| |
| |-
| |
| | 0x06+N || 2 || CRC-16 || 0xXXXX || CRC-16/CCITT checksum over Offset 0x00 to 0x05+N
| |
| |}
| |
|
| |
| '''Sub-sections to consider:'''
| |
| * === 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:'''
| |
| <syntaxhighlight lang="text">
| |
| Raw bytes (hex):
| |
| 0E FF 5A A5 01 02 03 04 ...
| |
|
| |
| Decoded:
| |
| 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:'''
| |
| <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>
| |
|
| |
|
|
| |
|
