bossac-wrapper 0.1.0__tar.gz

bossac_wrapper-0.1.0/CHANGELOG.md

@@ -0,0 +1,25 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+
+## [Unreleased]
+
+## [0.1.0]
+
+_First release._
+
+### Added
+
+- `upload()`, `verify()`, `read()`, `erase()`, `reset()` and `info()` for programming devices
+  with bossac, including support for Intel HEX files and the Arduino 1200 baud touch
+- `version()` for querying the version of the bundled bossac binary
+- `BossacError`, raised whenever bossac fails
+- bossac 1.9.1, built from source and bundled with the wheels for Linux, macOS and Windows
+
+
+[Unreleased]: https://github.com/int-brain-lab/bossac-wrapper/compare/v0.1.0...HEAD
+[0.1.0]: https://github.com/int-brain-lab/bossac-wrapper/releases/tag/v0.1.0

bossac_wrapper-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,74 @@
+Contributing
+============
+
+uv
+--
+
+This project uses [uv](https://docs.astral.sh/uv/) as its package manager, for managing
+dependencies and ensuring consistent, reproducible environments. See uv's
+[installation instructions](https://docs.astral.sh/uv/getting-started/installation/) for
+details on installing it.
+
+Installing developer dependencies
+----------------------------------
+
+```shell
+uv sync --group dev
+```
+
+Building bossac
+--------------
+
+The bundled `bossac` binary isn't committed to this repository - it's built from source
+automatically whenever it's needed (e.g. by `uv sync`, `uv build`, or `uv run tox`): the first
+time, and again whenever the pinned version (`_BOSSAC_VERSION` in `bossac/__init__.py`) changes.
+The build checks that BOSSA's release tag still points to the pinned commit (`_BOSSAC_COMMIT`) -
+update both together. Building it requires `git`, `make` and a C++ compiler; on Windows, it
+has to be built in an [MSYS2](https://www.msys2.org/) MINGW64 environment.
+
+Running the test suite
+-----------------------
+
+Tests, linting, and type checking all run through [tox](https://tox.wiki/) (via the
+[tox-uv](https://github.com/tox-dev/tox-uv) plugin), across every supported Python version -
+uv provisions whichever interpreters are missing automatically:
+
+```shell
+uv run tox -p
+```
+
+Coverage report
+---------------
+
+After running the test suite, a merged coverage report is available via:
+
+```shell
+uv run coverage report
+```
+
+Checking and formatting code
+-----------------------------
+
+```shell
+uv run ruff format
+uv run ruff check --fix
+uv run mypy
+```
+
+Building the documentation
+---------------------------
+
+```shell
+uv run sphinx-build -b dirhtml docs/source docs/build
+```
+
+Building the package
+---------------------
+
+```shell
+uv build --sdist
+uv build --wheel
+```
+
+Build the wheel separately: a plain `uv build` builds it from the sdist, which doesn't contain
+the bossac binary - so bossac would be cloned and compiled again every time.

bossac_wrapper-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 International Brain Laboratory
+
+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.

bossac_wrapper-0.1.0/PKG-INFO

@@ -0,0 +1,125 @@
+Metadata-Version: 2.1
+Name: bossac-wrapper
+Version: 0.1.0
+Summary: A Python wrapper for bossac
+Keywords: bossa,bossac,sam-ba,atmel,arduino,firmware
+Author-Email: Florian Rau <bimac@users.noreply.github.com>
+License: MIT
+Project-URL: Homepage, https://github.com/int-brain-lab/bossac-wrapper/
+Project-URL: Documentation, https://int-brain-lab.github.io/bossac-wrapper/
+Project-URL: Repository, https://github.com/int-brain-lab/bossac-wrapper.git
+Project-URL: Issues, https://github.com/int-brain-lab/bossac-wrapper/issues
+Project-URL: Changelog, https://github.com/int-brain-lab/bossac-wrapper/blob/main/CHANGELOG.md
+Requires-Python: >=3.10
+Requires-Dist: pyserial>=3.5
+Description-Content-Type: text/markdown
+
+bossac-wrapper
+==============
+
+A thin Python wrapper for [bossac](https://github.com/shumatech/BOSSA) by
+[ShumaTech](http://www.shumatech.com) - a flash programmer for Atmel SAM microcontrollers with
+a SAM-BA bootloader, such as the Arduino Due, Arduino Zero and MKR boards.
+
+Installation
+------------
+
+```shell
+pip install bossac-wrapper
+```
+
+This will install bossac-wrapper along with the necessary bossac binary for your system.
+
+bossac-wrapper requires Python 3.10 or later. Supported platforms are:
+
+- Linux (x86_64, arm64)
+- macOS (Intel, Apple Silicon)
+- Windows (x86_64)
+
+Examples
+--------
+
+### Uploading a firmware file
+
+To upload a firmware file to a device, use the `upload()` function. Both Intel HEX files (`.hex`)
+and raw binaries (`.bin`) are supported.
+
+```python
+import bossac
+import logging
+
+logging.basicConfig(level=logging.INFO)
+bossac.upload('blink.hex', port='/dev/ttyACM0')
+```
+
+By default, the device is first put into its bootloader with a 1200 baud touch. Its flash is
+then erased, written and verified, and the device is reset to start the new firmware. The
+progress will be logged:
+```
+INFO:bossac:Erase flash
+INFO:bossac:Done in 0.887 seconds
+INFO:bossac:Write 10288 bytes to flash (161 pages)
+INFO:bossac:Done in 0.067 seconds
+INFO:bossac:Verify 10288 bytes of flash
+INFO:bossac:Verify successful
+INFO:bossac:Done in 0.276 seconds
+INFO:bossac:Set boot flash true
+```
+
+An Intel HEX file carries its addresses, so it is flashed at the right offset on any board. A
+binary file doesn't, so its offset has to be given - it depends on the board's bootloader, e.g.
+`0x2000` on SAMD21 boards with an Arduino-style bootloader, or 0 on the Arduino Due, whose
+bootloader is in ROM. On a board whose bootloader is in flash, an offset of 0 would overwrite it.
+
+```python
+bossac.upload('blink.bin', port='/dev/ttyACM0', offset=0x2000)  # SAMD21
+```
+
+When uploading via a USB-to-serial bridge, such as the programming port of the Arduino Due, pass
+`usb=False`:
+
+```python
+bossac.upload('blink.bin', port='/dev/ttyACM0', offset=0, usb=False)
+```
+
+### Getting device information
+
+To get the details of a device, use the `info()` function. The device must be in its bootloader,
+e.g. after double-tapping its reset button. `touch=True` puts it there, too - but that usually
+destroys the firmware, which then has to be uploaded again: the Arduino Due erases its flash, and
+SAMD boards running Arduino firmware erase its first flash row.
+
+```python
+import bossac
+
+bossac.info(port='/dev/ttyACM0')
+```
+
+For a SparkFun SAMD21 Mini, this returns:
+```python
+{
+    'device': 'ATSAMD21x18',
+    'version': 'v1.1 [Arduino:XYZ] Feb 20 2019 10:43:51',
+    'address': 0,
+    'pages': 4096,
+    'page_size': 64,
+    'total_size': 262144,
+    'planes': 1,
+    'lock_regions': 16,
+    'locked': [],
+    'security': False,
+    'boot_flash': None,
+    'brownout_detection': True,
+    'brownout_reset': True,
+}
+```
+
+Full Documentation
+------------------
+
+The full API documentation is available [here](https://int-brain-lab.github.io/bossac-wrapper).
+
+![License](https://img.shields.io/github/license/int-brain-lab/bossac-wrapper)
+[![Coverage](https://img.shields.io/coverallsCoverage/github/int-brain-lab/bossac-wrapper)](https://coveralls.io/github/int-brain-lab/bossac-wrapper)
+[![CI](https://github.com/int-brain-lab/bossac-wrapper/actions/workflows/testing.yaml/badge.svg)](https://github.com/int-brain-lab/bossac-wrapper/actions)
+[![PyPI](https://img.shields.io/pypi/v/bossac-wrapper)](https://pypi.org/project/bossac-wrapper/)

bossac_wrapper-0.1.0/README.md

@@ -0,0 +1,109 @@
+bossac-wrapper
+==============
+
+A thin Python wrapper for [bossac](https://github.com/shumatech/BOSSA) by
+[ShumaTech](http://www.shumatech.com) - a flash programmer for Atmel SAM microcontrollers with
+a SAM-BA bootloader, such as the Arduino Due, Arduino Zero and MKR boards.
+
+Installation
+------------
+
+```shell
+pip install bossac-wrapper
+```
+
+This will install bossac-wrapper along with the necessary bossac binary for your system.
+
+bossac-wrapper requires Python 3.10 or later. Supported platforms are:
+
+- Linux (x86_64, arm64)
+- macOS (Intel, Apple Silicon)
+- Windows (x86_64)
+
+Examples
+--------
+
+### Uploading a firmware file
+
+To upload a firmware file to a device, use the `upload()` function. Both Intel HEX files (`.hex`)
+and raw binaries (`.bin`) are supported.
+
+```python
+import bossac
+import logging
+
+logging.basicConfig(level=logging.INFO)
+bossac.upload('blink.hex', port='/dev/ttyACM0')
+```
+
+By default, the device is first put into its bootloader with a 1200 baud touch. Its flash is
+then erased, written and verified, and the device is reset to start the new firmware. The
+progress will be logged:
+```
+INFO:bossac:Erase flash
+INFO:bossac:Done in 0.887 seconds
+INFO:bossac:Write 10288 bytes to flash (161 pages)
+INFO:bossac:Done in 0.067 seconds
+INFO:bossac:Verify 10288 bytes of flash
+INFO:bossac:Verify successful
+INFO:bossac:Done in 0.276 seconds
+INFO:bossac:Set boot flash true
+```
+
+An Intel HEX file carries its addresses, so it is flashed at the right offset on any board. A
+binary file doesn't, so its offset has to be given - it depends on the board's bootloader, e.g.
+`0x2000` on SAMD21 boards with an Arduino-style bootloader, or 0 on the Arduino Due, whose
+bootloader is in ROM. On a board whose bootloader is in flash, an offset of 0 would overwrite it.
+
+```python
+bossac.upload('blink.bin', port='/dev/ttyACM0', offset=0x2000)  # SAMD21
+```
+
+When uploading via a USB-to-serial bridge, such as the programming port of the Arduino Due, pass
+`usb=False`:
+
+```python
+bossac.upload('blink.bin', port='/dev/ttyACM0', offset=0, usb=False)
+```
+
+### Getting device information
+
+To get the details of a device, use the `info()` function. The device must be in its bootloader,
+e.g. after double-tapping its reset button. `touch=True` puts it there, too - but that usually
+destroys the firmware, which then has to be uploaded again: the Arduino Due erases its flash, and
+SAMD boards running Arduino firmware erase its first flash row.
+
+```python
+import bossac
+
+bossac.info(port='/dev/ttyACM0')
+```
+
+For a SparkFun SAMD21 Mini, this returns:
+```python
+{
+    'device': 'ATSAMD21x18',
+    'version': 'v1.1 [Arduino:XYZ] Feb 20 2019 10:43:51',
+    'address': 0,
+    'pages': 4096,
+    'page_size': 64,
+    'total_size': 262144,
+    'planes': 1,
+    'lock_regions': 16,
+    'locked': [],
+    'security': False,
+    'boot_flash': None,
+    'brownout_detection': True,
+    'brownout_reset': True,
+}
+```
+
+Full Documentation
+------------------
+
+The full API documentation is available [here](https://int-brain-lab.github.io/bossac-wrapper).
+
+![License](https://img.shields.io/github/license/int-brain-lab/bossac-wrapper)
+[![Coverage](https://img.shields.io/coverallsCoverage/github/int-brain-lab/bossac-wrapper)](https://coveralls.io/github/int-brain-lab/bossac-wrapper)
+[![CI](https://github.com/int-brain-lab/bossac-wrapper/actions/workflows/testing.yaml/badge.svg)](https://github.com/int-brain-lab/bossac-wrapper/actions)
+[![PyPI](https://img.shields.io/pypi/v/bossac-wrapper)](https://pypi.org/project/bossac-wrapper/)