Files
meshcore-open/lib/connector/meshcore_protocol.dart
T
2026-11-08 00:40:23 +01:00

1279 lines
41 KiB
Dart
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
import 'dart:convert';
import 'dart:typed_data';
import 'package:crypto/crypto.dart' as crypto;
import 'package:flutter/widgets.dart';
// Buffer Reader - sequential binary data reader with pointer tracking
class BufferReader {
int _pointer = 0;
int _lastPointer = 0;
final Uint8List _buffer;
BufferReader(Uint8List data) : _buffer = Uint8List.fromList(data);
int get remaining => _buffer.length - _pointer;
int readByte() => readBytes(1)[0];
Uint8List readBytes(int count) {
_lastPointer = _pointer;
if (_pointer + count > _buffer.length) {
throw RangeError(
'Attempted to read $count bytes at offset $_pointer, but only $remaining bytes remaining in buffer of length ${_buffer.length}',
);
}
final data = _buffer.sublist(_pointer, _pointer + count);
_pointer += count;
return data;
}
void skipBytes(int count) {
_lastPointer = _pointer;
if (_pointer + count > _buffer.length) {
throw RangeError(
'Attempted to skip $count bytes at offset $_pointer, but only $remaining bytes remaining in buffer of length ${_buffer.length}',
);
}
_pointer += count;
}
Uint8List readRemainingBytes() => readBytes(remaining);
String readCStringGreedy(int maxLength) {
_lastPointer = _pointer;
final value = <int>[];
final bytes = readBytes(maxLength);
for (final byte in bytes) {
if (byte == 0) break;
value.add(byte);
}
try {
return utf8.decode(Uint8List.fromList(value), allowMalformed: true);
} catch (e) {
return String.fromCharCodes(value); // Latin-1 fallback
}
}
String readCString({int maxLength = -1}) {
final backupPointer = _pointer;
final value = <int>[];
int counter = 0;
final maxLen = maxLength >= 0 ? maxLength : remaining;
while (counter < maxLen) {
final byte = readByte();
if (byte == 0) break;
value.add(byte);
counter++;
}
_lastPointer = backupPointer;
try {
return utf8.decode(Uint8List.fromList(value), allowMalformed: true);
} catch (e) {
return String.fromCharCodes(value); // Latin-1 fallback
}
}
int readUInt8() => readBytes(1).buffer.asByteData().getUint8(0);
int readInt8() => readBytes(1).buffer.asByteData().getInt8(0);
int readUInt16LE() =>
readBytes(2).buffer.asByteData().getUint16(0, Endian.little);
int readUInt16BE() =>
readBytes(2).buffer.asByteData().getUint16(0, Endian.big);
int readUInt32LE() =>
readBytes(4).buffer.asByteData().getUint32(0, Endian.little);
int readUInt32BE() =>
readBytes(4).buffer.asByteData().getUint32(0, Endian.big);
int readInt16LE() =>
readBytes(2).buffer.asByteData().getInt16(0, Endian.little);
int readInt16BE() => readBytes(2).buffer.asByteData().getInt16(0, Endian.big);
int readInt32LE() =>
readBytes(4).buffer.asByteData().getInt32(0, Endian.little);
int readInt24BE() {
var value = (readByte() << 16) | (readByte() << 8) | readByte();
if ((value & 0x800000) != 0) value -= 0x1000000;
return value;
}
void resetPointer() => _pointer = 0;
void rewind() => _pointer = _lastPointer;
}
// Buffer Writer - accumulating binary data builder
class BufferWriter {
final BytesBuilder _builder = BytesBuilder();
Uint8List toBytes() => _builder.toBytes();
void writeByte(int byte) => _builder.addByte(byte);
void writeBytes(Uint8List bytes) => _builder.add(bytes);
void writeUInt16LE(int num) {
final bytes = Uint8List(2)
..buffer.asByteData().setUint16(0, num, Endian.little);
writeBytes(bytes);
}
void writeUInt32LE(int num) {
final bytes = Uint8List(4)
..buffer.asByteData().setUint32(0, num, Endian.little);
writeBytes(bytes);
}
void writeInt32LE(int num) {
final bytes = Uint8List(4)
..buffer.asByteData().setInt32(0, num, Endian.little);
writeBytes(bytes);
}
void writeString(String string) =>
writeBytes(Uint8List.fromList(utf8.encode(string)));
void writeCString(String string, int maxLength) {
final bytes = Uint8List(maxLength);
final encoded = utf8.encode(string);
final len = utf8BoundaryLength(encoded, maxLength - 1);
bytes.setRange(0, len, encoded);
writeBytes(bytes);
}
void writeHex(String hex) {
writeBytes(hex2Uint8List(hex));
}
void writeBytesPadded(Uint8List bytes, int totalLength) {
// Path data (64 bytes, zero-padded)
final bytesPadded = Uint8List(totalLength);
final len = bytes.length < totalLength ? bytes.length : totalLength;
if (bytes.isNotEmpty && len > 0) {
final copyLen = bytes.length < totalLength ? bytes.length : totalLength;
for (int i = 0; i < copyLen; i++) {
bytesPadded[i] = bytes[i];
}
}
writeBytes(bytesPadded);
}
}
Uint8List hex2Uint8List(String hex) {
// Validate hex string length is even and not empty
if (hex.isEmpty || hex.length % 2 != 0) {
throw FormatException('Invalid hex string length: ${hex.length}');
}
List<int> result = [];
for (int i = 0; i < hex.length ~/ 2; i++) {
final hexByte = hex.substring(i * 2, i * 2 + 2);
final byte = int.tryParse(hexByte, radix: 16);
if (byte == null) {
throw FormatException('Invalid hex characters at position $i: $hexByte');
}
result.add(byte);
}
return Uint8List.fromList(result);
}
// Command codes (to device)
const int cmdAppStart = 1;
const int cmdSendTxtMsg = 2;
const int cmdSendChannelTxtMsg = 3;
const int cmdGetContacts = 4;
const int cmdGetDeviceTime = 5;
const int cmdSetDeviceTime = 6;
const int cmdSendSelfAdvert = 7;
const int cmdSetAdvertName = 8;
const int cmdAddUpdateContact = 9;
const int cmdSyncNextMessage = 10;
const int cmdSetRadioParams = 11;
const int cmdSetRadioTxPower = 12;
const int cmdResetPath = 13;
const int cmdSetAdvertLatLon = 14;
const int cmdRemoveContact = 15;
const int cmdShareContact = 16;
const int cmdExportContact = 17;
const int cmdImportContact = 18;
const int cmdReboot = 19;
const int cmdGetBattAndStorage = 20;
const int cmdDeviceQuery = 22;
const int cmdExportPrivateKey = 23;
const int cmdImportPrivateKey = 24;
const int cmdSendLogin = 26;
const int cmdSendStatusReq = 27;
const int cmdGetContactByKey = 30;
const int cmdGetChannel = 31;
const int cmdSetChannel = 32;
const int cmdSendTracePath = 36;
const int cmdSetOtherParams = 38;
const int cmdSendTelemetryReq = 39;
const int cmdGetCustomVar = 40;
const int cmdSetCustomVar = 41;
const int cmdSendBinaryReq = 50;
const int cmdSetFloodScope = 54;
const int cmdSendControlData = 55;
const int cmdGetStats = 56;
const int cmdSendAnonReq = 57;
const int cmdSetAutoAddConfig = 58;
const int cmdGetAutoAddConfig = 59;
const int cmdGetAllowedRepeatFreq = 60;
const int cmdSetPathHashMode = 61;
const int cmdSetDefaultFloodScope = 63; // FIRMWARE_VER_CODE 11+
const int cmdGetDefaultFloodScope = 64; // FIRMWARE_VER_CODE 11+
// Text message types
const int txtTypePlain = 0;
const int txtTypeCliData = 1;
const int txtTypeSigned = 2;
// Repeater request types (for server requests)
const int reqTypeGetStatus = 0x01;
const int reqTypeKeepAlive = 0x02;
const int reqTypeGetTelemetry = 0x03;
const int reqTypeGetAccessList = 0x05;
const int reqTypeGetNeighbors = 0x06;
Uint8List buildTelemetryBinaryPayload() {
// Room servers/repeaters read byte 1 as an inverse telemetry permission mask.
// Zero means "request every telemetry field allowed for this contact".
return Uint8List.fromList([reqTypeGetTelemetry, 0x00, 0x00, 0x00, 0x00]);
}
const int anonReqTypeRegions = 0x01;
// Control data sub-types used by MeshCore discovery packets.
const int controlSubtypeDiscoverReq = 0x08;
const int controlSubtypeDiscoverResp = 0x09;
// Repeater response codes
const int respServerLoginOk = 0;
// Response codes (from device)
const int respCodeOk = 0;
const int respCodeErr = 1;
const int respCodeContactsStart = 2;
const int respCodeContact = 3;
const int respCodeEndOfContacts = 4;
const int respCodeSelfInfo = 5;
const int respCodeSent = 6;
const int respCodeContactMsgRecv = 7;
const int respCodeChannelMsgRecv = 8;
const int respCodeCurrTime = 9;
const int respCodeNoMoreMessages = 10;
const int respCodeExportContact = 11;
const int respCodeBattAndStorage = 12;
const int respCodeDeviceInfo = 13;
const int respCodePrivateKey = 14;
const int respCodeDisabled = 15;
const int respCodeContactMsgRecvV3 = 16;
const int respCodeChannelMsgRecvV3 = 17;
const int respCodeChannelInfo = 18;
const int respCodeCustomVars = 21;
const int respCodeAutoAddConfig = 25;
const int respCodeAllowedRepeatFreq = 26;
const int respCodeStats = 24;
const int respCodeDefaultFloodScope = 28;
/// Region name field width in SET/GET_DEFAULT_FLOOD_SCOPE frames (NUL padded,
/// so at most 30 name bytes).
const int defaultFloodScopeNameSize = 31;
const int floodScopeKeySize = 16;
const int statsTypeCore = 0;
const int statsTypeRadio = 1;
const int statsTypePackets = 2;
// Push codes (async from device)
const int pushCodeAdvert = 0x80;
const int pushCodePathUpdated = 0x81;
const int pushCodeSendConfirmed = 0x82;
const int pushCodeMsgWaiting = 0x83;
const int pushCodeLoginSuccess = 0x85;
const int pushCodeLoginFail = 0x86;
const int pushCodeStatusResponse = 0x87;
const int pushCodeLogRxData = 0x88;
const int pushCodeTraceData = 0x89;
const int pushCodeNewAdvert = 0x8A;
const int pushCodeTelemetryResponse = 0x8B;
const int pushCodeBinaryResponse = 0x8C;
const int pushCodeControlData = 0x8E;
const int pushCodeContactDeleted = 0x8F;
const int pushCodeContactsFull = 0x90;
// Contact/advertisement types
const int advTypeChat = 1;
const int advTypeRepeater = 2;
const int advTypeRoom = 3;
const int advTypeSensor = 4;
const int teleModeDeny = 0;
const int teleModeAllowFlags = 1; // use contact.flags
const int teleModeAllowAll = 2;
// Payload Types
const int payloadTypeREQ =
0x00; // request (prefixed with dest/src hashes, MAC) (enc data: timestamp, blob)
const int payloadTypeRESPONSE =
0x01; // response to REQ or ANON_REQ (prefixed with dest/src hashes, MAC) (enc data: timestamp, blob)
const int payloadTypeTXTMSG =
0x02; // a plain text message (prefixed with dest/src hashes, MAC) (enc data: timestamp, text)
const int payloadTypeACK = 0x03; // a simple ack
const int payloadTypeADVERT = 0x04; // a node advertising its Identity
const int payloadTypeGRPTXT =
0x05; // an (unverified) group text message (prefixed with channel hash, MAC) (enc data: timestamp, "name: msg")
const int payloadTypeGRPDATA =
0x06; // an (unverified) group datagram (prefixed with channel hash, MAC) (enc data: timestamp, blob)
const int payloadTypeANONREQ =
0x07; // generic request (prefixed with dest_hash, ephemeral pub_key, MAC) (enc data: ...)
const int payloadTypePATH =
0x08; // returned path (prefixed with dest/src hashes, MAC) (enc data: path, extra)
const int payloadTypeTRACE = 0x09; // trace a path, collecting SNI for each hop
const int payloadTypeMULTIPART = 0x0A; // packet is one of a set of packets
const int payloadTypeCONTROL = 0x0B; // a control/discovery packet
//...
const int payloadTypeRawCustom =
0x0F; // custom packet as raw bytes, for applications with custom encryption, payloads, etc
//auto-add flags
const int autoAddOverwriteOldestFlag =
1 << 0; // 0x01 - overwrite oldest non-favourite when full
const int autoAddChatFlag =
1 << 1; // 0x02 - auto-add Chat (Companion) (ADV_TYPE_CHAT)
const int autoAddRepeaterFlag =
1 << 2; // 0x04 - auto-add Repeater (ADV_TYPE_REPEATER)
const int autoAddRoomServerFlag =
1 << 3; // 0x08 - auto-add Room Server (ADV_TYPE_ROOM)
const int autoAddSensorFlag =
1 << 4; // 0x10 - auto-add Sensor (ADV_TYPE_SENSOR)
/// Returns the largest prefix length of [bytes] that is at most [maxBytes]
/// and does not end in the middle of a UTF-8 encoded character.
int utf8BoundaryLength(List<int> bytes, int maxBytes) {
if (bytes.length <= maxBytes) return bytes.length;
if (maxBytes <= 0) return 0;
var len = maxBytes;
// Back up over continuation bytes (10xxxxxx) to the lead byte, then drop
// that lead byte too since its character would be cut short.
while (len > 0 && (bytes[len] & 0xC0) == 0x80) {
len--;
}
return len;
}
// Sizes
const int pubKeySize = 32;
const int signatureSize = 64;
const int maxPathSize = 64;
const int pathHashSize = 1;
const int maxNameSize = 32;
// Largest frame the app sends. Kept at 172 so commands still fit radios on
// firmware built before MAX_FRAME_SIZE grew to 176.
const int maxFrameSize = 172;
// Largest frame current firmware may send (MAX_FRAME_SIZE 176, +4 bytes for
// region transport codes). Receive paths must accept frames up to this size.
const int maxRxFrameSize = 176;
// Widest per-hop path hash firmware accepts on air (mode 2); 4 is reserved.
const int maxPathHashWidth = 3;
const int appProtocolVersion = 4;
// Matches firmware MAX_TEXT_LEN (10 * CIPHER_BLOCK_SIZE).
const int maxTextPayloadBytes = 160;
// From attempt 4 on the firmware appends [0][attempt] to the DM payload, so
// the text must fit in MAX_TEXT_LEN - 2 (BaseChatMesh::composeMsgPacket).
const int maxFullLengthTextAttempt = 3;
const int maxTextPayloadBytesAfterFullLengthAttempts = maxTextPayloadBytes - 2;
const int _sendTextMsgOverheadBytes =
1 + 1 + 1 + 4 + 6 + 1 + 2; // +2 safety margin
const int _sendChannelTextMsgOverheadBytes =
1 + 1 + 1 + 4 + 1 + 2; // +2 safety margin
int maxContactMessageBytes() {
final byFrame = maxFrameSize - _sendTextMsgOverheadBytes;
return _minPositive(byFrame, maxTextPayloadBytes);
}
int maxChannelMessageBytes(String? senderName) {
final nameLength = _senderNameBytes(senderName);
final prefixBytes = nameLength + 2; // "<name>: "
final byPayload = maxTextPayloadBytes - prefixBytes;
final byFrame = maxFrameSize - _sendChannelTextMsgOverheadBytes;
return _minPositive(byPayload, byFrame);
}
int _senderNameBytes(String? senderName) {
if (senderName == null || senderName.isEmpty) return maxNameSize - 1;
final bytes = utf8.encode(senderName);
final maxBytes = maxNameSize - 1;
return bytes.length > maxBytes ? maxBytes : bytes.length;
}
int _minPositive(int a, int b) {
final minValue = a < b ? a : b;
return minValue < 0 ? 0 : minValue;
}
// Contact frame offsets
const int contactPubKeyOffset = 1;
const int contactTypeOffset = 33;
const int contactFlagsOffset = 34;
const int contactFlagFavorite = 0x01;
const int contactFlagTeleBase = 0x02; // 'base' permission includes battery
const int contactFlagTeleLoc = 0x04;
const int contactFlagTeleEnv = 0x08; //access environment sensors
const int contactPathLenOffset = 35;
const int contactPathOffset = 36;
const int contactNameOffset = 100;
const int contactTimestampOffset = 132;
const int contactLatOffset = 136;
const int contactLonOffset = 140;
const int contactLastModOffset = 144;
const int contactFrameSize = 148;
// Message frame offsets
const int msgPubKeyOffset = 1;
const int msgTimestampOffset = 33;
const int msgFlagsOffset = 37;
const int msgTextOffset = 38;
class ParsedContactText {
final Uint8List senderPrefix;
final String text;
const ParsedContactText({required this.senderPrefix, required this.text});
}
ParsedContactText? parseContactMessageText(Uint8List frame) {
if (frame.isEmpty) return null;
final message = BufferReader(frame);
try {
final code = message.readByte();
if (code != respCodeContactMsgRecv && code != respCodeContactMsgRecvV3) {
return null;
}
// Companion radio layout:
// [code][snr?][res?][res?][prefix x6][path_len][txt_type][timestamp x4][extra?][text...]
if (code == respCodeContactMsgRecvV3) {
// Skip SNR and reserved bytes in v3 layout
message.skipBytes(3);
}
final senderPrefix = message.readBytes(6); // public key
message.skipBytes(1); // path length
final textType = message.readByte();
message.skipBytes(4); // timestamp (4 bytes)
final shiftedType = textType >> 2;
final isSigned = shiftedType == txtTypeSigned || textType == txtTypeSigned;
if (isSigned) {
// Signed messages have a 4-byte signature after the timestamp, before the text
message.skipBytes(4);
}
final text = message.readCString();
if (text.isEmpty) return null;
return ParsedContactText(senderPrefix: senderPrefix, text: text);
} catch (e) {
debugPrint('Error parsing contact message text: $e');
return null;
}
}
// Helper to read uint32 little-endian
int readUint32LE(Uint8List data, int offset) {
return data[offset] |
(data[offset + 1] << 8) |
(data[offset + 2] << 16) |
(data[offset + 3] << 24);
}
// Helper to read uint16 little-endian
int readUint16LE(Uint8List data, int offset) {
return data[offset] | (data[offset + 1] << 8);
}
// Helper to read int32 little-endian
int readInt32LE(Uint8List data, int offset) {
int val = readUint32LE(data, offset);
if (val >= 0x80000000) val -= 0x100000000;
return val;
}
// Helper to convert uint32 to hex string
String ackHashToHex(int ackHash) {
return ackHash.toRadixString(16).padLeft(8, '0');
}
// Helper to convert public key to hex string
const String _hexDigits = '0123456789abcdef';
String pubKeyToHex(Uint8List pubKey) {
final codes = Uint8List(pubKey.length * 2);
for (var i = 0; i < pubKey.length; i++) {
final b = pubKey[i];
codes[i * 2] = _hexDigits.codeUnitAt(b >> 4);
codes[i * 2 + 1] = _hexDigits.codeUnitAt(b & 0x0F);
}
return String.fromCharCodes(codes);
}
// Helper to convert hex string to public key
Uint8List hexToPubKey(String hex) {
if (hex.length != pubKeySize * 2) {
throw FormatException(
'Public key hex must be ${pubKeySize * 2} chars, got ${hex.length}',
);
}
final result = Uint8List(pubKeySize);
for (int i = 0; i < pubKeySize; i++) {
result[i] = int.parse(hex.substring(i * 2, i * 2 + 2), radix: 16);
}
return result;
}
// Build CMD_GET_CONTACTS frame
Uint8List buildGetContactsFrame({int? since}) {
final writer = BufferWriter();
writer.writeByte(cmdGetContacts);
if (since != null) {
writer.writeUInt32LE(since);
}
return writer.toBytes();
}
// Build CMD_SEND_LOGIN frame
// Format: [cmd][pub_key x32][password...]\0
Uint8List buildSendLoginFrame(Uint8List recipientPubKey, String password) {
final writer = BufferWriter();
writer.writeByte(cmdSendLogin);
writer.writeBytes(recipientPubKey);
writer.writeString(password);
writer.writeByte(0);
return writer.toBytes();
}
// Build CMD_SEND_STATUS_REQ frame
// Format: [cmd][pub_key x32]
Uint8List buildSendStatusRequestFrame(Uint8List recipientPubKey) {
final writer = BufferWriter();
writer.writeByte(cmdSendStatusReq);
writer.writeBytes(recipientPubKey);
return writer.toBytes();
}
// Build CMD_SEND_TXT_MSG frame (companion_radio format)
// Format: [cmd][txt_type][attempt][timestamp x4][pub_key_prefix x6][text...]\0
Uint8List buildSendTextMsgFrame(
Uint8List recipientPubKey,
String text, {
int attempt = 0,
int? timestampSeconds,
}) {
final timestamp =
timestampSeconds ?? (DateTime.now().millisecondsSinceEpoch ~/ 1000);
final writer = BufferWriter();
writer.writeByte(cmdSendTxtMsg);
writer.writeByte(txtTypePlain);
writer.writeByte(attempt.clamp(0, 255));
writer.writeUInt32LE(timestamp);
writer.writeBytes(recipientPubKey.sublist(0, 6));
writer.writeString(text);
writer.writeByte(0);
return writer.toBytes();
}
// Build CMD_SEND_CHANNEL_TXT_MSG frame
// Format: [cmd][txt_type][channel_idx][timestamp x4][text...]
Uint8List buildSendChannelTextMsgFrame(
int channelIndex,
String text, {
int? timestamp,
}) {
timestamp ??= DateTime.now().millisecondsSinceEpoch ~/ 1000;
final writer = BufferWriter();
writer.writeByte(cmdSendChannelTxtMsg);
writer.writeByte(txtTypePlain);
writer.writeByte(channelIndex);
writer.writeUInt32LE(timestamp);
writer.writeString(text);
writer.writeByte(0);
return writer.toBytes();
}
// Build CMD_REMOVE_CONTACT frame
Uint8List buildRemoveContactFrame(Uint8List pubKey) {
final writer = BufferWriter();
writer.writeByte(cmdRemoveContact);
writer.writeBytes(pubKey);
return writer.toBytes();
}
// Build CMD_APP_START frame
// Format: [cmd][app_ver][reserved x6][app_name...]
Uint8List buildAppStartFrame({
String appName = 'MeshCoreOpen',
int appVersion = 1,
}) {
final writer = BufferWriter();
writer.writeByte(cmdAppStart);
writer.writeByte(appVersion);
writer.writeBytes(Uint8List(6)); // reserved bytes
writer.writeString(appName);
writer.writeByte(0);
return writer.toBytes();
}
// Build CMD_DEVICE_QUERY frame
Uint8List buildDeviceQueryFrame({int appVersion = appProtocolVersion}) {
return Uint8List.fromList([cmdDeviceQuery, appVersion]);
}
// Build CMD_GET_DEVICE_TIME frame
Uint8List buildGetDeviceTimeFrame() {
return Uint8List.fromList([cmdGetDeviceTime]);
}
// Build CMD_GET_BATT_AND_STORAGE frame
Uint8List buildGetBattAndStorageFrame() {
return Uint8List.fromList([cmdGetBattAndStorage]);
}
/// Companion radio stats: [56][statsType] where statsType is statsTypeCore/Radio/Packets.
Uint8List buildGetStatsFrame(int statsType) {
return Uint8List.fromList([cmdGetStats, statsType & 0xFF]);
}
/// Path hash width on air: [61][0][mode], mode 0..2 → (mode+1) bytes per hop
/// hash. Firmware rejects mode 3 (4-byte hashes are reserved).
Uint8List buildSetPathHashModeFrame(int mode) {
final m = mode.clamp(0, 2).toInt();
return Uint8List.fromList([cmdSetPathHashMode, 0, m]);
}
// Build CMD_SET_DEVICE_TIME frame
Uint8List buildSetDeviceTimeFrame(int timestamp) {
final writer = BufferWriter();
writer.writeByte(cmdSetDeviceTime);
writer.writeUInt32LE(timestamp);
return writer.toBytes();
}
// Build CMD_SEND_SELF_ADVERT frame
// Format: [cmd][flood_flag]
Uint8List buildSendSelfAdvertFrame({bool flood = false}) {
return Uint8List.fromList([cmdSendSelfAdvert, flood ? 1 : 0]);
}
// Build CMD_SET_ADVERT_NAME frame
// Format: [cmd][name...]
Uint8List buildSetAdvertNameFrame(String name) {
final nameBytes = utf8.encode(name);
final nameLen = utf8BoundaryLength(nameBytes, maxNameSize - 1);
final writer = BufferWriter();
writer.writeByte(cmdSetAdvertName);
writer.writeBytes(Uint8List.fromList(nameBytes.sublist(0, nameLen)));
return writer.toBytes();
}
// Build CMD_SET_ADVERT_LATLON frame
// Format: [cmd][lat x4][lon x4]
Uint8List buildSetAdvertLatLonFrame(double lat, double lon) {
final writer = BufferWriter();
writer.writeByte(cmdSetAdvertLatLon);
writer.writeInt32LE((lat * 1000000).round());
writer.writeInt32LE((lon * 1000000).round());
return writer.toBytes();
}
Uint8List buildSetCustomVarFrame(String value) {
final writer = BufferWriter();
writer.writeByte(cmdSetCustomVar);
writer.writeString(value);
writer.writeByte(0);
return writer.toBytes();
}
// Build CMD_REBOOT frame
// Format: [cmd]["reboot"]
Uint8List buildRebootFrame() {
return Uint8List.fromList([cmdReboot, ...utf8.encode('reboot')]);
}
// Build CMD_SYNC_NEXT_MESSAGE frame
Uint8List buildSyncNextMessageFrame() {
return Uint8List.fromList([cmdSyncNextMessage]);
}
// Build CMD_GET_CHANNEL frame
Uint8List buildGetChannelFrame(int channelIndex) {
return Uint8List.fromList([cmdGetChannel, channelIndex]);
}
// Build CMD_SET_CHANNEL frame
// Format: [cmd][idx][name x32][psk x16]
Uint8List buildSetChannelFrame(int channelIndex, String name, Uint8List psk) {
final writer = BufferWriter();
writer.writeByte(cmdSetChannel);
writer.writeByte(channelIndex);
writer.writeCString(name, 32);
// Write PSK (16 bytes, zero-padded)
final pskPadded = Uint8List(16);
for (int i = 0; i < 16 && i < psk.length; i++) {
pskPadded[i] = psk[i];
}
writer.writeBytes(pskPadded);
return writer.toBytes();
}
// Build CMD_SET_RADIO_PARAMS frame
// Format: [cmd][freq x4][bw x4][sf][cr] (pre-v9)
// [cmd][freq x4][bw x4][sf][cr][repeat] (firmware v9+)
// freq: frequency in Hz (300000-2500000)
// bw: bandwidth in Hz (7000-500000)
// sf: spreading factor (5-12)
// cr: coding rate (5-8)
// clientRepeat: enable off-grid packet repeat (firmware v9+, omit for older)
Uint8List buildSetRadioParamsFrame(
int freqHz,
int bwHz,
int sf,
int cr, {
bool? clientRepeat,
}) {
final writer = BufferWriter();
writer.writeByte(cmdSetRadioParams);
writer.writeUInt32LE(freqHz);
writer.writeUInt32LE(bwHz);
writer.writeByte(sf);
writer.writeByte(cr);
if (clientRepeat != null) {
writer.writeByte(clientRepeat ? 1 : 0);
}
return writer.toBytes();
}
// Build CMD_SET_RADIO_TX_POWER frame
// Format: [cmd][power_dbm]
Uint8List buildSetRadioTxPowerFrame(int powerDbm) {
return Uint8List.fromList([cmdSetRadioTxPower, powerDbm]);
}
// Build CMD_RESET_PATH frame
// Format: [cmd][pub_key x32]
Uint8List buildResetPathFrame(Uint8List pubKey) {
final writer = BufferWriter();
writer.writeByte(cmdResetPath);
writer.writeBytes(pubKey);
return writer.toBytes();
}
// Build CMD_ADD_UPDATE_CONTACT frame to set custom path
// Format: [cmd][pub_key x32][type][flags][path_len][path x64][name x32][last_advert x4][Lat? x4, Lon? x4][lastmod? x4]
// The firmware stores last_advert as the contact's replay guard, so it must be
// the contact's own advert timestamp (0 when unknown), never the phone clock.
Uint8List buildUpdateContactPathFrame(
Uint8List pubKey,
Uint8List path,
int pathLen, {
int type = 1, // ADV_TYPE_CHAT
int flags = 0,
String name = '',
double? lat,
double? lon,
DateTime? lastAdvert,
DateTime? lastModified,
}) {
final writer = BufferWriter();
writer.writeByte(cmdAddUpdateContact);
writer.writeBytes(pubKey);
writer.writeByte(type);
writer.writeByte(flags);
writer.writeByte(pathLen);
writer.writeBytesPadded(path, maxPathSize);
// Name (32 bytes, null-padded)
writer.writeCString(name, maxNameSize);
final lastAdvertSeconds = lastAdvert == null
? 0
: lastAdvert.millisecondsSinceEpoch ~/ 1000;
writer.writeUInt32LE(lastAdvertSeconds.clamp(0, 0xFFFFFFFF).toInt());
// Optional [Lat x4, Lon x4][timestamp x4] tail per the doc comment above.
// Emit 8 bytes of position (zero-filled when only lastModified is provided)
// followed by an optional 4-byte timestamp. Earlier code emitted the
// position block twice, which corrupted the tail and caused the firmware
// to parse the second lat as the timestamp. See #427.
final hasLocation = lat != null && lon != null;
if (hasLocation || lastModified != null) {
writer.writeInt32LE(hasLocation ? (lat * 1e6).round() : 0);
writer.writeInt32LE(hasLocation ? (lon * 1e6).round() : 0);
if (lastModified != null) {
final lastModifiedTimestamp = lastModified.millisecondsSinceEpoch ~/ 1000;
writer.writeUInt32LE(lastModifiedTimestamp);
}
}
return writer.toBytes();
}
// Build CMD_GET_CONTACT_BY_KEY frame
// Format: [cmd][pub_key x32]
Uint8List buildGetContactByKeyFrame(Uint8List pubKey) {
final writer = BufferWriter();
writer.writeByte(cmdGetContactByKey);
writer.writeBytes(pubKey);
return writer.toBytes();
}
//Build CMD_GET_CUSTOM_VARS frame
Uint8List buildGetCustomVarsFrame() {
return Uint8List.fromList([cmdGetCustomVar]);
}
Uint8List buildGetAutoAddFlagsFrame() {
return Uint8List.fromList([cmdGetAutoAddConfig]);
}
Uint8List buildGetAllowedRepeatFreqFrame() {
return Uint8List.fromList([cmdGetAllowedRepeatFreq]);
}
typedef RepeatFreqRange = ({int lowKHz, int highKHz});
// RESP_ALLOWED_REPEAT_FREQ: [code] then [lower_khz u32][upper_khz u32] pairs.
List<RepeatFreqRange> parseAllowedRepeatFreqFrame(Uint8List frame) {
final ranges = <RepeatFreqRange>[];
final data = ByteData.sublistView(frame);
for (var i = 1; i + 8 <= frame.length; i += 8) {
ranges.add((
lowKHz: data.getUint32(i, Endian.little),
highKHz: data.getUint32(i + 4, Endian.little),
));
}
return ranges;
}
// Calculate LoRa airtime for a packet
// Based on Semtech SX127x datasheet formula
// Returns airtime in milliseconds
// Preamble defaults to the firmware's per-SF length (32 up to SF8, 16 above,
// RadioLibWrappers.h preambleLengthForSF); LDRO defaults to the RadioLib rule
// (symbol time > 16 ms).
int calculateLoRaAirtime({
required int payloadBytes,
required int spreadingFactor,
required int bandwidthHz,
required int codingRate,
int? preambleSymbols,
bool? lowDataRateOptimize,
bool explicitHeader = true,
}) {
// Symbol duration (Ts) in milliseconds
final symbolDuration = (1 << spreadingFactor) / (bandwidthHz / 1000.0);
// Preamble time
final preamble = preambleSymbols ?? (spreadingFactor <= 8 ? 32 : 16);
final preambleTime = (preamble + 4.25) * symbolDuration;
// Payload symbol count
final headerBytes = explicitHeader ? 0 : 20;
final crc = 1; // CRC enabled
final de = (lowDataRateOptimize ?? symbolDuration > 16.0) ? 1 : 0;
final numerator =
8 * payloadBytes - 4 * spreadingFactor + 28 + 16 * crc - headerBytes;
final denominator = 4 * (spreadingFactor - 2 * de);
var payloadSymbols =
8 + ((numerator / denominator).ceil()) * (codingRate + 4);
if (payloadSymbols < 0) {
payloadSymbols = 8;
}
final payloadTime = payloadSymbols * symbolDuration;
return (preambleTime + payloadTime).ceil();
}
// Calculate timeout for a message based on radio settings
// Returns timeout in milliseconds
int calculateMessageTimeout({
required int freqHz,
required int bwHz,
required int sf,
required int cr,
required int pathLength,
int messageBytes = 100, // Average message size
}) {
// Calculate airtime for one packet
final airtime = calculateLoRaAirtime(
payloadBytes: messageBytes,
spreadingFactor: sf,
bandwidthHz: bwHz,
codingRate: cr,
);
if (pathLength < 0) {
// Flood mode: Base delay + 16× airtime
return 500 + (16 * airtime);
} else {
// Direct path: Base delay + ((airtime×6 + 250ms)×(hops+1))
return 500 + ((airtime * 6 + 250) * (pathLength + 1));
}
}
// Build CLI command text message frame (companion_radio format)
// Format: [cmd][txt_type][attempt][timestamp x4][pub_key_prefix x6][text...]\0
Uint8List buildSendCliCommandFrame(
Uint8List repeaterPubKey,
String command, {
int attempt = 0,
int? timestampSeconds,
}) {
final timestamp =
timestampSeconds ?? (DateTime.now().millisecondsSinceEpoch ~/ 1000);
final writer = BufferWriter();
writer.writeByte(cmdSendTxtMsg);
writer.writeByte(txtTypeCliData);
writer.writeByte(attempt.clamp(0, 255));
writer.writeUInt32LE(timestamp);
writer.writeBytes(repeaterPubKey.sublist(0, 6));
writer.writeString(command);
writer.writeByte(0);
return writer.toBytes();
}
// Build a telemetry request frame
// Format: [cmd][pub_key x32][payload]
Uint8List buildSendBinaryReq(Uint8List repeaterPubKey, {Uint8List? payload}) {
final writer = BufferWriter();
writer.writeByte(cmdSendBinaryReq);
writer.writeBytes(repeaterPubKey);
if (payload != null && payload.isNotEmpty) {
writer.writeBytes(payload);
}
return writer.toBytes();
}
Uint8List buildSendControlDataFrame(Uint8List payload) {
final writer = BufferWriter();
writer.writeByte(cmdSendControlData);
writer.writeBytes(payload);
return writer.toBytes();
}
Uint8List buildDiscoveryRequestPayload(
int tag, {
bool prefixOnly = false,
int typeMask = 1 << advTypeRepeater,
}) {
final writer = BufferWriter();
// The high bit must be set for CMD_SEND_CONTROL_DATA; DISCOVER_REQ uses
// subtype 0x8, with the low bit selecting short/full public keys in replies.
writer.writeByte(
(controlSubtypeDiscoverReq << 4) | (prefixOnly ? 0x01 : 0x00),
);
writer.writeByte(typeMask);
writer.writeUInt32LE(tag);
writer.writeUInt32LE(0); // since=0 asks nearby nodes for any recent advert.
return writer.toBytes();
}
/// Node types a manual nearby-node scan asks for. Firmware repeaters and
/// sensors answer DISCOVER_REQ; room servers and companions currently don't,
/// but the room bit is harmless and lets future firmware reply.
const int nodeDiscoverScanTypeMask =
(1 << advTypeRepeater) | (1 << advTypeRoom) | (1 << advTypeSensor);
/// One DISCOVER_RESP, as pushed by the companion in PUSH_CODE_CONTROL_DATA:
/// `[0x8E][snr x4 int8][rssi int8][path_len][0x9<type>][snr x4 int8][tag u32 LE][pub_key 8|32]`.
class NodeDiscoverResponse {
NodeDiscoverResponse({
required this.nodeType,
required this.snr,
required this.rssi,
required this.remoteSnr,
required this.tag,
required this.publicKey,
});
final int nodeType;
/// SNR (dB) of the response as received by our radio.
final double snr;
final int rssi;
/// SNR (dB) of our request as heard by the responding node.
final double remoteSnr;
final int tag;
/// Full 32-byte key, or an 8-byte prefix when the request was prefix-only.
final Uint8List publicKey;
bool get hasFullKey => publicKey.length == pubKeySize;
String get publicKeyHex => pubKeyToHex(publicKey);
}
/// Parses a PUSH_CODE_CONTROL_DATA frame carrying a DISCOVER_RESP, or returns
/// null for any other or malformed frame.
NodeDiscoverResponse? parseNodeDiscoverResponse(Uint8List frame) {
// Push header (4) + type, snr, tag (6) + at least an 8-byte key prefix.
if (frame.length < 4 + 6 + 8 || frame[0] != pushCodeControlData) {
return null;
}
final reader = BufferReader(frame);
reader.skipBytes(1);
final snr = reader.readInt8() / 4.0;
final rssi = reader.readInt8();
reader.skipBytes(1); // path_len: responses are sent zero-hop.
final typeByte = reader.readByte();
if ((typeByte >> 4) != controlSubtypeDiscoverResp) return null;
final remoteSnr = reader.readInt8() / 4.0;
final tag = reader.readUInt32LE();
final keyBytes = reader.readRemainingBytes();
final keyLength = keyBytes.length >= pubKeySize ? pubKeySize : 8;
return NodeDiscoverResponse(
nodeType: typeByte & 0x0F,
snr: snr,
rssi: rssi,
remoteSnr: remoteSnr,
tag: tag,
publicKey: Uint8List.fromList(keyBytes.sublist(0, keyLength)),
);
}
Uint8List _reversePathByHop(Uint8List path, int pathHashWidth) {
if (path.isEmpty) return Uint8List(0);
final width = pathHashWidth.clamp(1, maxPathHashWidth).toInt();
if (path.length % width != 0) {
return Uint8List.fromList(path.reversed.toList());
}
final reversed = Uint8List(path.length);
final hops = path.length ~/ width;
for (var i = 0; i < hops; i++) {
final from = (hops - 1 - i) * width;
reversed.setRange(i * width, (i + 1) * width, path, from);
}
return reversed;
}
// Build CMD_SEND_ANON_REQ frame.
// Payload format for regions: [anon_req_type][reply_path_len][reply_path...].
Uint8List buildSendAnonReqFrame(
Uint8List repeaterPubKey, {
required int requestType,
Uint8List? replyPath,
int replyHopCount = 0,
int pathHashWidth = pathHashSize,
}) {
final width = pathHashWidth.clamp(1, maxPathHashWidth).toInt();
final path = replyPath ?? Uint8List(0);
final encodedPathLen = ((width - 1) << 6) | (replyHopCount & 0x3F);
final writer = BufferWriter();
writer.writeByte(cmdSendAnonReq);
writer.writeBytes(repeaterPubKey);
writer.writeByte(requestType);
writer.writeByte(encodedPathLen);
writer.writeBytes(_reversePathByHop(path, width));
return writer.toBytes();
}
//Build a trace request frame
//[cmd][tag x4][auth x4][flag][payload]
Uint8List buildTraceReq(int tag, int auth, int flag, {Uint8List? payload}) {
final writer = BufferWriter();
writer.writeByte(cmdSendTracePath);
writer.writeUInt32LE(tag);
writer.writeUInt32LE(auth);
writer.writeByte(flag);
if (payload != null && payload.isNotEmpty) {
writer.writeBytes(payload);
}
return writer.toBytes();
}
Uint8List buildExportPrivateKeyFrame() =>
Uint8List.fromList([cmdExportPrivateKey]);
Uint8List buildImportPrivateKeyFrame(Uint8List keyData) {
if (keyData.length != 64) {
throw ArgumentError.value(keyData.length, 'keyData.length', 'must be 64');
}
return Uint8List.fromList([cmdImportPrivateKey, ...keyData]);
}
// Build a export contact frame
// [cmd][pub_key x32 / if empty exports your contact info]
Uint8List buildExportContactFrame(Uint8List pubKey) {
final writer = BufferWriter();
writer.writeByte(cmdExportContact);
writer.writeBytes(pubKey);
return writer.toBytes();
}
// Build a import contact frame
// [cmd][contact_frame x98+]
Uint8List buildImportContactFrame(Uint8List contactFrame) {
final writer = BufferWriter();
writer.writeByte(cmdImportContact);
writer.writeBytes(contactFrame);
return writer.toBytes();
}
// Build a export contact frame
// [cmd][pub_key x32]
Uint8List buildZeroHopContact(Uint8List pubKey) {
final writer = BufferWriter();
writer.writeByte(cmdShareContact);
writer.writeBytes(pubKey);
return writer.toBytes();
}
// Build CMD_SET_OTHER_PARAMS frame
// Format: [cmd][allowTelemetryFlags][advertLocationPolicy][multiAcks]
Uint8List buildSetOtherParamsFrame(
int allowTelemetryFlags,
int advertLocationPolicy,
int multiAcks,
) {
final writer = BufferWriter();
writer.writeByte(cmdSetOtherParams);
//Going forward the app will just set Auto Add Contacts to disabled, and use the filter flags
//Allow Auto Add Contacts use inverted logic (0x01 = disabled, 0x00 = enabled).
writer.writeByte(0x01);
writer.writeByte(allowTelemetryFlags); // Allow Telemetry Flags
writer.writeByte(advertLocationPolicy); // Advertisement Location Policy
writer.writeByte(multiAcks); // Multi Acknowledgements
return writer.toBytes();
}
// Build CMD_SET_AUTO_ADD_CONFIG frame
// Format: [cmd][flags]
Uint8List buildSetAutoAddConfigFrame({
required bool autoAddChat,
required bool autoAddRepeater,
required bool autoAddRoomServer,
required bool autoAddSensor,
required bool overwriteOldest,
int? maxHops,
}) {
final writer = BufferWriter();
writer.writeByte(cmdSetAutoAddConfig);
int flags = 0;
if (autoAddChat) flags |= autoAddChatFlag;
if (autoAddRepeater) flags |= autoAddRepeaterFlag;
if (autoAddRoomServer) flags |= autoAddRoomServerFlag;
if (autoAddSensor) flags |= autoAddSensorFlag;
if (overwriteOldest) flags |= autoAddOverwriteOldestFlag;
writer.writeByte(flags);
// Optional autoadd_max_hops (firmware keeps its value when omitted).
if (maxHops != null) writer.writeByte(maxHops.clamp(0, 64).toInt());
return writer.toBytes();
}
//Build CMD_SEND_TELEMETRY_REQ
// Format: [cmd][reserved x3][pub_key? x32]
Uint8List buildSendTelemetryReq(Uint8List? pubKey) {
final writer = BufferWriter();
writer.writeByte(cmdSendTelemetryReq);
if (pubKey != null && pubKey.length == pubKeySize) {
writer.writeBytes(Uint8List(3)); // reserved bytes
writer.writeBytes(pubKey);
} else {
writer.writeBytes(Uint8List(3)); // reserved bytes
}
return writer.toBytes();
}
//Build CMD_SET_FLOOD_SCOPE
// Format: [cmd][scope]
Uint8List buildSetFloodScopeFrame(String region) {
if (region == '') {
// reset scope
return Uint8List.fromList([cmdSetFloodScope, 0]);
}
final scope = floodScopeKeyForRegion(region);
return Uint8List.fromList([cmdSetFloodScope, 0, ...scope]);
}
/// CMD_SET_FLOOD_SCOPE variant 1 (FIRMWARE_VER_CODE 12+): send floods with no
/// transport scope at all, overriding the radio's default flood scope.
Uint8List buildSetFloodScopeUnscopedFrame() {
return Uint8List.fromList([cmdSetFloodScope, 1]);
}
Uint8List buildGetDefaultFloodScopeFrame() {
return Uint8List.fromList([cmdGetDefaultFloodScope]);
}
/// CMD_SET_DEFAULT_FLOOD_SCOPE: `[63][name 31][key 16]` stores [region] as the
/// radio's default flood scope; an empty [region] clears it (`[63]`).
/// The name is stored without a leading '#'; the key uses the same derivation
/// as [buildSetFloodScopeFrame].
Uint8List buildSetDefaultFloodScopeFrame(String region) {
final name = region.startsWith('#') ? region.substring(1) : region;
if (name.isEmpty) return Uint8List.fromList([cmdSetDefaultFloodScope]);
final nameBytes = utf8.encode(name);
if (nameBytes.length >= defaultFloodScopeNameSize) {
throw ArgumentError.value(region, 'region', 'name longer than 30 bytes');
}
final frame = Uint8List(1 + defaultFloodScopeNameSize + floodScopeKeySize);
frame[0] = cmdSetDefaultFloodScope;
frame.setRange(1, 1 + nameBytes.length, nameBytes);
frame.setRange(
1 + defaultFloodScopeNameSize,
frame.length,
floodScopeKeyForRegion(name),
);
return frame;
}
/// Parses RESP_CODE_DEFAULT_FLOOD_SCOPE. Returns null when the radio has no
/// default scope (`[28]` alone) or the frame is malformed.
({String name, Uint8List key})? parseDefaultFloodScopeFrame(Uint8List frame) {
if (frame.isEmpty || frame[0] != respCodeDefaultFloodScope) return null;
if (frame.length < 1 + defaultFloodScopeNameSize + floodScopeKeySize) {
return null;
}
final nameField = frame.sublist(1, 1 + defaultFloodScopeNameSize);
final end = nameField.indexOf(0);
final name = utf8
.decode(
end >= 0 ? nameField.sublist(0, end) : nameField,
allowMalformed: true,
)
.trim();
if (name.isEmpty) return null;
final keyStart = 1 + defaultFloodScopeNameSize;
return (
name: name,
key: Uint8List.fromList(
frame.sublist(keyStart, keyStart + floodScopeKeySize),
),
);
}
Uint8List floodScopeKeyForRegion(String region) {
final name = region.startsWith('#') ? region : '#$region';
final hash = crypto.sha256.convert(utf8.encode(name)).bytes;
return Uint8List.fromList(hash.sublist(0, 16));
}
Uint8List floodTransportCode({
required Uint8List scopeKey,
required int payloadType,
required Uint8List payload,
}) {
final input = Uint8List(1 + payload.length)
..[0] = payloadType
..setRange(1, 1 + payload.length, payload);
final code = crypto.Hmac(crypto.sha256, scopeKey).convert(input).bytes;
if (code[0] == 0 && code[1] == 0) return Uint8List.fromList([1, 0]);
if (code[0] == 0xFF && code[1] == 0xFF) {
return Uint8List.fromList([0xFE, 0xFF]);
}
return Uint8List.fromList(code.sublist(0, 2));
}