Using Cynthion USER I/O with Facedancer

In addition to the four USB ports Cynthion also includes the following user i/o ports:

• USER Button

• USER PMOD A & B

• USER LEDs

Apart from PMOD B, which is used for the Facedancer SoC UART and JTAG interface, all of these can be accessed from within Python Facedancer devices.

Before proceeding, please ensure you have completed all steps in the Getting Started with Cynthion and Using Cynthion with Facedancer sections.

Requirements

• A Cynthion running the Facedancer bitstream.

• Two USB Cables.

Using Cynthion APIs

To access Cynthion USER i/o using Python you first need an instance of the Cynthion object, which can be created as follows:

from cynthion import Cynthion
c = Cynthion()

Once you have a Cynthion instance you will be able to access USER i/o using the leds and gpio APIs.

For example, open a new Python shell:

$ python

Python 3.11.11 (main, Feb 12 2025, 14:40:14) [Clang 16.0.0 (clang-1600.0.26.6)] on darwin
Type "help", "copyright", "credits" or "license" for more information.
>>>

First obtain a Cynthion instance:

>>> from cynthion import Cynthion
>>> c = Cynthion()

Turn on USER Led5:

>>> c.leds[5].on()

Turn off USER Led5:

>>> c.leds[5].off()

Toggle USER Led4:

>>> c.leds[4].toggle()

Get the USER Button:

>>> user_button = c.gpio.get_pin("USER")

Wait for the USER Button to be pressed: (hit enter twice to start)

>>> while user_button.read() == False: pass
...

Using USER Button and Leds with Facedancer

Lets modify the Facedancer rubber-ducky example to give us a bit more information and control using Cynthion USER i/o. We’ll subclass a Facedancer device and add some calls to the USER i/o APIs in response to host requests and device responses.

Create a new Python file called facedancer-user-io.py and add the following content:

facedancer-user-io.py

import asyncio
import logging

from facedancer                   import main, errors
from facedancer.devices.keyboard  import USBKeyboardDevice

from cynthion                     import Cynthion

# Subclass USBKeyboardDevice
class MyKeyboardDevice(USBKeyboardDevice):
    def __post_init__(self):
        super().__post_init__()

        # Get a Cynthion instance.
        cynthion = Cynthion()

        # Get USER Leds
        self.leds = cynthion.leds

        # Make sure all USER Leds are off
        [led.off() for led in self.leds.values()]

        # Get USER Button
        self.user_button = cynthion.gpio.get_pin("USER")

    def handle_bus_reset(self):
        # Strobe USER Led0 every time we see a bus reset
        self.leds[0].strobe(duration=0.1)
        super().handle_bus_reset()

    def handle_request(self, request):
        # Strobe USER Led1 every time the host makes a control request
        self.leds[1].strobe(duration=0.1)
        super().handle_request(request)

    def control_send(self, endpoint_number, in_request, data, *, blocking = False):
        # Strobe USER Led2 every time the device responds to a control request
        self.leds[2].strobe(duration=0.1)
        super().control_send(endpoint_number, in_request, data, blocking=blocking)

    def handle_data_requested(self, endpoint):
        report = self._generate_hid_report()
        endpoint.send(report)

        # Strobe USER Led3 every time the host requested a HID report descriptor from the host
        if report[2] == 0:
            self.leds[3].strobe(duration=0.1)
        # Strobe USER Led4 if the report descriptor contained a scancode for the host
        else:
            self.leds[4].strobe(duration=0.1)

# Rubber-ducky control script
async def type_letters():
    # Wait for device to connect
    await asyncio.sleep(2)

    logging.info("Press the USER button to proceed.")

    # Wait until Cynthion's USER button is pressed
    while device.user_button.read() == False:
        await asyncio.sleep(0.01)

    logging.info("Typing string into target device.")

    # Type a string with the device
    await device.type_string("echo hello, facedancer\n")

    logging.info("Finished. Press the USER button again to quit.")

    # Done
    while device.user_button.read() == False:
        await asyncio.sleep(0.01)

    raise errors.EndEmulation("User quit the emulation.")

# Start emulation
device = MyKeyboardDevice()
main(device, type_letters())

Open a terminal and run:

python ./facedancer-user-io.py

If everything went well you should see prompts at various points to press the USER button to continue execution as well as the USER Leds flashiing in response to device events.

USER Pmod inputs and outputs

In addition to the USER Button and Leds, Facedancer can also make use of Cynthion USER Pmod A (USER Pmod B is used for JTAG and UART duties) to trigger or respond to external hardware. They use the same gpio APIs as the USER Button but individual pins can also be configured as inputs or outputs.

Let’s build a simple example that uses two of the USER Pmod A pins to connect a switch and a LED to Cynthion.

You will need:

• 1x SPST Switch

• 1x 1 kOhm resistor

• 1x 10 kOhm resistor

• 1x LED

• 1x Breadboard

Circuit Diagram

Breadboard Layout

Source Code

Create a new Python file called cynthion-user-pmod.py with the following content:

cynthion-user-pmod.py

import time

from cynthion import           Cynthion
from cynthion.interfaces.gpio  import PinDirection

# Get Cynthion instance
c = Cynthion()

# Get USER Pmod Pin A1 and configure it as an input
a1 = c.gpio.get_pin("A1")
a1.set_direction(PinDirection.Input)

# Get USER Pmod Pin A3 and configure it as an output
a3 = c.gpio.get_pin("A3")
a3.set_direction(PinDirection.Output)

# Continuously read the input value of Pin A1 and output it to Pin A3.
while True:
    value = a1.read()
    a3.write(value)
    time.sleep(0.1)

Open a terminal and run:

python ./cynthion-user-pmod.py

If all goes well, the LED should light up when you press the switch and turn off when you release it.