gps-msg-add - SKILL.md Agent Skill

name: gps-msg-add description: Add a group of related GPS configuration messages to a TOML message file allowed-tools: Read, Glob, Grep, Bash, Write, Edit, Task, Skill

GPS Message Add Skill

Add a group of related GPS configuration messages to a TOML message file.

Required Information

Extract the following from the user's request or conversation context:

Protocol documentation - PDF, markdown, or text file describing the receiver's command protocol
Target message file - TOML file path (e.g., configs/gpsmsg/receiver.toml)
What to add - Description of messages to add, ranging from general ("PPS configuration") to specific ("set PPS pulse width to 100us, rising edge, only when locked")
Serial device (optional) - For testing (e.g., /dev/ttyUSB0)
Baud rate (optional) - For testing (e.g., 115200)

If any required information is missing, ask the user before proceeding.

Workflow

Step 1: Extract Relevant Message Definitions

Spawn a subagent (Task tool with general-purpose agent) to:

Read the protocol documentation
Find messages related to the requested functionality
Extract the complete message specification including:
- Message format (NMEA, binary class/id, line command)
- Field definitions, types, and valid values
- Default values and examples
Return a compact summary of just the relevant message definitions

The subagent prompt should be specific about what functionality is needed. For example:

"Read the protocol documentation at [path] and extract all message definitions related to PPS configuration. For each message, provide: message name/ID, format type (NMEA/binary/line), all fields with their types and valid values, and any examples."

Step 2: Design Message Functionality

Based on the extracted definitions and the user's description, determine:

What specific messages to create
What each message should accomplish
What parameter values to use

If the user provided a detailed description (e.g., "100us pulse, rising edge"), use those values directly. If the user provided a general description (e.g., "PPS configuration"), design a useful set of messages:

Query current configuration (get-pps)
Enable with sensible defaults (pps)
Disable (pps-off)

Reference existing message files in configs/gpsmsg/ for patterns, especially allystar.toml which has comprehensive examples with verification comments.

Step 3: Choose Tag Names

Follow the tag naming conventions in configs/gpsmsg/tags.md.

Key rules:

Tags use lowercase with hyphens
Enable/disable pairs use -off suffix
Query commands use get- prefix
Parametric commands include the value: min-elev-15, speed-115200

Group related messages under the same tag when they should be sent together. For example, rtcm-msm7 enables MSM7 messages for all constellations (1077, 1087, 1097, 1127). Use rtcm-arp separately to enable 1005 ARP.

Step 4: Generate TOML Entries

Generate the message entries in the correct format. See configs/gpsmsg/gpsmsg-schema.json for the schema.

Message types:

[[line]] - Plain text commands (CR/LF terminated)
[[nmea]] - NMEA-style commands (auto-adds $ prefix and checksum)
[[binary]] - Raw hex bytes
[[ubx]] - u-blox UBX binary protocol
[[casbin]] - CASIC binary protocol (ZKW/Zhongkewei)
[[asbin]] - Allystar binary protocol

Each message can have:

text or hex - the message content
tag - grouping tag for -t selection
description - human-readable description (only needed on first message with each tag)
delay - seconds to wait after sending (useful for reload/reset commands)
For binary protocols: class, id, payload.types, payload.values

Add a comment above each logical group explaining what it does.

Step 5: Test the Messages (if device provided)

If serial device and speed were provided, use the gps-msg-test skill to test each new tag. Provide:

The target message file
The serial device
The baud rate
The receiver model (ask user if not already known)
The tag to test

The test skill will:

Send the command and check for ACK/OK
Query configuration if a corresponding get-* tag exists
Verify observable effects where possible
Add verification comments to the TOML file

Example: NMEA Message Control

For individual NMEA message control (e.g., RMC):

# NMEA RMC Message Control

# Verified ACK received on TAU1201
# Verified RMC messages (GNRMC/BDRMC) appear at 1Hz after enable on TAU1201
[[asbin]]
tag = "nmea-rmc"
description = "Enable NMEA RMC message at 1Hz"
class = 0x06
id = 0x01
payload.types = "U1U1U1"
payload.values = [0xF0, 0x05, 1]

# Verified ACK received on TAU1201
# Verified BDRMC messages stop after disable on TAU1201
[[asbin]]
tag = "nmea-rmc-off"
description = "Disable NMEA RMC message"
class = 0x06
id = 0x01
payload.types = "U1U1U1"
payload.values = [0xF0, 0x05, 0]

Example: Constellation Selection

Per-constellation tags with all bands enabled:

# GNSS Constellation Selection (CFG-NAVSAT 0x06 0x0C)

# GPS all bands (L1 + L1C + L5 + L2C)
# Verified ACK received on TAU1201
# Verified GSV shows only GPS satellites after gnss-gps on TAU1201
[[asbin]]
tag = "gnss-gps"
description = "Enable GPS all bands (L1/L1C/L5/L2C)"
class = 0x06
id = 0x0C
payload.types = "U4"
payload.values = [0x00000701]

# Galileo all bands (E1 + E5A + E5B + E6)
# Verified ACK received on TAU1201
# Verified GSV shows only Galileo satellites after gnss-gal on TAU1201
[[asbin]]
tag = "gnss-gal"
description = "Enable Galileo all bands (E1/E5A/E5B/E6)"
class = 0x06
id = 0x0C
payload.types = "U4"
payload.values = [0x00700010]

Example: Reset Commands

Distinct commands for different reset levels:

# Restart Commands (CFG-SIMPLERST 0x06 0x40)

# Hot start (fastest, keeps ephemeris)
[[asbin]]
tag = "hot-start"
description = "Hot start - keeps ephemeris data"
class = 0x06
id = 0x40
payload.types = "U1"
payload.values = [3]

# Warm start (clears ephemeris, keeps almanac)
[[asbin]]
tag = "warm-start"
description = "Warm start - clears ephemeris"
class = 0x06
id = 0x40
payload.types = "U1"
payload.values = [2]

# Cold start (clears all satellite data)
[[asbin]]
tag = "cold-start"
description = "Cold start - clears all satellite data"
class = 0x06
id = 0x40
payload.types = "U1"
payload.values = [1]

Example: Reset (reload + cold-start)

The reset tag combines reload from NVM with clearing satellite data:

# Reset: reload config from NVM + cold start (clears satellite data)
# Verified config restored from NVM and GSV shows no el/az after reset on TAU1201
# First load config from NVM
[[asbin]]
tag = "reset"
description = "Reset - reload config and clear satellite data"
class = 0x06
id = 0x09
payload.types = "U4U4"
payload.values = [1, 0x07]

# Then cold start (mode 1 clears satellite data; mode 0 does not)
[[asbin]]
tag = "reset"
class = 0x06
id = 0x40
payload.types = "U1"
payload.values = [1]

Example: Factory Reset

Factory reset clears NVM then resets:

# Factory reset
# Verified receiver restarts after factory-reset on TAU1201
# Verified GSV shows satellites without elevation/azimuth after factory-reset on TAU1201
# Verified RMC shows 'V' (void) status after factory-reset on TAU1201
[[asbin]]
tag = "factory-reset"
description = "Factory reset - clears all settings"
class = 0x06
id = 0x09
payload.types = "U4U4"
payload.values = [2, 0xFFFFFFFF]

# Then reset to apply
[[asbin]]
tag = "factory-reset"
class = 0x06
id = 0x40
payload.types = "U1"
payload.values = [0]

Example: Fixed Position

Use ECEF coordinates (example from allystar.toml):

# Fixed Position Mode (CFG-FIXEDECEF 0x06 0x14)

# Poll current fixed ECEF position
# Verified CFG-FIXEDECEF response received on TAU1201
[[asbin]]
tag = "get-fixed-pos"
description = "Query current fixed ECEF position"
class = 0x06
id = 0x14

# Set fixed ECEF position (coordinates in cm as S4)
# X=-1144698.0455m, Y=6090335.4099m, Z=1504171.3914m
# Verified ACK received on TAU1201
# Verified get-fixed-pos returns expected values on TAU1201
[[asbin]]
tag = "fixed-pos-example"
description = "Set fixed ECEF position (example coordinates - replace with yours)"
class = 0x06
id = 0x14
payload.types = "I4I4I4"
payload.values = [-114469805, 609033541, 150417139]

# Clear fixed position
# Verified ACK received on TAU951M-P200
# Verified get-fixed-pos returns zeros after fixed-pos-off on TAU951M-P200
[[asbin]]
tag = "fixed-pos-off"
description = "Clear fixed position"
class = 0x06
id = 0x14
payload.types = "I4I4I4"
payload.values = [0, 0, 0]

Example: RTCM Output

ARP (1005) is separate from MSM messages:

# Enable RTCM ARP (1005) message
# Verified ACK received on TAU951M-P200
[[asbin]]
tag = "rtcm-arp"
description = "Enable RTCM ARP message (1005)"
class = 0x06
id = 0x01
payload.types = "U1U1U1"
payload.values = [0xF8, 0x05, 1]

# Enable RTCM MSM7 messages for all constellations
# Rate 1 = output every position fix
# Verified ACK received for all 4 commands on TAU951M-P200
# Verified RTCM 1077, 1087, 1097, 1127 messages appear in capture after enable on TAU951M-P200
# 1077 GPS MSM7
[[asbin]]
tag = "rtcm-msm7"
description = "Enable RTCM MSM7 messages for all constellations"
class = 0x06
id = 0x01
payload.types = "U1U1U1"
payload.values = [0xF8, 0x4D, 1]

# 1087 GLONASS MSM7
[[asbin]]
tag = "rtcm-msm7"
class = 0x06
id = 0x01
payload.types = "U1U1U1"
payload.values = [0xF8, 0x57, 1]

# 1097 Galileo MSM7
[[asbin]]
tag = "rtcm-msm7"
class = 0x06
id = 0x01
payload.types = "U1U1U1"
payload.values = [0xF8, 0x61, 1]

# 1127 BeiDou MSM7
[[asbin]]
tag = "rtcm-msm7"
class = 0x06
id = 0x01
payload.types = "U1U1U1"
payload.values = [0xF8, 0x7F, 1]

Safety

Ask for explicit permission before testing commands that:

Change baud rate (can lose communication)
Save to NVM/flash (persistent changes)
Factory reset (loses all configuration)

Notes

Always read the target message file first to understand existing patterns
Match the style of existing entries (comment style, ordering, etc.)
Test one message at a time before adding complex sequences
For binary protocols, use a subagent to carefully calculate payload bytes
Reference configs/gpsmsg/allystar.toml for comprehensive examples with verification comments