trail-mate/docs/team/team_chat_protocol.md

Team Chat protocol solution (Scheme C, v0.1)

This document describes the minimum implementable solution of the "Team Chat" protocol, which is used to carry structured messages: Text / Location / Command, and is bound to the Team security domain to support map and situation linkage.

---

1. Goal and Scope

• Goal: Make team chat a "parseable and executable" structured message flow.
• Override media type:
• Text: normal text.
• Location: Location sharing, can be rendered on Chat/GPS map.
• Command: command message, which can trigger team action prompts and map annotations.
• Security: only team members can decrypt, does not rely on the Meshtastic normal chat channel.

Prerequisites (v0.2 adjustments):

• Team creation/joining no longer via LoRa or NFC.
• Team formation only occurs in close-range scenarios within 5 meters, Use ESP‑NOW to complete team building and key distribution.
• LoRa is only used for daily communication within the team (Team Chat/Position/Track) and does not participate in the team formation process.

Non-target:

• Does not replace existing normal chat/broadcast messages.
• Does not implement complex reliable transmission (v0.1 does best-effort first).

---

2. Port and encryption

• New port:
• TEAM_CHAT_APP = 303 (defined in modules/core_team/include/team/protocol/team_portnum.h)
• Encryption method:
• Reuse TeamEncrypted envelope (team_wire.h).
• Derive team_chat key from team_psk.
• It is recommended to add:
  • deriveKey(psk, "team_chat", keys.chat_key)

This can achieve "team chat protocol layer isolation" and non-team members cannot decrypt it.

---

3. Payload structure (v0.1)

3.1 Universal header

Use concise TLV or fixed header + variable length payload. Recommended fixed header:

struct TeamChatHeader {
  uint8_t  version;    // =1
  uint8_t  type;       // 1=Text 2=Location 3=Command
 uint16_t flags; // Reserved
 uint32_t msg_id; // Locally generated, anti-replay/deduplication
 uint32_t ts; // Sending time (unix)
 uint32_t from; // Sender node_id
};

3.2 Text

struct TeamChatText {
  // UTF-8 text bytes
  bytes text;
};

3.3 Location

struct TeamChatLocation {
  int32_t lat_e7;
  int32_t lon_e7;
  int16_t alt_m;       // optional, 0=unknown
  uint16_t acc_m;      // optional, 0=unknown
  uint32_t ts;         // optional, 0=use header.ts
 uint8_t source; // Location semantic icon, see mapping below
  bytes    label;      // optional short label
};

source mapping (consistent with current firmware implementation):

• 0: None / Ordinary position (no semantic icon)
• 1:AreaCleared
• 2:BaseCamp
• 3:GoodFind
• 4:Rally
• 5:Sos

3.4 Command

v0.1 only does the minimum instruction set and does not do revocation/expiration semantics.

enum TeamCommandType : uint8_t {
 RallyTo = 1, // Rally to the target point
 MoveTo = 2, // Go to the target point
 Hold = 3 // Stay in place
};

struct TeamChatCommand {
  uint8_t  cmd_type;
 int32_t lat_e7; // Optional: used for Rally/Move
  int32_t  lon_e7;
 uint16_t radius_m; // Optional: collection radius
  uint8_t  priority;    // 0=normal 1=high
 bytes note; // Optional: short note
};

---

4. Sending and receiving process

4.1 Sending

• UI generates Text/Location/Command.
• Encoded as TeamChatHeader + payload.
• Via TeamService::sendTeamChat():
• Use keys.chat_key encryption encapsulation as TeamEncrypted.
• Sent via TEAM_CHAT_APP (mesh_.sendAppData(...)).

4.2 Receiving

• TeamService::processIncoming() Added TEAM_CHAT_APP branch:
• Decrypt TeamEncrypted.
• Parse TeamChatHeader.
• Trigger TeamChatEvent (new EventBus type).
• UI received TeamChatEvent:
• Appended to team_ui_chatlog (new type field).
• If it is Location/Command, update the map/GPS page annotation simultaneously.

---

5. Changes from existing code

Minimum change list (v0.1):

1. Protocol and port

• modules/core_team/include/team/protocol/team_portnum.h added TEAM_CHAT_APP = 303
• added team_chat.h/.cpp (encoding/decoding)

2. Key derivation

• TeamKeys added chat_key
• Derived from "team_chat" in TeamService::setKeysFromPsk()

3. TeamService

• Added sendTeamChat(...)
• processIncoming() handles TEAM_CHAT_APP

4. Event Bus

• sys/event_bus.h adds TeamChatEvent

5. UI/Storage

• team_ui_chatlog_append() is expanded to a structured message (type + payload)
• Contacts/Team chat page uses the TeamChat data source to render cards

---

6. Compatibility and Transition

• Keep existing normal chat:
• Primary/Secondary continue to use TEXT_MESSAGE_APP
• Team Chat as an independent channel:
• Does not affect normal chat history and notifications
• Team can be gradually replaced Page session source
• Location.source compatibility suggestions (PC/host computer):
• If an unknown source (not in 0..5) is received, render it as a normal Location, and the entire message must not be discarded
• Continue to use coordinate and time fields, and label can be used for display when it exists
• It is recommended to retain the original source Value for forward compatibility

---

7. v0.1 Fixed Matter

• ACK/Delivery: Not required (best effort).
• Command Revoke/Expire: Not supported.
• Map interaction: only a system notification pops up when a message is received; the pop-up window is triggered by selecting a map annotation in the Chat session and displays a cropped image of the tile map at that location.
• Team mode GPS: Render player positions from posring.log.

8. Version strategy

• TeamChatHeader.version = 1 -Subsequent extensions will be compatible through flags or new type

---

Appendix A: ESP‑NOW team building and joining (v0.2)

Goal: Reduce steps and unstable links, and quickly build a team at short distances (≤5m).

A1. Roles and constraints

• Scenario: Everyone in the same room/range ≤5m.
• Medium: ESP‑NOW (2.4GHz), LoRa/NFC is no longer used.
• Result: The member receives team_psk + team_id + key_id + epoch, and then uses LoRa to send and receive the Team protocol.

A2. Simplify the process

Leader

1. Create Team → Open the "Pairing (ESP‑NOW)" window (default 120s).
2. Receive member Join request (can be "Auto‑accept" or manually Accept).
3. Send KeyDist (ESP‑NOW) to the new member.

Member

1. Join Team → Nearby Teams (ESP‑NOW Scan) to select the target.
2. Send Join request and wait for KeyDist.
3. Enter the joined state after receiving the KeyDist.

A3. ESP‑NOW messages (recommended)

PAIR_BEACON { team_id_short, team_id, epoch, key_id, leader_id, expires_at }
PAIR_JOIN   { team_id, member_id, member_pub, nonce }
PAIR_ACCEPT { team_id, member_id, ok, nonce }
PAIR_KEY    { team_id, key_id, epoch, team_psk_encrypted, nonce }

Description:

• team_psk_encrypted can be encrypted with a temporary session key (derived from member_pub + leader private key).
• nonce is used to correlate requests and prevent replay.
• All ESP‑NOW packets are processed only within the Pairing window.

A4. Relationship with Team Chat

• ESP‑NOW is only responsible for "team building/enlisting/key distribution".
• Use LoRa's Team protocol (TEAM_CHAT / TEAM_POS / TEAM_TRACK / …) when done.