Getting Started with Cynthion

Prerequisites

To use Cynthion you will need to ensure the following software is installed:

Python v3.9, or later.

Cynthion Host Software Installation

The Cynthion host software distribution can be obtained from the Python Package Index (PyPI) or directly from source.

Note

For more information on installing Python packages from PyPI please refer to the “Installing Packages” section of the Python Packaging User Guide.

Linux

Use pip to install the Cynthion host software:

pip install cynthion

Install udev Rules

Configure your system to allow access to Cynthion for logged in users:

cynthion setup

If you’d prefer to perform this step manually, you can download and install the rules as follows:

# download udev rules
curl -O https://raw.githubusercontent.com/greatscottgadgets/cynthion/main/cynthion/python/assets/54-cynthion.rules

# install udev rules
sudo cp 54-cynthion.rules /etc/udev/rules.d

# reload udev rules
sudo udevadm control --reload

# apply udev rules to any devices that are already plugged in
sudo udevadm trigger

You can check that the rules are installed correctly with:

cynthion setup --check

macOS

Use Homebrew to install Python and libusb:

brew install python libusb

Use pip to install the Cynthion host software:

pip install cynthion
Note

The Cynthion host software uses the libusb1 Python package to communicate with the hardware. On macOS, the package does not install the native dynamic library with it, so it’s necessary to install the libusb native library through Homebrew, MacPorts or some other route.

If you are not using a Python distribution from Homebrew you may be able to direct Cynthion to the correct location by explicitly setting DYLD_FALLBACK_LIBRARY_PATH to the location of the libusb native library.

For example:
DYLD_FALLBACK_LIBRARY_PATH="/opt/homebrew/lib" cynthion info

Windows

Use pip to install the Cynthion host software:

pip install cynthion

Test Installation

Connect Hardware

Connection diagram for testing Cynthion installation.

Connect the Host computer to the Cynthion CONTROL port.
Check that the LED A power-on indicator lights up.

Test Hardware Connectivity

Open a terminal and confirm that everything is working by running:

cynthion info --force-offline

If everything is working you will see the following output:

Found Cynthion device!
    Hardware: Cynthion r1.4
    Manufacturer: Great Scott Gadgets
    Product: Cynthion Apollo Debugger
    Serial number: xxxxxxxxxxxxxxxxxxxxxxxxxx
    Vendor ID: 1d50
    Product ID: 615c
    bcdDevice: 0104
    Firmware version: v1.0.6
    USB API version: 1.1
    Flash UID: xxxxxxxxxxxxxxxx

Updating Cynthion Host Software

To update the Cynthion host software to the latest version run:

pip install --upgrade cynthion

Updating Cynthion Microcontroller Firmware and FPGA configuration flash

To upgrade the Cynthion Microcontroller firmware and FPGA configuration flash to the latest versions run:

cynthion update

You can update the Microcontroller firmware separately with:

cynthion update --mcu-firmware

You can update the FPGA configuration flash separately with:

cynthion update --bitstream