api reference - MrTibbz2/CaveBot GitHub Wiki
Commands sent to Pico are simple string commands:
-
CMD_STATUS
- Request system status (blocking Core0 operation) -
CMD_STOP
- Terminate currently running Core1 thread
-
CMD_START_<COMMAND_NAME>
- Start specific task on Core1-
CMD_START_SENSORREAD
- Begin continuous sensor reading
-
All Pico responses follow structured JSON format:
<IDENTIFIER>: { "type": "<MESSAGE_TYPE>", "status": "<STATUS_CODE>", "payload": {<DATA>} }
-
Core1
- Messages from Core1 thread -
Command
- Command execution results -
INFO
- System information -
ERROR
- Error messages
-
data_stream
- Sensor data transmission -
thread_status
- Core1 thread lifecycle events -
system_status
- System health information -
command_response
- Command execution results
-
active
- Thread/system is running -
success
- Command completed successfully -
failure
- Command failed -
ready
- System ready for commands -
thread_started
- Core1 thread initiated -
thread_stopped
- Core1 thread terminated -
thread_locked
- Core1 busy, cannot start new thread
Core1: {
"type": "data_stream",
"status": "active",
"payload": [
{"sensor_id": "front_left", "average": 150.2},
{"sensor_id": "rear_right", "average": 199.7}
]
}
INFO: {
"type": "system_status",
"status": "ready",
"details": {"firmware_version": "1.0.1"}
}
ERROR: {
"type": "core1_management",
"code": "THREAD_LOCKED",
"message": "Core1 busy, cannot start new thread."
}
{
"type": "<MESSAGE_TYPE>",
"subtype": "<SUBTYPE>",
"timestamp": "2025-01-01T12:00:00Z",
"payload": { /* message data */ }
}
{
"type": "data_stream",
"subtype": "distance_read",
"timestamp": "2025-01-01T12:00:00Z",
"payload": {
"sensor_leftfront": 150.2,
"sensor_rightfront": 200.0,
"sensor_leftback": 180.5
}
}
{
"type": "log",
"subtype": "pico_info",
"timestamp": "2025-01-01T12:00:00Z",
"payload": {
"message": "System initialized successfully"
}
}
prime = Prime("HUB_NAME") # Connect to named hub
prime.moveForward(distance_cm) # Move forward specified distance
prime.moveBackward(distance_cm) # Move backward specified distance
prime.turnLeft(angle_degrees) # Turn left by angle
prime.turnRight(angle_degrees) # Turn right by angle
prime.stop() # Stop all motors
prime.partyTime() # Execute celebration sequence
prime.getStatus() # Get hub status
- Uses
bleak
library for Bluetooth LE communication - Automatic device discovery by hub name
- Command queuing for reliable transmission
- Connection retry logic with exponential backoff
interface = PicoSerialInterface(baudrate=115200)
result = interface.connect() # Auto-detect and connect to Pico
port = interface._find_pico_port() # Find Pico USB port
interface.disconnect() # Close serial connection
interface.send_command(command_str) # Send command to Pico
interface.format_ostream() # Parse incoming data (run in thread)
status = interface.poll_status() # Request system status
parsed = interface._parse_pico_message(raw_message)
# Returns: {"identifier": "INFO", "type": "system_status", "status": "ready"}
-
THREAD_LOCKED
- Core1 already running a task -
SENSOR_INIT_FAIL
- Sensor initialization failed -
CAL_TIMEOUT
- Sensor calibration timeout -
UNKNOWN_COMMAND
- Invalid command received
-
CONNECTION_FAILED
- Cannot connect to Pico -
PARSE_ERROR
- Invalid message format -
TIMEOUT
- Communication timeout -
PORT_NOT_FOUND
- Pico USB port not detected
-
BLE_CONNECTION_FAILED
- Bluetooth connection error -
HUB_NOT_FOUND
- Named hub not discoverable -
COMMAND_TIMEOUT
- Command execution timeout -
INVALID_PARAMETER
- Invalid command parameter
- Distance values: 0-400 cm (HC-SR04 range)
- Invalid readings: -1 (sensor error)
- Timestamp format: ISO 8601 UTC
- Sensor names: predefined set of 8 sensors
- Distance parameters: positive numbers only
- Angle parameters: 0-360 degrees
- String commands: predefined command set
- JSON format: strict schema validation