palm-client: messaging protocol (send DM/channel, SENT, acks, channels, clock, advert)

Builders for SEND_TXT_MSG, SEND_CHANNEL_TXT_MSG (with MeshTerm's 150/130
byte limits), GET_CHANNEL, GET/SET_DEVICE_TIME and SEND_SELF_ADVERT; parsers
for CHANNEL_INFO, SENT (expected ack + timeout), PUSH_SEND_CONFIRMED and
CURR_TIME. All per MyMesh.cpp, checked byte for byte in host tests.
TxtPalmToUtf8 converts outgoing text from the Visor's Windows-1252 to UTF-8
and never cuts a character; it round-trips with TxtUtf8ToPalm.
This commit is contained in:
rich committed 2026-11-01 15:21:17 -05:00
1 parent 9f9032c2bb
commit 0189a23267
7 files changed
+283

No files matched your search

+110
View File
@@ -278,6 +278,76 @@ UInt16 VmBuildSetPathHashMode(UInt8 *out, UInt16 outSize, UInt8 mode)
return VmEncodeFrame(out, outSize, p, 3);
}
UInt16 VmBuildGetChannel(UInt8 *out, UInt16 outSize, UInt8 idx)
{
UInt8 p[2];
p[0] = VM_CMD_GET_CHANNEL;
p[1] = idx;
return VmEncodeFrame(out, outSize, p, 2);
}
/* CMD_SEND_TXT_MSG: code, txt_type, attempt, timestamp, recipient key prefix[6], text. */
UInt16 VmBuildSendTxt(UInt8 *out, UInt16 outSize, const UInt8 *prefix6, UInt32 timestamp, UInt8 attempt,
const UInt8 *text, UInt16 textLen)
{
UInt8 p[13 + VM_MAX_DM_TEXT];
if (textLen == 0 || textLen > VM_MAX_DM_TEXT)
return 0;
p[0] = VM_CMD_SEND_TXT_MSG;
p[1] = VM_TXT_TYPE_PLAIN;
p[2] = attempt;
PutLE32(p + 3, timestamp);
CopyBytes(p + 7, prefix6, 6);
CopyBytes(p + 13, text, textLen);
return VmEncodeFrame(out, outSize, p, (UInt16)(13 + textLen));
}
/* CMD_SEND_CHANNEL_TXT_MSG: code, txt_type, channel_idx, timestamp, text. The radio adds "Name: ". */
UInt16 VmBuildSendChannelTxt(UInt8 *out, UInt16 outSize, UInt8 channelIdx, UInt32 timestamp,
const UInt8 *text, UInt16 textLen)
{
UInt8 p[7 + VM_MAX_CHANNEL_TEXT];
if (textLen == 0 || textLen > VM_MAX_CHANNEL_TEXT)
return 0;
p[0] = VM_CMD_SEND_CHANNEL_TXT_MSG;
p[1] = VM_TXT_TYPE_PLAIN;
p[2] = channelIdx;
PutLE32(p + 3, timestamp);
CopyBytes(p + 7, text, textLen);
return VmEncodeFrame(out, outSize, p, (UInt16)(7 + textLen));
}
UInt16 VmBuildGetTime(UInt8 *out, UInt16 outSize)
{
UInt8 p[1];
p[0] = VM_CMD_GET_DEVICE_TIME;
return VmEncodeFrame(out, outSize, p, 1);
}
/* CMD_SET_DEVICE_TIME: the firmware only accepts a time at or after its own clock. */
UInt16 VmBuildSetTime(UInt8 *out, UInt16 outSize, UInt32 unixSeconds)
{
UInt8 p[5];
p[0] = VM_CMD_SET_DEVICE_TIME;
PutLE32(p + 1, unixSeconds);
return VmEncodeFrame(out, outSize, p, 5);
}
/* CMD_SEND_SELF_ADVERT: 1 = flood, 0 = zero hop (neighbours only). */
UInt16 VmBuildSendAdvert(UInt8 *out, UInt16 outSize, Boolean flood)
{
UInt8 p[2];
p[0] = VM_CMD_SEND_SELF_ADVERT;
p[1] = flood ? 1 : 0;
return VmEncodeFrame(out, outSize, p, 2);
}
/* CMD_REBOOT: code + "reboot" (the firmware checks the word, so a stray byte can't reboot it). */
UInt16 VmBuildReboot(UInt8 *out, UInt16 outSize)
{
@@ -415,3 +485,43 @@ Boolean VmParseMessage(const UInt8 *p, UInt16 len, VmMessage *out)
out->textLen = (UInt16)(len - i);
return 1;
}
/* CHANNEL_INFO: code, idx, name[32], secret[16]. */
Boolean VmParseChannelInfo(const UInt8 *p, UInt16 len, VmChannel *out)
{
if (len < 2 + VM_NAME_SIZE + VM_CHANNEL_SECRET_SIZE || p[0] != VM_RESP_CHANNEL_INFO)
return 0;
out->idx = p[1];
CopyName(out->name, sizeof(out->name), p + 2, VM_NAME_SIZE);
CopyBytes(out->secret, p + 2 + VM_NAME_SIZE, VM_CHANNEL_SECRET_SIZE);
return 1;
}
/* SENT: code, flood, expected_ack, est_timeout (ms). */
Boolean VmParseSent(const UInt8 *p, UInt16 len, VmSent *out)
{
if (len < 10 || p[0] != VM_RESP_SENT)
return 0;
out->flood = p[1] != 0;
out->expectedAck = GetLE32(p + 2);
out->timeoutMs = GetLE32(p + 6);
return 1;
}
/* PUSH_SEND_CONFIRMED: code, ack, round trip (ms). The same ack can arrive more than once. */
Boolean VmParseSendConfirmed(const UInt8 *p, UInt16 len, UInt32 *ack, UInt32 *tripMs)
{
if (len < 9 || p[0] != VM_PUSH_SEND_CONFIRMED)
return 0;
*ack = GetLE32(p + 1);
*tripMs = GetLE32(p + 5);
return 1;
}
Boolean VmParseCurrTime(const UInt8 *p, UInt16 len, UInt32 *unixSeconds)
{
if (len < 5 || p[0] != VM_RESP_CURR_TIME)
return 0;
*unixSeconds = GetLE32(p + 1);
return 1;
}
+37
View File
@@ -40,16 +40,23 @@ typedef char Char;
#define VM_PUB_KEY_SIZE 32
#define VM_NAME_SIZE 32 /* contact names: 31 chars + NUL */
#define VM_MAX_PATH_SIZE 64
#define VM_CHANNEL_SECRET_SIZE 16
/* Commands (app -> radio) */
#define VM_CMD_APP_START 1
#define VM_CMD_SEND_TXT_MSG 2
#define VM_CMD_SEND_CHANNEL_TXT_MSG 3
#define VM_CMD_GET_CONTACTS 4
#define VM_CMD_GET_DEVICE_TIME 5
#define VM_CMD_SET_DEVICE_TIME 6
#define VM_CMD_SEND_SELF_ADVERT 7
#define VM_CMD_SET_ADVERT_NAME 8
#define VM_CMD_SYNC_NEXT_MESSAGE 10
#define VM_CMD_SET_RADIO_PARAMS 11
#define VM_CMD_SET_RADIO_TX_POWER 12
#define VM_CMD_REBOOT 19
#define VM_CMD_DEVICE_QUERY 22
#define VM_CMD_GET_CHANNEL 31
#define VM_CMD_SET_PATH_HASH_MODE 61
/* Replies (radio -> app) */
@@ -59,10 +66,13 @@ typedef char Char;
#define VM_RESP_CONTACT 3
#define VM_RESP_END_OF_CONTACTS 4
#define VM_RESP_SELF_INFO 5
#define VM_RESP_SENT 6
#define VM_RESP_CURR_TIME 9
#define VM_RESP_NO_MORE_MESSAGES 10
#define VM_RESP_DEVICE_INFO 13
#define VM_RESP_CONTACT_MSG_V3 16
#define VM_RESP_CHANNEL_MSG_V3 17
#define VM_RESP_CHANNEL_INFO 18
/* Pushes (radio -> app, unsolicited) */
#define VM_PUSH_ADVERT 0x80
@@ -108,6 +118,18 @@ typedef struct {
UInt8 pathHashMode; /* path hash size in bytes = mode + 1 */
} VmDeviceInfo;
typedef struct {
UInt8 idx;
Char name[VM_NAME_SIZE + 1];
UInt8 secret[VM_CHANNEL_SECRET_SIZE];
} VmChannel;
typedef struct {
Boolean flood; /* sent as a flood (no known path) */
UInt32 expectedAck; /* matches a later PUSH_SEND_CONFIRMED; 0 = none expected */
UInt32 timeoutMs; /* the radio's estimate of how long the ack may take */
} VmSent;
/* Limits the firmware enforces (MyMesh.cpp); checked before sending. */
#define VM_FREQ_MIN_KHZ 150000UL
#define VM_FREQ_MAX_KHZ 2500000UL
@@ -119,6 +141,8 @@ typedef struct {
#define VM_CR_MAX 8
#define VM_TX_POWER_MIN (-9)
#define VM_NAME_MAX 31
#define VM_MAX_DM_TEXT 150 /* UTF-8 bytes, as MeshTerm limits them */
#define VM_MAX_CHANNEL_TEXT 130 /* channel text also carries "Name: " */
#define VM_PATH_HASH_MODE_MAX 2
typedef struct {
@@ -185,6 +209,15 @@ UInt16 VmBuildSetRadioParams(UInt8 *out, UInt16 outSize, UInt32 freqKHz, UInt32
Boolean includeRepeat, Boolean repeat);
UInt16 VmBuildSetTxPower(UInt8 *out, UInt16 outSize, Int8 dbm);
UInt16 VmBuildSetPathHashMode(UInt8 *out, UInt16 outSize, UInt8 mode);
UInt16 VmBuildGetChannel(UInt8 *out, UInt16 outSize, UInt8 idx);
/* Direct message: text is UTF-8 bytes, prefix the first 6 bytes of the recipient's key. */
UInt16 VmBuildSendTxt(UInt8 *out, UInt16 outSize, const UInt8 *prefix6, UInt32 timestamp, UInt8 attempt,
const UInt8 *text, UInt16 textLen);
UInt16 VmBuildSendChannelTxt(UInt8 *out, UInt16 outSize, UInt8 channelIdx, UInt32 timestamp,
const UInt8 *text, UInt16 textLen);
UInt16 VmBuildGetTime(UInt8 *out, UInt16 outSize);
UInt16 VmBuildSetTime(UInt8 *out, UInt16 outSize, UInt32 unixSeconds);
UInt16 VmBuildSendAdvert(UInt8 *out, UInt16 outSize, Boolean flood);
/* CMD_REBOOT: the radio restarts without replying. */
UInt16 VmBuildReboot(UInt8 *out, UInt16 outSize);
@@ -195,5 +228,9 @@ Boolean VmParseContactsStart(const UInt8 *p, UInt16 len, UInt32 *count);
Boolean VmParseContact(const UInt8 *p, UInt16 len, VmContact *out);
Boolean VmParseEndOfContacts(const UInt8 *p, UInt16 len, UInt32 *lastMod);
Boolean VmParseMessage(const UInt8 *p, UInt16 len, VmMessage *out);
Boolean VmParseChannelInfo(const UInt8 *p, UInt16 len, VmChannel *out);
Boolean VmParseSent(const UInt8 *p, UInt16 len, VmSent *out);
Boolean VmParseSendConfirmed(const UInt8 *p, UInt16 len, UInt32 *ack, UInt32 *tripMs);
Boolean VmParseCurrTime(const UInt8 *p, UInt16 len, UInt32 *unixSeconds);
#endif
+38
View File
@@ -173,3 +173,41 @@ UInt16 TxtUtf8ToPalm(const UInt8 *in, UInt16 inLen, Char *out, UInt16 outSize)
out[o] = 0;
return o;
}
/* Windows-1252 0x80-0x9F to Unicode (0 = unused slot). */
static const UInt16 kCp1252[32] = {
0x20AC, 0, 0x201A, 0x0192, 0x201E, 0x2026, 0x2020, 0x2021,
0x02C6, 0x2030, 0x0160, 0x2039, 0x0152, 0, 0x017D, 0,
0, 0x2018, 0x2019, 0x201C, 0x201D, 0x2022, 0x2013, 0x2014,
0x02DC, 0x2122, 0x0161, 0x203A, 0x0153, 0, 0x017E, 0x0178
};
UInt16 TxtPalmToUtf8(const Char *in, UInt16 inLen, UInt8 *out, UInt16 outSize)
{
UInt16 i, o = 0;
for (i = 0; i < inLen; i++) {
UInt8 c = (UInt8)in[i];
UInt16 cp = c;
if (c >= 0x80 && c < 0xA0)
cp = kCp1252[c - 0x80] ? kCp1252[c - 0x80] : '?';
if (cp < 0x80) {
if (o + 1 > outSize)
return 0;
out[o++] = (UInt8)cp;
} else if (cp < 0x800) {
if (o + 2 > outSize)
return 0;
out[o++] = (UInt8)(0xC0 | (cp >> 6));
out[o++] = (UInt8)(0x80 | (cp & 0x3F));
} else {
if (o + 3 > outSize)
return 0;
out[o++] = (UInt8)(0xE0 | (cp >> 12));
out[o++] = (UInt8)(0x80 | ((cp >> 6) & 0x3F));
out[o++] = (UInt8)(0x80 | (cp & 0x3F));
}
}
return o;
}
+6
View File
@@ -46,4 +46,10 @@ UInt16 TxtSplitSender(const Char *text, UInt16 len);
*/
UInt16 TxtUtf8ToPalm(const UInt8 *in, UInt16 inLen, Char *out, UInt16 outSize);
/*
* The Visor's text (Windows-1252) to UTF-8 for sending. Returns the byte count,
* or 0 if it won't fit in outSize (so a message is never cut mid-character).
*/
UInt16 TxtPalmToUtf8(const Char *in, UInt16 inLen, UInt8 *out, UInt16 outSize);
#endif
+25
View File
@@ -77,3 +77,28 @@ static const UInt8 kContactsEmpty[] = {
0x00, 0x00, 0x00, 0x00,
};
/* SYNTHETIC: CHANNEL_INFO per MyMesh.cpp CMD_GET_CHANNEL: slot 1, "#phillymesh", secret 0x11..0x20. */
static const UInt8 kChannelInfo[] = {
0x3e, 0x32, 0x00, 0x12, 0x01, 0x23, 0x70, 0x68, 0x69, 0x6c, 0x6c, 0x79,
0x6d, 0x65, 0x73, 0x68, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
0x00, 0x11, 0x12, 0x13, 0x14, 0x15, 0x16, 0x17, 0x18, 0x19, 0x1a, 0x1b,
0x1c, 0x1d, 0x1e, 0x1f, 0x20,
};
/* SYNTHETIC: SENT: flood, expected ack 0xdeadbeef, timeout 12000 ms. */
static const UInt8 kSent[] = {
0x3e, 0x0a, 0x00, 0x06, 0x01, 0xef, 0xbe, 0xad, 0xde, 0xe0, 0x2e, 0x00,
0x00,
};
/* SYNTHETIC: PUSH_SEND_CONFIRMED: ack 0xdeadbeef, round trip 850 ms. */
static const UInt8 kSendConfirmed[] = {
0x3e, 0x09, 0x00, 0x82, 0xef, 0xbe, 0xad, 0xde, 0x52, 0x03, 0x00, 0x00,
};
/* SYNTHETIC: CURR_TIME 1792432680. */
static const UInt8 kCurrTime[] = {
0x3e, 0x05, 0x00, 0x09, 0x28, 0x5a, 0xd6, 0x6a,
};
+50
View File
@@ -224,6 +224,55 @@ static void test_decimals(void)
CHECK(!VmParseInt("-", &i) && !VmParseInt("", &i) && !VmParseInt("2x", &i));
}
/* Messaging, laid out per the MyMesh.cpp handlers (CMD_SEND_TXT_MSG etc.). */
static void test_messaging(void)
{
UInt8 out[200];
static const UInt8 prefix[6] = { 0xa0, 0xa1, 0xa2, 0xa3, 0xa4, 0xa5 };
static const UInt8 dm[] = {
0x3c, 0x0f, 0x00, 0x02, 0x00, 0x01, 0x28, 0x5a, 0xd6, 0x6a,
0xa0, 0xa1, 0xa2, 0xa3, 0xa4, 0xa5, 'h', 'i'
};
static const UInt8 chan[] = { 0x3c, 0x09, 0x00, 0x03, 0x00, 0x01, 0x28, 0x5a, 0xd6, 0x6a, 'h', 'i' };
static const UInt8 setTime[] = { 0x3c, 0x05, 0x00, 0x06, 0x28, 0x5a, 0xd6, 0x6a };
static const UInt8 advert[] = { 0x3c, 0x02, 0x00, 0x07, 0x01 };
static const UInt8 getChan[] = { 0x3c, 0x02, 0x00, 0x1f, 0x02 };
UInt8 longText[VM_MAX_CHANNEL_TEXT + 1];
VmFrameDecoder d;
VmChannel ch;
VmSent sent;
UInt32 ack, trip, t;
/* timestamp 1792432680 = 0x6ad65a28 */
CHECK(VmBuildSendTxt(out, sizeof(out), prefix, 1792432680UL, 1, (const UInt8 *)"hi", 2) == sizeof(dm));
CHECK(memcmp(out, dm, sizeof(dm)) == 0);
CHECK(VmBuildSendChannelTxt(out, sizeof(out), 1, 1792432680UL, (const UInt8 *)"hi", 2) == sizeof(chan));
CHECK(memcmp(out, chan, sizeof(chan)) == 0);
memset(longText, 'x', sizeof(longText));
CHECK(VmBuildSendChannelTxt(out, sizeof(out), 0, 0, longText, VM_MAX_CHANNEL_TEXT) != 0);
CHECK(VmBuildSendChannelTxt(out, sizeof(out), 0, 0, longText, VM_MAX_CHANNEL_TEXT + 1) == 0);
CHECK(VmBuildSendTxt(out, sizeof(out), prefix, 0, 0, longText, 0) == 0);
CHECK(VmBuildSetTime(out, sizeof(out), 1792432680UL) == sizeof(setTime));
CHECK(memcmp(out, setTime, sizeof(setTime)) == 0);
CHECK(VmBuildSendAdvert(out, sizeof(out), 1) == sizeof(advert) && memcmp(out, advert, sizeof(advert)) == 0);
CHECK(VmBuildGetChannel(out, sizeof(out), 2) == sizeof(getChan) && memcmp(out, getChan, sizeof(getChan)) == 0);
decode_one(&d, kChannelInfo, sizeof(kChannelInfo));
CHECK(VmParseChannelInfo(d.payload, d.len, &ch));
CHECK(ch.idx == 1 && strcmp(ch.name, "#phillymesh") == 0 && ch.secret[0] == 0x11 && ch.secret[15] == 0x20);
CHECK(!VmParseChannelInfo(d.payload, 49, &ch));
decode_one(&d, kSent, sizeof(kSent));
CHECK(VmParseSent(d.payload, d.len, &sent));
CHECK(sent.flood && sent.expectedAck == 0xdeadbeefUL && sent.timeoutMs == 12000UL);
decode_one(&d, kSendConfirmed, sizeof(kSendConfirmed));
CHECK(VmParseSendConfirmed(d.payload, d.len, &ack, &trip) && ack == 0xdeadbeefUL && trip == 850UL);
decode_one(&d, kCurrTime, sizeof(kCurrTime));
CHECK(VmParseCurrTime(d.payload, d.len, &t) && t == 1792432680UL);
}
static void test_parse_self_info(void)
{
VmFrameDecoder d;
@@ -330,6 +379,7 @@ int main(void)
test_settings_builders();
test_decimals();
test_path_len();
test_messaging();
test_parse_self_info();
test_parse_contacts();
test_parse_messages();
+17
View File
@@ -107,6 +107,22 @@ static void test_utf8(void)
CHECK(TxtUtf8ToPalm((const UInt8 *)"abcdef", 6, out, 4) == 3 && strcmp(out, "abc") == 0);
}
static void test_to_utf8(void)
{
UInt8 out[16];
char back[16];
static const char cafe[] = { 'c', 'a', 'f', (char)0xE9 };
static const char quotes[] = { (char)0x93, 'h', 'i', (char)0x94, (char)0x85 };
CHECK(TxtPalmToUtf8(cafe, 4, out, sizeof(out)) == 5 && out[3] == 0xC3 && out[4] == 0xA9);
CHECK(TxtPalmToUtf8(quotes, 5, out, sizeof(out)) == 11);
CHECK(out[0] == 0xE2 && out[1] == 0x80 && out[2] == 0x9C); /* U+201C */
/* round trip back to the Visor's charset */
CHECK(TxtUtf8ToPalm(out, 11, back, sizeof(back)) == 5 && memcmp(back, quotes, 5) == 0);
/* doesn't fit: nothing rather than a cut character */
CHECK(TxtPalmToUtf8(cafe, 4, out, 4) == 0);
}
int main(void)
{
test_metrics();
@@ -114,6 +130,7 @@ int main(void)
test_age_and_snr();
test_sender_split();
test_utf8();
test_to_utf8();
if (failures) {
printf("%d failure(s)\n", failures);
return 1;