API Reference Specification

The Flask server served from the Raspberry Pi controller exposes the following REST API endpoints for hardware movements, NLP assistant controls, vision tracking, and Bluetooth speaker interfaces.

1. Locomotion & Servo Mechanics

POST/api/move/<action>

Sends walking direction gait requests to the locomotion board.

URL Actions: forward | backward | left | right | stop

Payload: { "speed": 10-100 }

Response Sample:

{ "success": true, "action": "forward", "speed": 100 }

POST/api/tilt/<direction>/<action>

Drives the pan/tilt camera gimbal servo motors.

URL Directions: up | down | left | right

URL Actions: start | stop

Response Sample:

{ "success": true, "direction": "up", "action": "start" }

POST/api/default/<action>

Triggers predefined physical posture gaits.

URL Actions: steady | jump | handshake

Response Sample:

{ "success": true, "action": "jump" }

2. NLP Command Assistant & RAG

POST/api/chatbot/command

Submits raw text queries for NLP command parsing or SLM generation.

Payload: { "command": "walk forward 5 steps" }

Response Sample (Command Intent):

{
  "success": true,
  "command": "walk forward 5 steps",
  "intent": "MOVE_FORWARD",
  "score": 0.965,
  "threshold_passed": true,
  "action_taken": "Moving forward for 5 steps."
}

POST/api/chatbot/audio

Uploads raw recorded WAV speech commands to the server.

Payload Format: multipart/form-data

Form Parameters: audio (WAV audio file binary, 16kHz mono PCM)

Response Sample: Matches the exact JSON structure of the text-based chatbot command response, containing speech transcript details.

3. Computer Vision & CNNs

POST/api/detect_digit

Classifies digits using LeNet-5. When explain is set, returns model weights/activations.

Payload: { "image": "base64_jpeg_or_png_string", "explain": true }

Response Sample:

{
  "success": true,
  "prediction": 5,
  "confidence": 98.4,
  "message": "CNN Digit Detection: I detected the digit '5'...",
  "explanation": {
    "weights": { "conv1": [[[[float]]]], "bias1": [float], ... },
    "activations": { "input": [[float]], "conv1": [[[float]]], ... }
  }
}

POST/api/color/follow/<color>

Toggles target object color tracking modes.

URL Colors: green | blue | red | none

Response Sample:

{ "success": true, "active_color": "green", "status": "activated" }

POST/api/face/detect/<action>

Toggles the facial detection bounding box overlay on the video stream.

URL Actions: start | stop

Response Sample:

{ "success": true, "status": "started" }

POST/api/face/follow/<action>

Starts/stops the camera following a registered person.

URL Actions: start | stop

Payload: { "name": "John" } (only required when starting)

Response Sample:

{ "success": true, "action": "start", "name": "John" }

GET/api/face/capture

Snaps a series of 6 camera frames to prepare facial registration embeddings.

Response Sample:

{
  "success": true,
  "has_face": true,
  "images": [ "base64_jpeg_1", "base64_jpeg_2", ... ]
}

POST/api/face/save

Saves and registers face frames under a target username.

Payload: { "name": "John", "images": [ "base64_img1", ... ] }

Response Sample:

{ "success": true, "message": "Successfully learned face for John" }

4. Bluetooth Management

GET/api/bluetooth/scan

Triggers Bluetooth discovery and returns local speakers list.

Response Sample:

{
  "success": true,
  "devices": [
    { "mac": "AA:BB:CC:DD:EE:FF", "name": "Sony SRS-XB13", "connected": false },
    { "mac": "00:11:22:33:44:55", "name": "JBL Flip 5", "connected": true }
  ]
}

POST/api/bluetooth/connect

Establishes pairing, trust, and connection bindings to a Bluetooth MAC.

Payload: { "mac": "AA:BB:CC:DD:EE:FF" }

Response Sample:

{ "success": true, "message": "Connected to AA:BB:CC:DD:EE:FF" }

POST/api/bluetooth/disconnect

Disconnects from a targeted Bluetooth speaker.

Payload: { "mac": "AA:BB:CC:DD:EE:FF" }

Response Sample:

{ "success": true, "message": "Disconnected from AA:BB:CC:DD:EE:FF" }

5. Telemetry & Status Monitoring

GET/api/status

Gathers real-time performance and system indicators from the RPi controller.

Response Sample:

{
  "success": true,
  "mode": "sta",
  "ip": "192.168.4.215",
  "cpu_temp": 46.2,
  "ram_info": 32.4,
  "cpu_use": 14.8
}