pyforce-rosie 2.0.0__py3-none-any.whl

pyforce_rosie-2.0.0.dist-info/METADATA

@@ -0,0 +1,166 @@
+Metadata-Version: 2.5
+Name: pyforce-rosie
+Version: 2.0.0
+Summary: Mobile robot control in plain Python, for learning and teaching robotics
+Project-URL: Repository, https://github.com/PyForce/rosie
+Project-URL: Issues, https://github.com/PyForce/rosie/issues
+Author: Rolando Urquiza, Fernando Martínez González, Gustavo Viera-López, Antonio Serrano Muñoz, Danilo Gómez Gómez, Alex Coto, Silvio Delgado, Jesús Garnica, Sergio Frayle Pérez
+Maintainer-email: Gustavo Viera-López <gvieralopez@gmail.com>
+License: MIT
+License-File: LICENSE
+Keywords: differential drive,mobile robots,path planning,robotics
+Requires-Python: >=3.12
+Requires-Dist: websockets>=15.0
+Provides-Extra: robot
+Requires-Dist: fastapi>=0.162; extra == 'robot'
+Requires-Dist: numpy>=2.5; extra == 'robot'
+Requires-Dist: pydantic>=2.14; extra == 'robot'
+Requires-Dist: pyserial>=3.5; extra == 'robot'
+Requires-Dist: shapely>=2.2; extra == 'robot'
+Requires-Dist: smbus2>=0.6; extra == 'robot'
+Requires-Dist: typer>=0.27; extra == 'robot'
+Requires-Dist: uvicorn[standard]>=0.54; extra == 'robot'
+Description-Content-Type: text/markdown
+
+<div align="center">
+
+<img src="https://raw.githubusercontent.com/PyForce/rosie/main/assets/logo.svg" alt="" width="96">
+
+# rosie
+
+**Learn mobile robotics by reading the robot**
+
+[![QA](https://github.com/PyForce/rosie/actions/workflows/qa.yml/badge.svg)](https://github.com/PyForce/rosie/actions/workflows/qa.yml)
+[![Release](https://img.shields.io/github/v/release/PyForce/rosie?label=release)](https://github.com/PyForce/rosie/releases/latest)
+[![PyPI](https://img.shields.io/pypi/v/pyforce-rosie)](https://pypi.org/project/pyforce-rosie/)
+[![Docker image](https://img.shields.io/badge/docker-ghcr.io-2496ED?logo=docker&logoColor=white)](https://github.com/PyForce/rosie/pkgs/container/rosie)
+[![Docs](https://readthedocs.org/projects/pyforce-rosie/badge/?version=latest)](https://pyforce-rosie.readthedocs.io)
+[![Python 3.12+](https://img.shields.io/badge/python-3.12%2B-3776AB?logo=python&logoColor=white)](https://www.python.org/)
+[![License: MIT](https://img.shields.io/badge/license-MIT-green)](https://github.com/PyForce/rosie/blob/main/LICENSE)
+<br>
+[![uv](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/uv/main/assets/badge/v0.json)](https://github.com/astral-sh/uv)
+[![Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff)
+[![Checked with mypy](https://www.mypy-lang.org/static/mypy_badge.svg)](https://mypy-lang.org/)
+
+[Quick start](#quick-start) · [What you can learn](#what-you-can-learn) · [Documentation](#documentation) · [Development](#development)
+
+</div>
+
+---
+
+rosie is a complete robot stack (localization, planning, control, drives) for two-wheeled robots, written as
+short Python modules you can read, change and run on a simulated robot or a real one. It estimates where the
+robot is from its wheel encoders, plans routes around walls and furniture and trajectories along them, tracks
+them with feedback controllers, and lets you drive by hand from a browser or from Python.
+
+It's made for learning and teaching robotics, from the control equations to the web page that drives the
+robot.
+
+![WebRosie, rosie's web page, with a robot in the built-in house](https://raw.githubusercontent.com/PyForce/rosie/main/docs/images/webrosie.png)
+
+## Quick start
+
+rosie runs next to the robot, or next to a simulated one, and takes orders over a web API. There are
+several ways to use it: from a browser, from Python, from plain HTTP, or by changing rosie itself. Each
+one below starts with the simulated robot, so no hardware is needed.
+
+### In the browser
+
+```bash
+docker run -p 8080:8080 ghcr.io/pyforce/rosie
+```
+
+Open <http://localhost:8080>: [WebRosie](https://github.com/PyForce/WebRosie), with a simulated robot in a
+house. Click the map to send it somewhere, or drive it with the keyboard.
+
+### As a Python package
+
+```bash
+pip install "pyforce-rosie[robot]"
+rosie start
+```
+
+This runs rosie's web API on port 5000, without the web interface. Flags or `ROSIE_*` environment
+variables pick another robot, map or port.
+
+### From a Python script or notebook
+
+With rosie running (either way above), on the same computer or any other:
+
+```python
+import time
+
+from rosie.client import RosieClient  # pip install pyforce-rosie
+
+robot = RosieClient("http://localhost:8080")  # 5000 with rosie start
+print(robot.odometry())  # Position(x=0.0, y=0.0, theta=0.0)
+robot.goto(1, 0.5, 0.3)  # to (1 m, 0.5 m) at 0.3 m/s
+time.sleep(5)
+print(robot.odometry())  # about Position(x=1.0, y=0.5, theta=0.46)
+```
+
+### Over HTTP
+
+The web API is plain HTTP and JSON, so any language or tool can drive the robot:
+
+```bash
+curl -X POST localhost:8080/goto -d '{"target": [1, 0.5], "speed": 0.3}'
+curl localhost:8080/odometry
+```
+
+### From the source
+
+To change rosie itself, for example to try your own controller:
+
+```bash
+git clone https://github.com/PyForce/rosie
+cd rosie
+uv sync
+uv run rosie start
+```
+
+[Getting started](https://github.com/PyForce/rosie/blob/main/docs/getting-started.md) covers each of these in more detail, plus configuration.
+
+## What you can learn
+
+| Topic | In rosie |
+|---|---|
+| Wheel odometry | second-order Runge-Kutta, from encoder counts |
+| Trajectory generation | straight lines, or cubic polynomials that round the corners |
+| Trajectory tracking | input-output linearization; plug in your own controller as one class |
+| Reaching a point | a polar go-to-point controller |
+| Wheel speed control | an incremental PID |
+| Route planning | free space, a visibility graph, A* |
+| Hardware | serial and I2C motor drives, an ultrasound sensor board |
+| Integration | a REST + WebSocket API, a web interface, a Python client |
+
+The simulated robot runs on a clock you control, so a script can simulate a 10-second movement in
+milliseconds, the same every time. Every planned movement can be recorded to CSV, one row per control step,
+ready for pandas.
+
+## Documentation
+
+- [Getting started](https://github.com/PyForce/rosie/blob/main/docs/getting-started.md): running, driving and configuring rosie.
+- [How rosie works](https://github.com/PyForce/rosie/blob/main/docs/how-rosie-works.md): the control loop, and where everything lives.
+- [Motion control](https://github.com/PyForce/rosie/blob/main/docs/motion-control.md) and [Navigation](https://github.com/PyForce/rosie/blob/main/docs/navigation.md): the algorithms, with their
+  equations.
+- [Teaching with rosie](https://github.com/PyForce/rosie/blob/main/docs/teaching.md): lab ideas.
+- [Robots and hardware](https://github.com/PyForce/rosie/blob/main/docs/robots.md), [Web API and extensions](https://github.com/PyForce/rosie/blob/main/docs/integration.md),
+  [Python client](https://github.com/PyForce/rosie/blob/main/docs/client.md).
+
+## Development
+
+Setup, QA, docs and releases: [DEVELOPMENT.md](https://github.com/PyForce/rosie/blob/main/DEVELOPMENT.md).
+
+## Contributing
+
+Issues and pull requests are welcome; `make qa` must pass.
+
+## License
+
+MIT: see [LICENSE](https://github.com/PyForce/rosie/blob/main/LICENSE). rosie is a [PyForce](https://github.com/PyForce) project, started in 2015:
+[authors](https://github.com/PyForce/rosie/blob/main/docs/about.md).
+
+---
+
+<sub>🚀 Project starter provided by [Cookie Pyrate v1.1.0](https://github.com/gvieralopez/cookie-pyrate/tree/v1.1.0)</sub>

pyforce_rosie-2.0.0.dist-info/RECORD

@@ -0,0 +1,72 @@
+rosie/__init__.py,sha256=_7OlQdbVkK4jad0CLdpI0grT-zEAb-qgFmH5mFzDXiA,22
+rosie/__main__.py,sha256=EI3XZvVxKxqafFFEZNVOdoDQPURBR0vJph03j7syrkY,401
+rosie/cli.py,sha256=J3IIXoA9qIYBMboCNQEGCuWEjrwRPlfNcPR5SaiCP_M,3039
+rosie/core.py,sha256=VaH5kd-Gb7zwrSzw4LcpTPKnr_2lx_IOm4YXWC-E1Wo,8217
+rosie/errors.py,sha256=zeBtg8pMyHe-96qhdg5ZFc0eNPVNW0bQEOW1lld0lmI,640
+rosie/models.py,sha256=0fSD9_aL3rmqJMXzci7YzOoemszGBBXtPU3xr_ISJUI,3834
+rosie/profile.py,sha256=yKMONHhoez6EhCP8F1KlddKrpcf3PBCrQAQxk5h8BGA,3387
+rosie/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+rosie/recording.py,sha256=j2Vy1vNS4JRlVXuPxJVhaI6Bt9S4zR6KcnwNKsv7hYw,3721
+rosie/robot.py,sha256=iqLJR4YcjHcL6G8LumvHH7F27MXhmqUFSY0fYdezG0U,1899
+rosie/service.py,sha256=eJE0U3pYSZV_5TswqLyOHxQMZHpVPrPTpUGdgZ-P8Ks,2936
+rosie/apis/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+rosie/apis/models.py,sha256=Iu0YNtSbLI6cNaw9xsLWml0n_6NT9Uy2uHczN8yWwgk,356
+rosie/apis/web/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+rosie/apis/web/models.py,sha256=gqp1vqmguIQF-HV0P_oOsthpVfu_D6Fx-NEXytb95vA,1381
+rosie/apis/web/routes.py,sha256=bNq7qjoh9bfmro6scuW7T4E46jGUUzXNf2X9Cib4S74,7337
+rosie/apis/web/server.py,sha256=HNoVAyD4606xJ84MExPmpjgG2e57n9813GFJwhZcGXE,2099
+rosie/builtin/maps/house.geojson,sha256=Fafj-ZsWetupjhppQrZjD3HdzMfMmUehbIbmIjdWOwU,3792
+rosie/builtin/profiles/blubot/profile.toml,sha256=D89zIzrz9rVUr-3cj3PeNwuIJhMAv29sMauaHVRzqVE,941
+rosie/builtin/profiles/blubot/thumbnail.png,sha256=saM1bispoPWYW__FgY2ITPg9rhC0b6kTkLgQPtf-aiQ,191199
+rosie/builtin/profiles/blubot/vector.svg,sha256=DJ7-hmBQP8EFvS1ixhw5ADQODPscfEc6TVgpkysz6Q0,14552
+rosie/builtin/profiles/kevin/profile.toml,sha256=kMdsepafPcFUve_tYVUZ6l284I6iLT42tDt3OzuKBB8,911
+rosie/builtin/profiles/kevin/thumbnail.png,sha256=PQ4fuHeG4R5aF7RD_8sO4YxGOVfRPEprUJ7Izmw_acE,255660
+rosie/builtin/profiles/kevin/vector.svg,sha256=vxPHNGza0KTRLyyJwYAiXt3ZICdDgUdgUPE5BNYAN-Y,22923
+rosie/builtin/profiles/ltl/profile.toml,sha256=vJ8QG3_k53_UYEBCpVVb0RA3IHeN2UJ8FCYRYMLhMIo,1016
+rosie/builtin/profiles/ltl/thumbnail.png,sha256=jSEunewwtZXtp1-gsdEjfYKMwn9RTFbgX-u8jho86Oo,241946
+rosie/builtin/profiles/ltl/vector.svg,sha256=5Tr1pPbsZDQL8Fyi6gLpLFbSlNHQa5a5eixkg5gWxRA,27707
+rosie/builtin/profiles/rovert/profile.toml,sha256=1QPG1YkJcnySzcnYYCQq_a6MXbAGUo6PYvyW7eqdXZU,946
+rosie/builtin/profiles/rovert/thumbnail.png,sha256=lxWBxfxrqVkvB69_nV5OeTo1T31LRS42IxOv-6beqB8,144212
+rosie/builtin/profiles/rovert/vector.svg,sha256=U8586XwxunzqUSZA23NcxK6O3O9_XeyMRv3zm4N4twQ,9113
+rosie/builtin/profiles/simubot/profile.toml,sha256=-JqF0MzcRGRUGx7sOE9GOUIf1UdUkzHLJLhyFGpb8og,769
+rosie/builtin/profiles/simubot/thumbnail.png,sha256=YCBCae6OodHg5rvotLg1bkJquwDY7V3ybVKZiUwn5R8,56233
+rosie/builtin/profiles/simubot/vector.svg,sha256=p1APWqiuvyo99JZv_WNXmRIr9lTy51GQL2dafQcYNMs,31720
+rosie/client/__init__.py,sha256=KPU4ziUe9wmT2syTEEKnfM3rkRLzKWCUavE_DLh6h7o,434
+rosie/client/api.py,sha256=mxM0vnmZFvbTpIj5fBegeYrQ2Qi39A1g-N3LcDaYQN0,6981
+rosie/client/models.py,sha256=QoKPx0UeSiBiGAAN6s4WPsfHsspXFaFg5Q_SkgdgIpI,629
+rosie/control/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+rosie/control/models.py,sha256=LHT17ern9oDmNbSePELLHPvUUlZ8mP4NOt9k_sVU3gU,2278
+rosie/control/movement.py,sha256=T2KnQjHQiAbwKmqCouiHYGWxOyKc2scwbpXPa_By8Cw,4677
+rosie/control/regulation.py,sha256=OHM1jGLZ-ctITAhGr_UF4EdepymipLG8lPR9VokMDnc,1358
+rosie/control/teleoperation.py,sha256=ekLPg8hjVlAR_hvGhXonuFXxoAa9DWVFwoqBRdJBFBs,1081
+rosie/control/tracking.py,sha256=tG9bxO53UzA_Ei4AXH6bvY88DPRwXeAOCH0CiJ-sLgk,1359
+rosie/hardware/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+rosie/hardware/buses.py,sha256=I6p90kOqaHCkel9ph2Ll5Cma3rYWE9lwvypqNfVyKgM,1150
+rosie/hardware/models.py,sha256=7ZEBYOgpGz7JWpikZOqdrHzIKfyzICSJtrs4Xp3SiEo,596
+rosie/hardware/drive/__init__.py,sha256=YNNIWvXKqCIz1vDhHRCiIjYG0TXvPS55dwb3tAzZoIw,677
+rosie/hardware/drive/kinematics.py,sha256=dOuVXp74fK8GT37vpSvFHhSGjjhRainLG2TGEzrKibc,514
+rosie/hardware/drive/models.py,sha256=wC2UrYMIJ8kDQsBA38HhELLBMOEbs6RLIVAnPOJr_PM,1820
+rosie/hardware/drive/pid.py,sha256=6CgK7vJNasm0ljDI_4Wnvj7Jy3qjpTBXWq4PhIxznvQ,800
+rosie/hardware/drive/devices/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+rosie/hardware/drive/devices/arduino.py,sha256=rT1Apl50oi-ubnrAlsY2NInFSJhPapZhZQzEaypmyrk,3390
+rosie/hardware/drive/devices/md25.py,sha256=_M-1zvv0Rm1kjOE6pKPpLYGFtkfH9S42AsqEVTEFCEk,5839
+rosie/hardware/drive/devices/virtual.py,sha256=gF2En6t3dPYt5XCWljM_FNSBqpwt-5mf2HuDi1hf3UY,2588
+rosie/hardware/sensors/__init__.py,sha256=gIexC6Hocuv6NKNTuHRasuP2-tZNPZLBPzXNvAs6NWs,806
+rosie/hardware/sensors/models.py,sha256=zaIGiXWruSBg_-zSFmHFXCg14_tUphHD2npSLxR7yy4,349
+rosie/hardware/sensors/usound.py,sha256=Zglmv6LmoM0MGXjBhlRDMPIBMOUVO0ZTrt7qEK8G2mc,7977
+rosie/localization/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+rosie/localization/odometry.py,sha256=w_guiEeN1XdhYLxO5RolnzZMaPj1KZCpPnBvAdsOhjo,1480
+rosie/planning/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+rosie/planning/models.py,sha256=aM8rZs-UZ7j2big2etSNhGFUOD1cc0oAUhYrSejUx70,1181
+rosie/planning/path.py,sha256=DZCxQxOavYktY798KsiaZ1l97qYhEH7701FsYSUE3aA,1156
+rosie/planning/search.py,sha256=BJS-FR-ZfMpdTd65-QM0kpLZLe_K3lBaSq-Y6GZPHu8,1640
+rosie/planning/trajectory.py,sha256=ULxYW5tyrqaLQ658gLGqHZC99wCgRJaQ2tLeAySX_YQ,6284
+rosie/planning/visibility.py,sha256=gBjtMGGNCPGngZGmD2oDPI8QnFUPMoE3bJR39A2LfO4,2830
+rosie/world/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+rosie/world/maps.py,sha256=zUmKwgZIRVueodvBB8KYhHGSGt9K7zGmzi7sKe-hi9U,2742
+rosie/world/models.py,sha256=MYPWSX_1ITQtkE5wJnrmiQVTDjq_kc-ANCIt6qEOBJ0,444
+pyforce_rosie-2.0.0.dist-info/METADATA,sha256=lxuB1aSOnqm8eBk8O_pmx3XKBz0zOUuGwmwwP_SNAnY,7422
+pyforce_rosie-2.0.0.dist-info/WHEEL,sha256=2iZrJkDIkeDh0k9SikKMqFuRP-ua6mb4Ir1AsER4BEw,87
+pyforce_rosie-2.0.0.dist-info/entry_points.txt,sha256=NAs606q0hysPA4fQ5U2ICf2PxAaqE4JiHVsgfVLiyOg,46
+pyforce_rosie-2.0.0.dist-info/licenses/LICENSE,sha256=besggTlfcnF02jOikkoAnanhiOOyHM7tf_sAqkvnjYM,1083
+pyforce_rosie-2.0.0.dist-info/RECORD,,

pyforce_rosie-2.0.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.33.0
+Root-Is-Purelib: true
+Tag: py3-none-any

pyforce_rosie-2.0.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+rosie = rosie.__main__:main

pyforce_rosie-2.0.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2015 The rosie authors (PyForce)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

rosie/__init__.py

@@ -0,0 +1 @@
+__version__ = "2.0.0"

rosie/__main__.py

@@ -0,0 +1,17 @@
+import importlib
+import sys
+
+
+def main() -> None:
+    try:
+        # the command needs the `robot` extra; the client alone doesn't
+        cli = importlib.import_module("rosie.cli")
+    except ModuleNotFoundError as error:
+        sys.exit(
+            f"rosie needs the robot: pip install 'pyforce-rosie[robot]' (missing {error.name})"
+        )
+    cli.app()
+
+
+if __name__ == "__main__":
+    main()

rosie/apis/models.py

@@ -0,0 +1,11 @@
+from collections.abc import Callable
+from contextlib import AbstractAsyncContextManager
+from typing import TYPE_CHECKING
+
+from rosie.models import StartSettings
+
+if TYPE_CHECKING:
+    from rosie.core import Robot
+
+# an interface serves the robot while inside its context
+type Interface = Callable[[Robot, StartSettings], AbstractAsyncContextManager[None]]

rosie/apis/web/models.py

@@ -0,0 +1,57 @@
+from typing import Literal
+
+from pydantic import BaseModel, ConfigDict
+
+
+class _Frozen(BaseModel):
+    model_config = ConfigDict(frozen=True)
+
+
+class Position(_Frozen):
+    x: float  # m
+    y: float  # m
+    theta: float  # rad
+
+
+class GotoOrder(_Frozen):
+    target: tuple[float, float]  # x, y (m)
+    speed: float  # m/s
+    planner: bool = False  # go around walls and furniture
+
+
+class FollowOrder(_Frozen):
+    path: list[tuple[float, float]]  # points to drive through (m)
+    speed: float  # m/s
+    planner: bool = False  # go around walls and furniture from point to point
+
+
+class RobotInfo(_Frozen):
+    name: str
+    thumbnail: str  # path of the robot's picture
+    vector: str  # path of the robot's icon
+    video: str | Literal[False]  # video stream (":port/path" on the robot's host), if any
+    size: tuple[float, float, float]  # length, width, height (m)
+    profile: str
+
+
+class Maps(_Frozen):
+    maps: list[str]
+
+
+class TrajectoryPlanners(_Frozen):
+    planners: list[str]
+    in_use: str
+
+
+class DriveCommand(_Frozen):
+    """WebSocket, client to rosie: the driving commands under manual control."""
+
+    type: Literal["move"]
+    data: tuple[float, float, float]  # steering, throttle, spin, each in [-1, 1]
+
+
+class PositionUpdate(_Frozen):
+    """WebSocket, rosie to clients: where the robot is now."""
+
+    type: Literal["position"]
+    data: Position

rosie/apis/web/routes.py

@@ -0,0 +1,228 @@
+import asyncio
+import json
+import logging
+from typing import Annotated, Any
+
+from fastapi import APIRouter, Depends, HTTPException, Request, WebSocket, WebSocketDisconnect
+from fastapi.responses import FileResponse, JSONResponse, Response
+from pydantic import ValidationError
+
+from rosie.apis.web.models import (
+    DriveCommand,
+    FollowOrder,
+    GotoOrder,
+    Maps,
+    Position,
+    PositionUpdate,
+    RobotInfo,
+    TrajectoryPlanners,
+)
+from rosie.control.models import Telemetry
+from rosie.core import Robot
+from rosie.errors import NoRouteError
+from rosie.planning.trajectory import TRAJECTORY_PLANNERS
+
+logger = logging.getLogger(__name__)
+
+router = APIRouter()
+
+
+def get_robot(request: Request) -> Robot:
+    robot: Robot = request.app.state.robot
+    return robot
+
+
+RobotDependency = Annotated[Robot, Depends(get_robot)]
+
+
+@router.get("/odometry")
+def odometry(robot: RobotDependency) -> Position:
+    x, y, theta = robot.position()
+    return Position(x=x, y=y, theta=theta)
+
+
+@router.get("/metadata")
+def metadata(request: Request, robot: RobotDependency) -> RobotInfo:
+    profile = robot.profile
+    return RobotInfo(
+        name=profile.name,
+        thumbnail=request.app.url_path_for("thumbnail"),
+        vector=request.app.url_path_for("vector"),
+        video=profile.camera.stream if profile.camera else False,
+        size=(profile.body.length, profile.body.width, profile.body.height),
+        profile=profile.folder_name,
+    )
+
+
+@router.get("/thumbnail")
+def thumbnail(robot: RobotDependency) -> FileResponse:
+    return FileResponse(robot.profile.picture)
+
+
+@router.get("/vector")
+def vector(robot: RobotDependency) -> FileResponse:
+    return FileResponse(robot.profile.icon)
+
+
+@router.get("/sensor/{name}")
+def sensor(name: str, robot: RobotDependency) -> dict[str, object]:
+    if name not in robot.sensors:
+        raise HTTPException(status_code=404, detail=f"no sensor {name}")
+    return {name: robot.sensors[name]()}
+
+
+@router.post("/position")
+async def position(request: Request, robot: RobotDependency) -> Response:
+    """Teleport the robot."""
+    target = Position.model_validate_json(await request.body())
+    robot.teleport(target.x, target.y, target.theta)
+    return Response()
+
+
+@router.post("/goto")
+async def goto(request: Request, robot: RobotDependency) -> Response:
+    order = GotoOrder.model_validate_json(await request.body())
+    x, y = order.target
+    try:
+        if order.planner:
+            robot.follow_with_planner([(x, y)], order.speed)
+        else:
+            robot.goto(x, y, order.speed)
+    except NoRouteError as error:
+        return JSONResponse({"error": str(error)}, status_code=409)
+    except ValueError as error:
+        return JSONResponse({"detail": str(error)}, status_code=422)
+    return Response()
+
+
+@router.post("/follow")
+async def follow(request: Request, robot: RobotDependency) -> Response:
+    order = FollowOrder.model_validate_json(await request.body())
+    try:
+        if order.planner:
+            robot.follow_with_planner(order.path, order.speed)
+        else:
+            robot.follow(order.path, order.speed)
+    except NoRouteError as error:
+        return JSONResponse({"error": str(error)}, status_code=409)
+    except ValueError as error:
+        return JSONResponse({"detail": str(error)}, status_code=422)
+    return Response()
+
+
+@router.get("/maps")
+def maps(robot: RobotDependency) -> Maps:
+    return Maps(maps=list(robot.maps()))
+
+
+@router.get("/map")
+def current_map(robot: RobotDependency) -> dict[str, Any]:
+    """The map the planner uses."""
+    worldmap = robot.get_map(robot.map_name) if robot.map_name else None
+    if not worldmap:
+        raise HTTPException(status_code=404)
+    return worldmap
+
+
+@router.get("/map/{name}")
+def getmap(name: str, robot: RobotDependency) -> dict[str, Any]:
+    worldmap = robot.get_map(name)
+    if not worldmap:
+        raise HTTPException(status_code=404)
+    return worldmap
+
+
+@router.post("/map/{name}")
+def use_map(name: str, robot: RobotDependency) -> Response:
+    """Plan routes on this map from now on."""
+    if name not in robot.maps():
+        raise HTTPException(status_code=404, detail=f"no map {name}")
+    robot.use_map(name)
+    return Response()
+
+
+@router.get("/trajectory-planners")
+def trajectory_planners(robot: RobotDependency) -> TrajectoryPlanners:
+    return TrajectoryPlanners(planners=list(TRAJECTORY_PLANNERS), in_use=robot.trajectory_planner)
+
+
+@router.post("/trajectory-planner/{name}")
+def use_trajectory_planner(name: str, robot: RobotDependency) -> Response:
+    """Plan the next movements with this trajectory planner."""
+    if name not in TRAJECTORY_PLANNERS:
+        raise HTTPException(status_code=404, detail=f"no trajectory planner {name}")
+    robot.use_trajectory_planner(name)
+    return Response()
+
+
+class WebObserver:
+    """Streams the robot's position to WebSocket clients, and takes their commands in manual mode."""
+
+    def __init__(self, robot: Robot) -> None:
+        self.robot = robot
+        self.is_manual = False
+        self.clients: list[WebSocket] = []
+        # pending sends, kept until done (the event loop only keeps weak references)
+        self.sending: set[asyncio.Task[None]] = set()
+        self.last_location = (0.0, 0.0, 0.0)
+
+    async def websocket(self, websocket: WebSocket) -> None:
+        await websocket.accept()
+        logger.debug("connected websocket client: %s", websocket.client)
+        self.clients.append(websocket)
+        try:
+            while True:
+                self._receive(await websocket.receive_text())
+        except WebSocketDisconnect:
+            pass
+        finally:
+            self.clients.remove(websocket)
+
+    def movement_begin(self, expected_updates: int | None) -> None:
+        pass
+
+    def movement_end(self) -> None:
+        pass
+
+    def movement_update(self, telemetry: Telemetry) -> None:
+        pose = telemetry.pose
+        location = (pose.x, pose.y, pose.theta)
+        if location == self.last_location:
+            return
+        self.last_location = location
+
+        message = PositionUpdate(
+            type="position", data=Position(x=pose.x, y=pose.y, theta=pose.theta)
+        ).model_dump_json()
+        for client in list(self.clients):
+            task = asyncio.create_task(client.send_text(message))
+            self.sending.add(task)
+            task.add_done_callback(self._sent)
+
+    def manual(self) -> Response:
+        self.is_manual = True
+        self.robot.start_manual()
+        return Response()
+
+    def planned(self) -> Response:
+        self.is_manual = False
+        self.robot.stop_manual()
+        return Response()
+
+    def _receive(self, text: str) -> None:
+        message = json.loads(text)
+        if not isinstance(message, dict) or message.get("type") != "move" or not self.is_manual:
+            return
+        try:
+            move = DriveCommand.model_validate(message)
+        except ValidationError:
+            logger.warning("ignoring malformed move: %s", text)
+            return
+        steering, throttle, spin = move.data
+        self.robot.move(steering, throttle, spin)
+
+    def _sent(self, task: asyncio.Task[None]) -> None:
+        """Forget a finished send; a client gone meanwhile is not an error."""
+        self.sending.discard(task)
+        if not task.cancelled():
+            task.exception()

rosie/apis/web/server.py

@@ -0,0 +1,59 @@
+import asyncio
+import logging
+from collections.abc import AsyncGenerator
+from contextlib import asynccontextmanager
+
+import uvicorn
+from fastapi import FastAPI, Request
+from fastapi.middleware.cors import CORSMiddleware
+from fastapi.responses import Response
+from pydantic import ValidationError
+
+from rosie.apis.web import routes
+from rosie.core import Robot
+from rosie.models import StartSettings
+
+logger = logging.getLogger(__name__)
+
+
+@asynccontextmanager
+async def start_web_api(robot: Robot, settings: StartSettings) -> AsyncGenerator[None, None]:
+    """Start the web API; on the way out of the block, uvicorn closes its connections."""
+    server = uvicorn.Server(
+        uvicorn.Config(
+            create_app(robot), host=settings.host, port=settings.port, log_level="warning"
+        )
+    )
+    serving = asyncio.create_task(server.serve())
+    logger.info("web API on http://%s:%d", settings.host, settings.port)
+    try:
+        yield
+    finally:
+        server.should_exit = True
+        await serving
+
+
+def create_app(robot: Robot) -> FastAPI:
+    """REST + WebSocket interface to `robot`."""
+    app = FastAPI(title="rosie")
+    # WebRosie is served from another origin than the robot
+    app.add_middleware(
+        CORSMiddleware, allow_origins=["*"], allow_methods=["*"], allow_headers=["*"]
+    )
+
+    @app.exception_handler(ValidationError)
+    async def invalid_request(_request: Request, error: ValidationError) -> Response:
+        # error.json() also serialises raw input that isn't valid JSON (bytes)
+        detail = error.json(include_url=False)
+        return Response(f'{{"detail":{detail}}}', status_code=422, media_type="application/json")
+
+    app.state.robot = robot
+    app.include_router(routes.router)
+
+    observer = routes.WebObserver(robot)
+    robot.observers.append(observer)
+    # bound methods can't use the decorators
+    app.add_api_websocket_route("/websocket", observer.websocket)
+    app.add_api_route("/manual", observer.manual, methods=["PUT", "POST"])
+    app.add_api_route("/planned", observer.planned, methods=["PUT", "POST"])
+    return app