node-red-contrib-meshtastic-advanced 1.0.0

Advanced Node-RED nodes for Meshtastic message encoding, decoding, encryption (PSK/PKC), and decryption

npm install node-red-contrib-meshtastic-advanced

node-red-contrib-meshtastic-advanced

Advanced Node-RED nodes for Meshtastic message encoding, decoding, encryption, and decryption.

Features

• ✅ Full Encryption Support: Both channel (PSK) and direct message (PKC) encryption
• ✅ All Message Types: Supports all Meshtastic message types (TEXT, POSITION, TELEMETRY, etc.)
• ✅ Modern Architecture: TypeScript-based with proper error handling
• ✅ Secure Key Storage: Uses Node-RED credentials API for encrypted key storage
• ✅ Flexible Design: Modular nodes that can be chained for custom workflows

Installation

npm install node-red-contrib-meshtastic-advanced

Or install directly in Node-RED:

1. Go to Menu → Manage palette
2. Select the Install tab
3. Search for node-red-contrib-meshtastic-advanced
4. Click Install

Nodes

🔓 meshtastic-decrypt

Decrypts encrypted Meshtastic packets using either:

• Channel encryption (PSK): AES-128/256-CTR with pre-shared key
• Direct message encryption (PKC): x25519 + AES-256-CCM

Configuration:

• Mode: Auto-detect, Channel (PSK), or Direct Message (PKC)
• Channel Key: Pre-shared key for channel decryption (16 or 32 bytes)
• Private Key: Your x25519 private key for DM decryption
• Public Keys: JSON mapping of sender node numbers to public keys

Input: Binary ServiceEnvelope with encrypted packet

Output: ServiceEnvelope with decrypted payload

📖 meshtastic-decode

Decodes Meshtastic protobuf payloads to readable JSON.

Configuration:

• Output Format: Flat (all fields at top level) or Nested (organized structure)
• Include Raw: Optionally include raw protobuf bytes

Input: ServiceEnvelope (binary or object) with decoded payload

Output: JSON object with decoded message content

Supported Message Types:

• TEXT_MESSAGE_APP
• POSITION_APP
• NODEINFO_APP
• TELEMETRY_APP
• ROUTING_APP
• ADMIN_APP
• WAYPOINT_APP
• NEIGHBORINFO_APP
• TRACEROUTE_APP
• And more...

✏️ meshtastic-encode

Encodes JSON messages to Meshtastic protobuf format.

Configuration:

• Default To: Destination node (default: broadcast 0xFFFFFFFF)
• Default Channel: Channel index 0-7 (default: 0)
• Default Hop Limit: Max hops 0-7 (default: 3)
• Output Type: ServiceEnvelope (full packet) or Data only
• Output Format: Object or Buffer

Input Example:

{
  "portNum": "TEXT_MESSAGE_APP",
  "message": "Hello, mesh!",
  "to": 123456,
  "channel": 0,
  "wantAck": false
}

🔒 meshtastic-encrypt

Encrypts Meshtastic payloads using channel PSK or direct message PKC.

Configuration:

• Mode: Channel (PSK) or Direct Message (PKC)
• From Node: Source node number
• Channel Key: Pre-shared key for channel encryption
• My Private Key: Your x25519 private key for DM encryption
• Recipient Public Key: Recipient's x25519 public key

Input: Data protobuf or ServiceEnvelope

Output: Encrypted ServiceEnvelope

Example Flows

Receive and Decode Encrypted Messages

[MQTT In] → [meshtastic-decrypt] → [meshtastic-decode] → [Debug]

1. Subscribe to MQTT topic for incoming Meshtastic messages
2. Decrypt using channel key
3. Decode to readable JSON
4. Display in debug panel

Send Encrypted Text Messages

[Inject] → [meshtastic-encode] → [meshtastic-encrypt] → [MQTT Out]

1. Create message payload
2. Encode to protobuf
3. Encrypt with channel key
4. Publish to MQTT

Multi-Channel Monitoring

[MQTT In] → [Switch] → [meshtastic-decrypt (ch 0)]
                     → [meshtastic-decrypt (ch 1)]
                     → [meshtastic-decrypt (ch 2)]

Monitor multiple channels with different encryption keys.

Security Considerations

Default Key Warning

⚠️ The default Meshtastic channel key is AQ== (base64) which is INSECURE.

Always configure a secure channel key. The nodes will warn you if you use the default key.

Key Storage

All encryption keys are stored using Node-RED's credentials system, which encrypts them at rest. Keys are never exported in flow JSON files.

Supported Key Formats

• Base64: Standard base64 encoding (e.g., AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA=)
• Hex: Hexadecimal encoding (e.g., 0000000000000000000000000000000000000000000000000000000000000000)

Key Lengths

• Channel PSK: 16 bytes (AES-128) or 32 bytes (AES-256)
• x25519 Keys: 32 bytes

Encryption Details

Channel Encryption (PSK + AES-CTR)

Meshtastic uses AES-CTR for channel encryption with a nonce constructed from:

• Node number (from field): 32 bits
• Packet ID: 32 bits
• Counter: Increments per 16-byte block

Direct Message Encryption (PKC + AES-CCM)

For v2.5+ direct messages:

1. Each node has an x25519 key pair
2. Shared secret derived using ECDH
3. Messages encrypted with AES-256-CCM (provides authentication)
4. Random nonce per message

Development

Build

npm install
npm run build

Run Tests

npm test

Local Development

# Link to local Node-RED
cd ~/.node-red
npm link /path/to/node-red-contrib-meshtastic-advanced

# Watch mode
npm run dev

Troubleshooting

"Packet is still encrypted" error

Make sure you use the meshtastic-decrypt node before the decode node. The decode node only works with already-decrypted packets.

"Channel decryption requires a channelKey" error

Configure the channel key in the decrypt node settings. Make sure it matches the key used by your Meshtastic devices.

"No public key found for sender" error

For DM decryption, you need to configure the sender's public key in the decrypt node's "Public Keys" field.

"Invalid key length" error

Check that your keys are the correct length:

• Channel keys: 16 bytes (AES-128) or 32 bytes (AES-256)
• x25519 keys: 32 bytes

Migration from Old Plugin

The old @meshtastic/node-red-contrib-meshtastic plugin had limited functionality:

• Only had a decode node (no decrypt, encode, or encrypt)
• Decrypt node was non-functional
• No PKC/DM support

This new plugin is a complete rewrite with full functionality.

Migration Steps

1. Uninstall old plugin: npm uninstall @meshtastic/node-red-contrib-meshtastic
2. Install new plugin: npm install node-red-contrib-meshtastic-advanced
3. Update flows to use new node names (meshtastic-decrypt, meshtastic-decode, etc.)
4. Configure encryption keys in decrypt/encrypt nodes

References

• Meshtastic Official Site
• Meshtastic Encryption Docs
• Meshtastic Protobufs
• Node-RED Documentation

License

MIT

Contributing

Contributions are welcome! Please open an issue or pull request on GitHub.

Acknowledgments

• Meshtastic Project for the amazing mesh networking platform
• @noble/curves for x25519 implementation
• Node-RED community for the excellent flow-based programming tool