psc-sr-robot3 2026.0.3.18__tar.gz

psc_sr_robot3-2026.0.3.18/.flake8

@@ -0,0 +1,14 @@
+[flake8]
+max_line_length = 95
+ignore =
+    # Don't require imperative mood docstrings.
+    D401,
+    # Ignore docstrings on magic methods
+    D105,
+    # Ignore docstrings on init methods
+    D107,
+    # Allow line breaks before and after a binary operator
+    W503, W504,
+    # Ignore TODO comments
+    T000,
+

psc_sr_robot3-2026.0.3.18/.github/dependabot.yml

@@ -0,0 +1,34 @@
+version: 2
+updates:
+- package-ecosystem: pip
+  directory: "/"
+  schedule:
+    interval: daily
+  open-pull-requests-limit: 10
+  ignore:
+  - dependency-name: sphinx
+    versions:
+    - 3.4.3
+    - 3.5.0
+    - 3.5.1
+    - 3.5.2
+    - 3.5.3
+  - dependency-name: flake8
+    versions:
+    - 3.8.4
+    - 3.9.0
+  - dependency-name: pytest
+    versions:
+    - 6.2.2
+  - dependency-name: sphinx-rtd-theme
+    versions:
+    - 0.5.1
+  - dependency-name: isort
+    versions:
+    - 5.7.0
+  - dependency-name: flake8-comprehensions
+    versions:
+    - 3.3.1
+  - dependency-name: rope
+    versions:
+    - 0.18.0

psc_sr_robot3-2026.0.3.18/.github/workflows/test_build.yml

@@ -0,0 +1,87 @@
+name: Lint & build
+
+on:
+  push:
+  workflow_dispatch:
+
+jobs:
+  test:
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest]
+        py_version: ["3.9", "3.10", "3.11", "3.12", "3.13"]
+        include:
+          - os: windows-latest
+            py_version: "3.9"
+          - os: windows-latest
+            py_version: "3.13"
+          - os: macos-latest
+            py_version: "3.9"
+          - os: macos-latest
+            py_version: "3.13"
+    runs-on: ${{ matrix.os }}
+    steps:
+    - uses: actions/checkout@v4
+      with:
+        fetch-depth: 0
+    - name: Set up Python
+      uses: actions/setup-python@v5
+      with:
+        python-version: ${{ matrix.py_version }}
+    - name: Install dependencies
+      run: |
+        python -m pip install --upgrade pip
+        python -m pip install .[dev,vision]
+    - name: Lint
+      run: |
+        make lint
+    - name: Isort
+      run: |
+        make isort-check
+    - name: Typecheck
+      run: |
+        make type
+    - name: Run tests
+      run: |
+        make test
+
+  build:
+    permissions:
+      id-token: write  # IMPORTANT: this permission is mandatory for trusted publishing
+    runs-on: ubuntu-latest
+    needs: test
+    # PyPI's trusted publisher for psc-sr-robot3 names this environment
+    environment:
+      name: pypi
+      url: https://pypi.org/p/psc-sr-robot3
+    steps:
+    - uses: actions/checkout@v4
+      with:
+        fetch-depth: 0
+    - name: Set up Python 3.10
+      uses: actions/setup-python@v5
+      with:
+        python-version: "3.10"
+    - name: Install dependencies
+      run: |
+        python -m pip install --upgrade pip build
+        # Install package to generate version info
+        python -m pip install .
+    - name: Build package
+      run: |
+        make build
+    - name: Save built package
+      uses: actions/upload-artifact@v4
+      with:
+        name: package
+        path: |
+          dist
+    - name: Check the package
+      run: |
+        python -m pip install twine
+        python -m twine check --strict dist/*
+    - name: Publish to PyPi
+      # Version tags only, such as 2026.0.3.18
+      if: ${{ github.ref_type == 'tag' && startsWith(github.ref_name, '20') }}
+      uses: pypa/gh-action-pypi-publish@release/v1

psc_sr_robot3-2026.0.3.18/.gitignore

@@ -0,0 +1,135 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+pip-wheel-metadata/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+#  Usually these files are written by a python script from a template
+#  before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py,cover
+.hypothesis/
+.pytest_cache/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+.python-version
+
+# pipenv
+#   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
+#   However, in case of collaboration, if having platform-specific dependencies or dependencies
+#   having no cross-platform support, pipenv may install dependencies that don't work, or not
+#   install all needed dependencies.
+#Pipfile.lock
+
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+_version.py
+
+# macOS metadata
+.DS_Store
+**/.DS_Store

psc_sr_robot3-2026.0.3.18/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2019-21 Dan Trickey
+Copyright (c) 2023 SourceBots
+
+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.

psc_sr_robot3-2026.0.3.18/Makefile

@@ -0,0 +1,33 @@
+.PHONY: lint type test test-html isort isort-check build upload
+
+PYMODULE:=sr/robot3
+TESTS:=tests
+
+all: lint isort-check type test
+
+lint:
+	flake8 $(PYMODULE)
+
+type:
+	mypy $(PYMODULE)
+
+test:
+	pytest --cov=$(PYMODULE) --cov-report=term --cov-report=xml $(TESTS)
+
+test-html:
+	pytest --cov=$(PYMODULE) --cov-report=html $(TESTS)
+
+isort-check:
+	python -m isort --check $(PYMODULE)
+
+isort:
+	python -m isort $(PYMODULE)
+
+build:
+	python -m build
+
+upload:
+	twine upload dist/*
+
+clean:
+	rm -rf dist/* build/*

psc_sr_robot3-2026.0.3.18/PKG-INFO

@@ -0,0 +1,195 @@
+Metadata-Version: 2.4
+Name: psc-sr-robot3
+Version: 2026.0.3.18
+Summary: PSC Robotics' version of the Student Robotics API for Python 3
+Author: PSC Robotics
+Author-email: Student Robotics <kit-team@studentrobotics.org>
+License: MIT License
+        
+        Copyright (c) 2019-21 Dan Trickey
+        Copyright (c) 2023 SourceBots
+        
+        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.
+        
+Project-URL: Repository, https://github.com/PSC-Robotics/Custom-SR-Library
+Project-URL: Homepage, https://psc-robotics.uk
+Project-URL: Documentation, https://docs.psc-robotics.uk
+Project-URL: Student Robotics sr-robot3, https://github.com/srobo/sr-robot
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Operating System :: OS Independent
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Typing :: Typed
+Classifier: Topic :: Education
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: pyserial<4,>=3
+Requires-Dist: april_vision==3.0.0
+Requires-Dist: paho-mqtt<3,>=2
+Requires-Dist: pydantic<2,>=1.9.1
+Requires-Dist: typing-extensions; python_version < "3.10"
+Requires-Dist: tomli<3,>=2.0.1; python_version < "3.11"
+Provides-Extra: dev
+Requires-Dist: flake8; extra == "dev"
+Requires-Dist: isort; extra == "dev"
+Requires-Dist: mypy<2,>=1.7; extra == "dev"
+Requires-Dist: build; extra == "dev"
+Requires-Dist: types-pyserial; extra == "dev"
+Requires-Dist: pytest; extra == "dev"
+Requires-Dist: pytest-cov; extra == "dev"
+Requires-Dist: paho-mqtt<3,>=2; extra == "dev"
+Provides-Extra: vision
+Requires-Dist: opencv-python-headless<5,>=4.10; extra == "vision"
+Dynamic: license-file
+
+# psc-sr-robot3
+
+[![MIT license](https://img.shields.io/badge/license-MIT-brightgreen.svg?style=flat)](https://opensource.org/licenses/MIT)
+
+`psc-sr-robot3` is PSC Robotics' version of [sr-robot3](https://github.com/srobo/sr-robot),
+the Student Robotics Python API. It adds PSC's brain board: GPIO motors and steppers,
+servo drivers and I2C, the brain board LED and battery sensor, the buzzer and gamepads.
+See the [PSC Robotics docs](https://docs.psc-robotics.uk).
+
+Your code imports it as `sr.robot3`, the same as Student Robotics' library, so the two
+can't be installed together. The PSC Robotics OS image already has it installed; install
+it on a computer to get code completion and type checking while you write robot code.
+
+## Installation
+
+```bash
+pip install psc-sr-robot3
+```
+
+To include OpenCV, for the camera:
+
+```bash
+pip install "psc-sr-robot3[vision]"
+```
+
+Versions are Student Robotics' base version followed by PSC's own release number:
+2026.0.3.18 is PSC release 18 of sr-robot3 2026.0.3.
+
+## Usage
+
+The main entry point for the API is the `Robot` class.
+Instantiating this class will automatically detect and connect to any supported SR v4 boards connected to the device.
+All SR boards are optional; connected boards are initialized and exposed as usual. By default, the `Robot` class waits for a start signal before continuing. When a power board is present, its start button is used; without one, the start signal can come from Astoria.
+
+```python
+
+from sr.robot3 import Robot
+
+r = Robot()
+
+```
+
+To disable the waiting for the start button, you can pass `wait_for_start=False` to the constructor.
+The `wait_for_start` method needs to be called before the metadata is available.
+
+```python
+
+from sr.robot3 import Robot
+
+r = Robot(wait_for_start=False)
+
+# Setup in here
+
+r.wait_start()
+
+```
+
+An Arduino running firmware version 4 or later can drive a step/direction
+stepper driver with `arduino.stepper_move(step_pin, direction_pin, steps)`. The
+call blocks until the requested pulses are emitted; pass `direction=False` to
+drive DIR low, and use `step_delay_us` to set the low interval between pulses.
+Moves are limited to 350 ms per command so they fit within the serial timeout.
+This API does not provide acceleration or track motor position.
+
+### Buzzer
+
+`robot.buzzer.buzz(frequency, duration, blocking=False)` plays a tone on the
+buzzer connected to the brain board, like the Student Robotics power board's
+`piezo.buzz()`. `Note` values such as `Note.A6` can be used for the frequency.
+A new tone replaces the one playing. Tones are played by the robot's status
+service, which also beeps when code is waiting for the start button, when start
+is pressed, and with fast short beeps when code crashes.
+
+### Steppers on the brain board's GPIO pins
+
+`robot.brain.stepper_move(step_pin, direction_pin, steps)` drives a
+step/direction stepper driver wired to the Pi's GPIO header, using BCM GPIO
+numbers. It takes the same arguments as `arduino.stepper_move`, but has no
+350 ms limit: `steps` can be up to 1000000 and `step_delay_us` from 50 to
+1000000. Timing is done in software, so step timing can vary slightly. GPIO 5,
+13 and 18 are used by the robot and can't be used.
+
+### Multiple cameras
+
+Every connected camera with a calibration is available in `robot.cameras`.
+`robot.camera` still works when exactly one camera is connected.
+
+```python
+from sr.robot3 import Robot
+
+r = Robot()
+
+for camera_id, camera in r.cameras.items():
+    print(camera_id, camera.see())
+
+front = r.cameras["A1B2C3D4"]
+```
+
+Cameras are keyed by their USB serial number. Cameras with no serial number,
+a generic placeholder serial or a serial shared with another connected camera
+are keyed by the USB port they are plugged into, such as `usb-1-1.2`. Keep
+those cameras in the same ports so their names stay the same. The camera
+calibration dialog in the robot web UI shows the name of each connected camera.
+Cameras of the same model share one calibration.
+
+### Camera calibrations
+
+The bundled Logitech calibrations are used automatically and are read-only in
+the camera calibration dialog. Custom calibration directories can be added to the code
+USB root with either `camera-calibrations.toml`:
+
+```toml
+calibrations = ["camera-calibrations"]
+```
+
+or `camera-calibrations.json`:
+
+```json
+{"calibrations": ["camera-calibrations"]}
+```
+
+Place the AprilVision calibration XML files in the listed directory. Paths are
+relative to the manifest and must remain on the code USB. Only cameras matching
+a loaded calibration are added to `Robot.cameras`.
+
+## Developer Notes
+
+There are a number of considerations that have been made in the design of this API.
+Some of these may not be immediately obvious, so they are documented below.
+
+- The API is designed to raise exceptions for incorrect actions, such as trying to modify the output dictionary or assign a value directly to the motor object.
+- `MappingProxyType` is used to prevent the user from adding, removing or overwriting keys in any parts of the API that return a dictionary.
+- `tuple` is used to prevent the user from adding, removing or overwriting items in any parts of the API that would return a list.
+- `__slots__` is used to prevent the user from adding, removing or overwriting attributes in any parts of the API.
+- `sr.robot3.serial_wrapper.SerialWrapper` handles automatic reconnection to the serial port if the connection is lost and impleents 3 retries on any serial operation before raising a `BoardDisconnectionError`.

psc_sr_robot3-2026.0.3.18/README.md

@@ -0,0 +1,135 @@
+# psc-sr-robot3
+
+[![MIT license](https://img.shields.io/badge/license-MIT-brightgreen.svg?style=flat)](https://opensource.org/licenses/MIT)
+
+`psc-sr-robot3` is PSC Robotics' version of [sr-robot3](https://github.com/srobo/sr-robot),
+the Student Robotics Python API. It adds PSC's brain board: GPIO motors and steppers,
+servo drivers and I2C, the brain board LED and battery sensor, the buzzer and gamepads.
+See the [PSC Robotics docs](https://docs.psc-robotics.uk).
+
+Your code imports it as `sr.robot3`, the same as Student Robotics' library, so the two
+can't be installed together. The PSC Robotics OS image already has it installed; install
+it on a computer to get code completion and type checking while you write robot code.
+
+## Installation
+
+```bash
+pip install psc-sr-robot3
+```
+
+To include OpenCV, for the camera:
+
+```bash
+pip install "psc-sr-robot3[vision]"
+```
+
+Versions are Student Robotics' base version followed by PSC's own release number:
+2026.0.3.18 is PSC release 18 of sr-robot3 2026.0.3.
+
+## Usage
+
+The main entry point for the API is the `Robot` class.
+Instantiating this class will automatically detect and connect to any supported SR v4 boards connected to the device.
+All SR boards are optional; connected boards are initialized and exposed as usual. By default, the `Robot` class waits for a start signal before continuing. When a power board is present, its start button is used; without one, the start signal can come from Astoria.
+
+```python
+
+from sr.robot3 import Robot
+
+r = Robot()
+
+```
+
+To disable the waiting for the start button, you can pass `wait_for_start=False` to the constructor.
+The `wait_for_start` method needs to be called before the metadata is available.
+
+```python
+
+from sr.robot3 import Robot
+
+r = Robot(wait_for_start=False)
+
+# Setup in here
+
+r.wait_start()
+
+```
+
+An Arduino running firmware version 4 or later can drive a step/direction
+stepper driver with `arduino.stepper_move(step_pin, direction_pin, steps)`. The
+call blocks until the requested pulses are emitted; pass `direction=False` to
+drive DIR low, and use `step_delay_us` to set the low interval between pulses.
+Moves are limited to 350 ms per command so they fit within the serial timeout.
+This API does not provide acceleration or track motor position.
+
+### Buzzer
+
+`robot.buzzer.buzz(frequency, duration, blocking=False)` plays a tone on the
+buzzer connected to the brain board, like the Student Robotics power board's
+`piezo.buzz()`. `Note` values such as `Note.A6` can be used for the frequency.
+A new tone replaces the one playing. Tones are played by the robot's status
+service, which also beeps when code is waiting for the start button, when start
+is pressed, and with fast short beeps when code crashes.
+
+### Steppers on the brain board's GPIO pins
+
+`robot.brain.stepper_move(step_pin, direction_pin, steps)` drives a
+step/direction stepper driver wired to the Pi's GPIO header, using BCM GPIO
+numbers. It takes the same arguments as `arduino.stepper_move`, but has no
+350 ms limit: `steps` can be up to 1000000 and `step_delay_us` from 50 to
+1000000. Timing is done in software, so step timing can vary slightly. GPIO 5,
+13 and 18 are used by the robot and can't be used.
+
+### Multiple cameras
+
+Every connected camera with a calibration is available in `robot.cameras`.
+`robot.camera` still works when exactly one camera is connected.
+
+```python
+from sr.robot3 import Robot
+
+r = Robot()
+
+for camera_id, camera in r.cameras.items():
+    print(camera_id, camera.see())
+
+front = r.cameras["A1B2C3D4"]
+```
+
+Cameras are keyed by their USB serial number. Cameras with no serial number,
+a generic placeholder serial or a serial shared with another connected camera
+are keyed by the USB port they are plugged into, such as `usb-1-1.2`. Keep
+those cameras in the same ports so their names stay the same. The camera
+calibration dialog in the robot web UI shows the name of each connected camera.
+Cameras of the same model share one calibration.
+
+### Camera calibrations
+
+The bundled Logitech calibrations are used automatically and are read-only in
+the camera calibration dialog. Custom calibration directories can be added to the code
+USB root with either `camera-calibrations.toml`:
+
+```toml
+calibrations = ["camera-calibrations"]
+```
+
+or `camera-calibrations.json`:
+
+```json
+{"calibrations": ["camera-calibrations"]}
+```
+
+Place the AprilVision calibration XML files in the listed directory. Paths are
+relative to the manifest and must remain on the code USB. Only cameras matching
+a loaded calibration are added to `Robot.cameras`.
+
+## Developer Notes
+
+There are a number of considerations that have been made in the design of this API.
+Some of these may not be immediately obvious, so they are documented below.
+
+- The API is designed to raise exceptions for incorrect actions, such as trying to modify the output dictionary or assign a value directly to the motor object.
+- `MappingProxyType` is used to prevent the user from adding, removing or overwriting keys in any parts of the API that return a dictionary.
+- `tuple` is used to prevent the user from adding, removing or overwriting items in any parts of the API that would return a list.
+- `__slots__` is used to prevent the user from adding, removing or overwriting attributes in any parts of the API.
+- `sr.robot3.serial_wrapper.SerialWrapper` handles automatic reconnection to the serial port if the connection is lost and impleents 3 retries on any serial operation before raising a `BoardDisconnectionError`.