Skip to content

Commit 2b7f5ae

Browse files
NuwanJNuwanJ
authored
Add initial documentation structure and requirements for the Robot Library (#22)
1 parent b59f8b7 commit 2b7f5ae

File tree

15 files changed

+608
-8
lines changed

15 files changed

+608
-8
lines changed

‎.github/workflows/docs-cd.yml‎

Lines changed: 57 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,57 @@
1+
name: 'Documentation: Publish'
2+
3+
on:
4+
push:
5+
branches: ['dev']
6+
workflow_dispatch:
7+
8+
permissions:
9+
contents: read
10+
pages: write
11+
id-token: write
12+
13+
concurrency:
14+
group: pages
15+
cancel-in-progress: false
16+
17+
jobs:
18+
build:
19+
runs-on: ubuntu-latest
20+
steps:
21+
- name: Checkout
22+
uses: actions/checkout@v4
23+
24+
- name: Set up Python
25+
uses: actions/setup-python@v5
26+
with:
27+
python-version: '3.x'
28+
29+
- name: Install dependencies
30+
run: |
31+
python -m pip install --upgrade pip
32+
pip install -e .
33+
pip install -r docs/requirements.txt
34+
35+
- name: Generate API stubs
36+
run: |
37+
sphinx-apidoc -o docs/api src/robot
38+
39+
- name: Build HTML
40+
run: |
41+
python -m sphinx -b html docs docs/_build/html
42+
43+
- name: Upload artifact
44+
uses: actions/upload-pages-artifact@v3
45+
with:
46+
path: docs/_build/html
47+
48+
deploy:
49+
needs: build
50+
runs-on: ubuntu-latest
51+
environment:
52+
name: github-pages
53+
url: ${{ steps.deployment.outputs.page_url }}
54+
steps:
55+
- name: Deploy to GitHub Pages
56+
id: deployment
57+
uses: actions/deploy-pages@v4

‎README.md‎

Lines changed: 105 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -1,18 +1,115 @@
1-
# Robot Library Python
1+
# Robot Library (Python)
22

3-
A modular Python library for building robot applications. It provides components
4-
for motion control, sensor access, communication, and indicators.
3+
A modular Python library for building robot applications. It provides components for motion control, sensors, communications, and indicators over MQTT.
4+
5+
Documentation: the full site is auto-built and deployed to GitHub Pages on pushes to the `dev` branch. Once enabled in the repo settings, it will be available at: `https://pera-swarm.github.io/robot-library-python/`.
56

67
## Installation
78

8-
```bash
9-
pip install -e .
9+
You can install in a few ways:
10+
11+
- Editable (development) install from a local checkout:
12+
13+
```bash
14+
pip install -e .
15+
```
16+
17+
- From source via Git (replace org/repo as appropriate):
18+
19+
This library requires `paho-mqtt` (declared in `pyproject.toml`) and Python 3.8+.
20+
21+
## Quick Start
22+
23+
Create a virtual robot by subclassing `robot.VirtualRobot`, configure MQTT, and start the main loop:
24+
25+
```python
26+
from robot import MQTTSettings, VirtualRobot
27+
from robot.interfaces import RobotState
28+
29+
30+
class MyRobot(VirtualRobot):
31+
def loop(self):
32+
if self.state == RobotState.RUN:
33+
print("running...")
34+
# do work
35+
self.delay(1000)
36+
37+
38+
# Configure MQTT broker connection
39+
MQTTSettings.server = "localhost"
40+
MQTTSettings.port = 1883
41+
MQTTSettings.user_name = ""
42+
MQTTSettings.password = ""
43+
MQTTSettings.channel = "v1"
44+
45+
r = MyRobot(1, 0, 0, 90)
46+
r.start()
47+
r.run() # or run in a separate thread
48+
```
49+
50+
See `examples/my_test_robot.py` for a complete runnable example.
51+
52+
## Core Concepts
53+
54+
- Robot: base lifecycle (`start/stop/reset/delay/loop`) and MQTT subscription handling. See `robot.Robot`.
55+
- VirtualRobot: convenient virtual implementation; subclass and implement `loop`. See `robot.VirtualRobot`.
56+
- Motion: differential drive style controller for movement and rotation. See `robot.MotionController`.
57+
- Sensors: distance, color, and proximity, with non-blocking MQTT updates and blocking request/reply helpers.
58+
- Communication: simple and directed messaging channels to other robots or a controller.
59+
- Indicators: NeoPixel control via MQTT topics.
60+
61+
## Usage Examples
62+
63+
Motion control:
64+
65+
```python
66+
from robot import MotionController
67+
68+
motion = MotionController() # standalone stub coordinate for quick tests
69+
motion.move(100, 100, duration=1000) # forward 1s
70+
motion.rotate_degree(120, 90) # rotate 90 degrees at speed 120
71+
```
72+
73+
Sensors (within a `Robot` subclass after `setup()` has run):
74+
75+
```python
76+
dist = self.dist_sensor.get_distance()
77+
rgb = self.color_sensor.get_color() # RGBColorType
78+
prox = self.proximity_sensor.get_proximity() # ProximityReadingType
79+
```
80+
81+
Communications:
82+
83+
```python
84+
self.simple_comm.send_message("hello swarm")
85+
self.directed_comm.send_message_with_distance("to leader", distance=25)
1086
```
1187

12-
## Usage
88+
Indicators:
1389

1490
```python
15-
from robot.motion import MotionController
91+
self.neo_pixel.change_color(255, 128, 0)
92+
```
93+
94+
## Extending and Customizing
95+
96+
- New behavior: subclass `VirtualRobot` and implement `loop`. Optionally override `sensor_interrupt` or `communication_interrupt`.
97+
- New sensors/indicators: follow the pattern in `robot.sensors.*` and `robot.indicators.*`, implementing `handle_subscription` and publishing/consuming your desired topics via `RobotMqttClient`.
98+
- Motion tuning: adjust `robot.configs.robot_settings.RobotSettings` constants (speed bounds, robot geometry) to match your platform.
99+
- MQTT setup: set fields on `robot.configs.mqtt_settings.MQTTSettings` before constructing robots.
16100

17-
controller = MotionController()
101+
## Documentation
102+
103+
Sphinx documentation lives in `docs/` and is auto-generated on pushes to `dev` via GitHub Actions, then deployed to GitHub Pages. To build locally:
104+
105+
```bash
106+
pip install -r docs/requirements.txt
107+
sphinx-apidoc -o docs/api src/robot
108+
python -m sphinx -b html docs docs/_build/html
109+
open docs/_build/html/index.html
18110
```
111+
112+
## Contributing
113+
114+
- Run lint and tests: `flake8 src tests` and `PYTHONPATH=src pytest`
115+
- Example to run: `python examples/my_test_robot.py`

‎docs/Makefile‎

Lines changed: 29 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,29 @@
1+
# Minimal Sphinx Makefile
2+
3+
SPHINXBUILD?=sphinx-build
4+
SOURCEDIR=.
5+
BUILDDIR=_build
6+
ROOTDIR=..
7+
PY?=python
8+
PORT?= 9000
9+
10+
.PHONY: help clean html apidoc
11+
12+
help:
13+
@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)"
14+
15+
clean:
16+
rm -rf "$(BUILDDIR)"
17+
18+
apidoc:
19+
@if command -v sphinx-apidoc >/dev/null 2>&1; then \
20+
sphinx-apidoc -o api $(ROOTDIR)/src/robot; \
21+
else \
22+
$(PY) -m sphinx.ext.apidoc -o api $(ROOTDIR)/src/robot; \
23+
fi
24+
25+
html:
26+
$(SPHINXBUILD) -b html "$(SOURCEDIR)" "$(BUILDDIR)/html"
27+
28+
livehtml:
29+
sphinx-autobuild --host 0.0.0.0 --port ${PORT} -c . "$(SOURCEDIR)" "$(BUILDDIR)/html"

‎docs/_static/.gitkeep‎

Whitespace-only changes.

‎docs/api/modules.rst‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
robot
2+
=====
3+
4+
.. toctree::
5+
:maxdepth: 4
6+
7+
robot

‎docs/api/robot.communication.rst‎

Lines changed: 29 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,29 @@
1+
robot.communication package
2+
===========================
3+
4+
Submodules
5+
----------
6+
7+
robot.communication.directed\_comm module
8+
-----------------------------------------
9+
10+
.. automodule:: robot.communication.directed_comm
11+
:members:
12+
:show-inheritance:
13+
:undoc-members:
14+
15+
robot.communication.simple\_comm module
16+
---------------------------------------
17+
18+
.. automodule:: robot.communication.simple_comm
19+
:members:
20+
:show-inheritance:
21+
:undoc-members:
22+
23+
Module contents
24+
---------------
25+
26+
.. automodule:: robot.communication
27+
:members:
28+
:show-inheritance:
29+
:undoc-members:

‎docs/api/robot.helpers.rst‎

Lines changed: 29 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,29 @@
1+
robot.helpers package
2+
=====================
3+
4+
Submodules
5+
----------
6+
7+
robot.helpers.coordinate module
8+
-------------------------------
9+
10+
.. automodule:: robot.helpers.coordinate
11+
:members:
12+
:show-inheritance:
13+
:undoc-members:
14+
15+
robot.helpers.robot\_mqtt module
16+
--------------------------------
17+
18+
.. automodule:: robot.helpers.robot_mqtt
19+
:members:
20+
:show-inheritance:
21+
:undoc-members:
22+
23+
Module contents
24+
---------------
25+
26+
.. automodule:: robot.helpers
27+
:members:
28+
:show-inheritance:
29+
:undoc-members:

‎docs/api/robot.indicators.rst‎

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
robot.indicators package
2+
========================
3+
4+
Submodules
5+
----------
6+
7+
robot.indicators.neopixel module
8+
--------------------------------
9+
10+
.. automodule:: robot.indicators.neopixel
11+
:members:
12+
:show-inheritance:
13+
:undoc-members:
14+
15+
Module contents
16+
---------------
17+
18+
.. automodule:: robot.indicators
19+
:members:
20+
:show-inheritance:
21+
:undoc-members:

‎docs/api/robot.rst‎

Lines changed: 48 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,48 @@
1+
robot package
2+
=============
3+
4+
Subpackages
5+
-----------
6+
7+
.. toctree::
8+
:maxdepth: 4
9+
10+
robot.communication
11+
robot.helpers
12+
robot.indicators
13+
robot.sensors
14+
15+
Submodules
16+
----------
17+
18+
robot.motion module
19+
-------------------
20+
21+
.. automodule:: robot.motion
22+
:members:
23+
:show-inheritance:
24+
:undoc-members:
25+
26+
robot.mqtt\_client module
27+
-------------------------
28+
29+
.. automodule:: robot.mqtt_client
30+
:members:
31+
:show-inheritance:
32+
:undoc-members:
33+
34+
robot.robot\_base module
35+
------------------------
36+
37+
.. automodule:: robot.robot_base
38+
:members:
39+
:show-inheritance:
40+
:undoc-members:
41+
42+
Module contents
43+
---------------
44+
45+
.. automodule:: robot
46+
:members:
47+
:show-inheritance:
48+
:undoc-members:

‎docs/api/robot.sensors.rst‎

Lines changed: 37 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,37 @@
1+
robot.sensors package
2+
=====================
3+
4+
Submodules
5+
----------
6+
7+
robot.sensors.color module
8+
--------------------------
9+
10+
.. automodule:: robot.sensors.color
11+
:members:
12+
:show-inheritance:
13+
:undoc-members:
14+
15+
robot.sensors.distance module
16+
-----------------------------
17+
18+
.. automodule:: robot.sensors.distance
19+
:members:
20+
:show-inheritance:
21+
:undoc-members:
22+
23+
robot.sensors.proximity module
24+
------------------------------
25+
26+
.. automodule:: robot.sensors.proximity
27+
:members:
28+
:show-inheritance:
29+
:undoc-members:
30+
31+
Module contents
32+
---------------
33+
34+
.. automodule:: robot.sensors
35+
:members:
36+
:show-inheritance:
37+
:undoc-members:

0 commit comments

Comments
 (0)