7. Team Features

Team Features

Language: English. Chinese version: 7. Team Features (中文)

Team is the main MCU carrier of Trail Mate's TAK core capability. It is not one more group channel; it organizes members, positions, maps, tracks, markers, assembly points, messages, and operational state into authorized shared awareness.

What Team Means In This Project

According to the current docs/TEAM.md, a Team can be summarized as:

a temporary, mission-driven outdoor action unit that can form and dissolve as needed

It tries to keep answering three questions:

• are we still together
• what do we do next
• is anyone in trouble

That is why the Team data model is not only text. It includes location, waypoints, tracks, status, and lifecycle-related events.

Team Is Not Just Group Chat

Ordinary chat is mainly about delivering text. Team is about preserving coordination visibility.

In Trail Mate, that difference appears in at least four ways:

• Team has its own create, join, rotate, and disband lifecycle
• Team has its own position, waypoint, and track paths
• Team has a stronger privacy model than an ordinary broadcast channel
• Team is meant to support later review, not only short-term conversation

Reducing Team to “sharing a channel” would miss the whole design.

Current Core Team Capabilities

Temporary team formation

The design already supports:

• creating a team
• joining a nearby team
• disbanding a team

The current concept is organized more like a lifecycle than like a static group:

Create → Active → Rotate → Disband

That reflects the idea that a field team is a temporary operational unit, not a permanent social group.

Position sharing

Team position sharing is not ordinary public position broadcast. The design explicitly assumes that once a Team position message is sent, only Team members should be able to interpret it meaningfully.

This is protected by two layers:

• channel-level link encryption
• application-level encryption derived from TeamKey

For field use, that difference matters because “someone is nearby” and “this specific teammate is here” are very different privacy levels.

Team waypoints and assembly points

Trail Mate already treats Team waypoints and assembly points as real project capabilities. They are project-specific Team extensions and should not be conflated with Meshtastic native WAYPOINT_APP interoperability.

The most important current boundary is simple:

• Team waypoint and assembly-point capability exists inside Trail Mate
• native Meshtastic waypoint interoperability is outside the current product promise; Team waypoints remain their own frozen semantic

Team tracks

Team does not only share the latest point. It also includes track sampling and track snapshots. For a field team, this is often more useful than a single position because it helps answer whether someone drifted off-route or regrouped.

Team chat and state synchronization

Team also includes text chat, but it sits inside a wider collaboration loop that includes member lists, roles, state, last position, and team-oriented views.

How Team Formation Works

The current design separates team formation from team runtime.

Nearby formation through ESP-NOW

When the team is first formed and members are still close together, Trail Mate uses ESP-NOW to handle pairing and TeamKey exchange. The purpose is to create the team relationship securely before long-range operation begins.

Runtime operation through LoRa

Once the team is formed, the ongoing traffic moves to LoRa. The reason is straightforward:

• nearby pairing benefits from fast local exchange
• longer-range runtime coordination benefits from LoRa’s lower-power wide-area link

Splitting these stages is more realistic than forcing one mechanism to do both jobs equally well.

Team Data Categories

The current design notes imply several broad kinds of Team data.

Lifecycle events

Examples include:

• create
• discovery or public visibility
• join request
• join acceptance
• state synchronization
• key rotation
• disband or leave

These let the system answer when the team started, who joined, and when it ended.

Position and track events

Examples include:

• member position reception
• waypoint and assembly-point reception
• batch track-point reception

These are about situational awareness, not ordinary chat.

Action-oriented events

The Team design also includes the idea of actionable instructions rather than relying only on free-form text, such as gather, wait, or help-related commands. This reflects a coordination device mindset rather than a purely messaging-device mindset.

Visibility and anomaly events

The design explicitly calls out status changes such as:

• temporarily not visible
• visible again
• low battery
• stationary too long

These are important because team problems often show up first as missing visibility rather than as explicit text from the affected member.

Team Ports And Protocol Boundary

Trail Mate currently tends to give Team its own application ports, such as:

• TEAM_POSITION_APP
• TEAM_WAYPOINT_APP
• TEAM_TRACK_APP
• TEAM_MGMT_APP

That tells you something important about the project’s intent. Team is not being treated as a loose repackaging of someone else’s native application semantics. It is being built as a first-class field-coordination extension.

Privacy Model

One of the core Team design decisions is that even if some channel-level configuration becomes known, non-members should not be able to easily interpret the team’s internal position and coordination content.

That is why the current design emphasizes:

• channel isolation
• TeamKey-derived application-layer encryption

For outdoor coordination, that is not a luxury feature. It is part of the baseline requirement.

Team And The Map

In Trail Mate, Team is not a chat-only concept. It is directly tied to the map:

• member positions should appear on the map
• waypoints and assembly points should appear on the map
• track snapshots should help explain movement
• contact and event state should help interpret the team picture

That is why Team belongs in the main wiki structure rather than under an “advanced chat” subsection.

Frozen Product Boundary

The current boundaries that can be stated with confidence include:

• Team is a temporary action unit, not a permanent group
• create, join, and disband are part of the workflow
• Team includes positions, waypoints, and tracks
• formation uses ESP-NOW, runtime uses LoRa
• Team uses a stronger privacy model than ordinary public chat
• the project is willing to use its own TEAM_*_APP ports

The MCU Team/TAK surface will not gain new major domains. If command vocabulary, health fields, or lifecycle-review details are not current user capabilities, they must not be advertised as roadmap features. Maintenance may correct existing behavior only while preserving anonymous-operation, authorization, and position-sharing boundaries.

Hardware Support Boundary

Not every target supports Team. The clearest example is GAT562 Mesh EVB Pro, which intentionally excludes Team as part of its product boundary. If the Team page or related features are absent on a device, check the target boundary first before assuming the adaptation failed.

The Most Important Conclusion

If only one sentence survives, it should be this:

Trail Mate’s Team feature is about managing small-team coordination state, not merely adding another chat channel.

Once that is understood, the project’s use of its own ports, lifecycle, map integration, and event handling starts to make much more sense.

Documentation That Can Be Split Further

This page can be split into explanations of existing behavior:

• Team pairing workflow
• Team ports and packet semantics
• Team UI and map interaction
• Team lifecycle and review model

These subpages explain the frozen Team/TAK capability; they do not imply major feature expansion.