Introduction
Welcome to the Bluetooth Low Energy (BLE) API documentation for the Camera Slider firmware. This documentation provides everything you need to communicate with and control the Camera Slider device from external applications, mobile apps, or web interfaces.
The Camera Slider is a motorized camera slider that can be controlled remotely via BLE, allowing for precise positioning and movement control for photography and videography applications.
Quick Start
1. Connect to Device
- Scan for BLE device named "Camera Slider"
- Connect using the UART service UUID:
6E400001-B5A3-F393-E0A9-E50E24DCCA9E
- Use TX characteristic:
6E400002-B5A3-F393-E0A9-E50E24DCCA9E
- Use RX characteristic:
6E400003-B5A3-F393-E0A9-E50E24DCCA9E
2. Send Commands
await client.write_gatt_char(tx_char, b'a')
await client.write_gatt_char(tx_char, b'b')
3. Monitor Responses
Subscribe to RX characteristic notifications to receive device feedback and status updates.
API Overview
The BLE API provides several key areas of functionality:
BLE Services
- UART Service: Primary communication channel for commands and responses
- Device Information: Manufacturer and model details
- Battery Service: Power level monitoring
- OTA DFU: Over-the-air firmware updates
Commands
- Movement Control: Forward/backward movement with configurable distance
- Status Queries: Device state, position, and configuration information
- Configuration: Speed, acceleration, and movement parameters
- System Control: Emergency stop, reset, and diagnostic functions
Responses
- Command Acknowledgments: Confirmation of received commands
- Status Updates: Real-time device state information
- Error Messages: Detailed error reporting and troubleshooting
- Data Logging: Movement history and performance metrics
Platform Support
The API is designed to work across multiple platforms:
| Platform | Library | Example File |
| Python | bleak | python_simple.py |
| Web Browser | Web Bluetooth API | javascript_web_ble.js |
| iOS | CoreBluetooth | ios_swift_example.swift |
| Android | BluetoothLeGatt | android_kotlin_example.kt |
| Node.js | noble | javascript_node_ble.js |
Getting Started
For Python Developers
pip install bleak
# See examples/python_simple.py for complete implementation
For Web Developers
<script>
// Use Web Bluetooth API (Chrome/Edge)
// See examples/javascript_web_ble.js for complete implementation
</script>
For Mobile Developers
- iOS: Use CoreBluetooth framework with Swift
- Android: Use BluetoothLeGatt with Kotlin/Java
- See respective example files for complete implementations
Current Features
✅ Implemented
- Basic forward/backward movement control
- LED status indication
- BLE UART communication
- Device discovery and connection
- Real-time command processing
🔄 In Development
- Position tracking and absolute positioning
- Speed and acceleration control
- Status reporting and monitoring
- Error handling and recovery
- Configuration management
📋 Planned
- Programmed movement sequences
- Multi-device coordination
- Advanced motion profiles
- Data logging and analytics
- Remote firmware updates
Architecture
┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐
│ Client App │ │ BLE Stack │ │ Camera Slider │
│ │◄──►│ │◄──►│ Firmware │
│ - Commands │ │ - UART Service │ │ - Motor Control│
│ - Responses │ │ - GATT Server │ │ - Position │
│ - Status │ │ - Advertising │ │ - Sensors │
└─────────────────┘ └─────────────────┘ └─────────────────┘
Command Reference
Movement Commands
| Command | Description | Parameters | Response |
a | Move forward | None | "a intercept - change dir" |
b | Move backward | None | "b intercept - change dir" |
pos:<value> | Move to position | Integer position | "Moving to position X" |
speed:<value> | Set speed | 1-100 | "Speed set to X" |
Control Commands
| Command | Description | Parameters | Response |
s | Get status | None | JSON status object |
x | Emergency stop | None | "STOP" |
r | Reset device | None | "RESET" |
h | Go home | None | "Going home" |
Configuration Commands
| Command | Description | Parameters | Response |
config:save | Save settings | None | "Settings saved" |
config:load | Load settings | None | "Settings loaded" |
config:reset | Reset to defaults | None | "Defaults restored" |
Response Formats
Status Response
{
"status": "idle|moving|error|stopped",
"position": 1234,
"target": 1234,
"speed": 50,
"battery": 85,
"temperature": 23.5,
"errors": []
}
Error Response
{
"error": "INVALID_COMMAND",
"message": "Command 'z' not recognized",
"code": 1001,
"timestamp": "2024-01-15T10:30:00Z"
}
Command Acknowledgment
{
"ack": "COMMAND_RECEIVED",
"command": "a",
"timestamp": "2024-01-15T10:30:00Z",
"execution_time": 15
}
Troubleshooting
Common Issues
Connection Problems
- Ensure device is advertising (LED blinking)
- Check device name: "Camera Slider"
- Verify BLE is enabled on your device
- Try restarting the Camera Slider
Command Not Working
- Verify connection is established
- Check command format (single character or string)
- Monitor serial output for error messages
- Ensure device is not in error state
Performance Issues
- Reduce command frequency if experiencing lag
- Check battery level
- Verify firmware version
- Monitor memory usage
Error Codes
| Code | Description | Solution |
| 1001 | Invalid command | Check command syntax |
| 1002 | Device busy | Wait for current operation |
| 1003 | Out of range | Check parameter values |
| 1004 | Hardware error | Restart device |
| 1005 | Low battery | Charge device |
Development
Adding New Commands
- Define command constant in
ble_api.h
- Add command processing in
bleuart.ino
- Update documentation in this file
- Add examples to
ble_examples.h
- Test with various platforms
Testing
- Use the provided testing examples
- Test on multiple platforms
- Verify error handling
- Check performance under load
- Validate response formats
Examples
Basic Movement Control
import asyncio
from bleak import BleakClient
async def basic_control():
async with BleakClient("XX:XX:XX:XX:XX:XX") as client:
await client.write_gatt_char(tx_char, b'a')
await asyncio.sleep(2)
await client.write_gatt_char(tx_char, b'b')
await asyncio.sleep(2)
await client.write_gatt_char(tx_char, b's')
asyncio.run(basic_control())
Web Interface
<!DOCTYPE html>
<html>
<head>
<title>Camera Slider Control</title>
</head>
<body>
<button onclick="moveForward()">Forward</button>
<button onclick="moveBackward()">Backward</button>
<button onclick="getStatus()">Status</button>
<script src="camera_slider.js"></script>
</body>
</html>
Mobile App Integration
- iOS: Use CoreBluetooth framework
- Android: Use BluetoothLeGatt
- See platform-specific examples for complete implementations
Additional Resources
Documentation Files
External Resources
Support
- Check the troubleshooting section above
- Review error codes and messages
- Test with provided examples
- Verify firmware version compatibility
Changelog
Version 1.0 (Current)
- Initial BLE API implementation
- Basic movement control (forward/backward)
- UART service communication
- Device discovery and connection
- LED status indication
Version 1.1 (Planned)
- Position tracking and absolute positioning
- Speed and acceleration control
- Status reporting and monitoring
- Enhanced error handling
Version 1.2 (Planned)
- Programmed movement sequences
- Configuration management
- Data logging capabilities
- Multi-device support
License
This firmware and API documentation are provided under the MIT License. See the LICENSE file for complete terms and conditions.
Contact
For questions, bug reports, or feature requests:
This documentation is automatically generated and maintained using Doxygen. For the most up-to-date information, always refer to the generated HTML documentation.
