45_binary_request

Example 45: Binary Request

Send advanced binary protocol operations to query device status, test connectivity, and gather network information.

Purpose

This example demonstrates how to send binary requests for advanced mesh protocol operations. Binary requests are low-level protocol operations for querying device state, testing connectivity, and gathering network topology information.

Usage

go run ./examples/45_binary_request/ -port /dev/ttyUSB0

What This Does

The example:

1. Prompts for target device public key
2. Lets you choose a request type
3. Sends the binary request
4. Listens for EventBinaryResponse
5. Displays the response

Binary Request Types

0x01: Status Request

Query device information and status.

Request: No parameters needed Response includes:

• Device name
• Firmware version
• Uptime (seconds since boot)
• Battery level
• Capabilities flags

Use cases:

• Remote device diagnostics
• Firmware version audit
• Battery monitoring
• Check if device is responsive

0x02: Keep-alive Ping

Simple connectivity test.

Request: No parameters needed Response includes:

• Acknowledgment
• Timestamp

Use cases:

• Test if device is reachable
• Measure round-trip time
• Verify network path exists
• Monitor connection quality

0x03: Telemetry Request

Request current sensor readings.

Request: No parameters needed Response includes:

• Temperature
• Humidity
• Atmospheric pressure
• GPS coordinates
• Battery voltage
• Other sensors

Use cases:

• On-demand sensor polling
• Get fresh readings immediately
• Check if sensors are working
• Supplement periodic telemetry broadcasts

Note: This is equivalent to Example 39 (Request Telemetry).

0x05: ACL Request

Query access control list.

Request: No parameters needed Response includes:

• Number of authorized keys
• List of public keys
• Permission flags per key

Use cases:

• Audit device permissions
• Verify access control configuration
• Debug authorization issues
• Security compliance checks

0x06: Neighbors Request

List nearby mesh nodes.

Request: No parameters needed Response includes:

• Number of neighbors
• For each neighbor:
  • Public key
  • Signal strength (RSSI)
  • Last seen timestamp

Use cases:

• Network topology mapping
• Signal strength surveys
• Find nearby devices
• Troubleshoot connectivity
• Visualize mesh network

Interactive Example Session

╔══════════════════════════════════════════════════════╗
║  Binary Request - Advanced Protocol Operations     ║
╚══════════════════════════════════════════════════════╝

Connected as: Alice

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Send Binary Request
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Enter target device public key (32 hex bytes, or 'q' to quit):
a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2

Select request type:
  1. Status request (0x01)
  2. Keep-alive ping (0x02)
  3. Telemetry request (0x03)
  4. ACL request (0x05)
  5. Neighbors request (0x06)

Choice: 6

Sending binary request...
  Request type: Neighbors (0x06)
  Target: a1b2c3d4e5f6...

✓ Request sent successfully!
Waiting for response...

[14:32:15] Binary Response Received
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

  Request type: Neighbors (0x06)

  ✓ Response received successfully!

  EXPECTED NEIGHBORS RESPONSE:
     • Number of neighbors
     • For each neighbor:
       - Public key
       - Signal strength (RSSI)
       - Last seen timestamp

Use Case Examples

Network Topology Mapping

Query all known devices for their neighbors:

1. Get list of contacts (Example 10)
2. For each contact:
   - Send neighbors request (0x06)
   - Record response
3. Build graph of network connections
4. Visualize mesh topology

Device Health Monitoring

Periodically check device status:

1. Send status request (0x01) every hour
2. Record battery level
3. Alert if battery < 20%
4. Track uptime
5. Detect firmware version drift

Connectivity Testing

Test if devices can communicate:

1. Send keep-alive ping (0x02)
2. Measure response time
3. If timeout, device unreachable
4. If response, calculate latency
5. Monitor connectivity over time

Sensor Network Polling

Collect data from sensor nodes:

1. Send telemetry request (0x03) to each sensor
2. Wait for responses
3. Store sensor readings
4. Repeat every 5 minutes
5. Build time-series database

Response Handling

Successful Response

1. Request sent successfully
2. Wait for EventBinaryResponse
3. Response arrives within timeout
4. Parse response payload
5. Display or process data

Timeout (No Response)

1. Request sent successfully
2. Wait for EventBinaryResponse
3. Timeout after 20 seconds
4. Device may be offline/out of range
5. Retry or mark as unreachable

Error Response

1. Request sent successfully
2. Response contains error
3. Device doesn't support request type
4. Or insufficient permissions
5. Handle gracefully

Best Practices

Don't Spam Requests

• Limit request frequency
• Respect device power budget
• Avoid flooding the network
• Use appropriate polling intervals

Good:

Send status request every 1 hour
Send telemetry request every 5 minutes
Send ping only when testing connectivity

Bad:

Send status request every 5 seconds
Continuous telemetry polling
Ping spam

Handle Timeouts Gracefully

• Not all devices will respond
• Network conditions vary
• Allow adequate timeout (20+ seconds)
• Don't assume failure immediately

Batch Operations

If querying multiple devices:

1. Send all requests first
2. Then collect all responses
3. Don't block on each device
4. Use goroutines for parallel operation

Respect Device Capabilities

• Not all devices support all request types
• Sensor nodes may not have ACLs
• Simple devices may not track neighbors
• Check device type before requesting

Protocol Details

Request Structure

Request consists of:
- Target public key (32 bytes)
- Request code (1 byte): 0x01, 0x02, 0x03, 0x05, or 0x06
- Parameters (variable, usually empty)

Response Structure

Response event (EventBinaryResponse, 0x8C):
- Sender public key
- Request code (echo)
- Response payload (format depends on request type)
- Timestamp

Network Path

Your device → Mesh network → Target device
                ↓
Target device → Mesh network → Your device (response)

Response time depends on:

• Number of hops
• Network congestion
• Device processing time
• Radio conditions

Comparison: Binary Request vs Other Examples

Operation	Binary Request	Alternative Example
Telemetry	Request 0x03	Example 39 (SendTelemetryRequest)
Status	Request 0x01	Example 38 (SendStatusRequest)
Ping	Request 0x02	No direct equivalent
ACL	Request 0x05	No direct equivalent
Neighbors	Request 0x06	No direct equivalent

Note: SendBinaryRequest is the low-level API. Other examples provide higher-level wrappers.

Security Considerations

ACL Requests

• May reveal authorized users
• Consider privacy implications
• Only query ACLs you own
• Don't broadcast ACL data

Status Requests

• May reveal firmware version
• Could help attackers find vulnerabilities
• Consider rate limiting
• Monitor for reconnaissance attempts

Neighbors Requests

• Reveals network topology
• Shows device relationships
• Privacy consideration for users
• Could aid network mapping attacks

Troubleshooting

No response received

• Device is offline or out of range
• Network path doesn't exist
• Device doesn't support request type
• Request was lost in transmission
• Increase timeout and retry

Response parsing errors

• Response format depends on firmware
• Different firmware versions may differ
• Check firmware documentation
• Update API library if needed

Wrong response received

• Multiple devices responded
• Filter by sender public key
• Implement request/response correlation
• Use sequence numbers if available

Related Examples

• Example 38: Request Status - Dedicated status request
• Example 39: Request Telemetry - Dedicated telemetry request
• Example 28: Network Discovery - Discover nearby devices
• Example 47: Control Data - Network management packets

Advanced Usage

Building Network Map

// Pseudo-code for network mapping
contacts := api.GetContacts()
neighborsMap := make(map[PublicKey][]Neighbor)

for _, contact := range contacts {
    // Send neighbors request
    api.SendBinaryRequest(ctx, contact.PublicKey, 0x06, nil)

    // Wait for response
    response := waitForResponse(contact.PublicKey)

    // Store neighbors
    neighborsMap[contact.PublicKey] = parseNeighbors(response)
}

// Now you have complete network topology
visualizeGraph(neighborsMap)

Health Monitoring Dashboard

// Pseudo-code for monitoring
for {
    for _, device := range monitoredDevices {
        // Request status
        api.SendBinaryRequest(ctx, device.PublicKey, 0x01, nil)

        // Collect response
        status := waitForStatus(device.PublicKey)

        // Update dashboard
        updateDashboard(device, status)
    }

    time.Sleep(5 * time.Minute)
}

Technical Notes

Request Codes

The request codes (0x01, 0x02, etc.) are part of the MeshCore binary protocol specification. These are standardized across compatible devices.

Response Event

Responses arrive as EventBinaryResponse (0x8C). Subscribe to this event type to receive responses.

Firmware Compatibility

Response format may vary by firmware version. Always check firmware documentation for response structure details.