Main Scaffold API

This page documents the main classes and methods of the Scaffold Python API.

Manipulating the attributes of the different modules of a Scaffold instance will read or write in the FPGA registers. Some registers may be cached by the Python API, so reading them does not require any communication with the board and thus can be fast.

class scaffold.Scaffold(dev: str | None = None, init_ios: bool = False, sn: str | None = None)

This class connects to a Scaffold board and provides access to all the device parameters and peripherals.

Variables:

uarts – list of scaffold.UART instance managing UART peripherals.
i2cs – list of scaffold.I2C instance managing I2C peripherals.
iso7816 – scaffold.ISO7816 instance managing the ISO7816 peripheral.
pgens – list of four scaffold.PulseGenerator instance managing the FPGA pulse generators.
power – scaffold.Power instance, enabling control of the power supplies of DUT and platform sockets.
leds – scaffold.LEDs instance, managing LEDs brightness and lighting mode.
[a0,a1,a2,a3,b0,b1,c0,c1,d0,d1,d2,d3,d4,d5] – scaffold.Signal instances for connecting and controlling the corresponding I/Os of the board.

__init__(dev: str | None = None, init_ios: bool = False, sn: str | None = None)

Create Scaffold API instance.

Parameters:

dev – If specified, connect to the hardware Scaffold board using the given serial device. If None, tries to find automatically the device by scanning USB description strings.
init_ios – True to enable I/Os peripherals initialization. Doing so will set all I/Os to a default state, but it may generate pulses on the I/Os. When set to False, I/Os connections are unchanged during initialization and keep the configuration set by previous sessions.
sn – If dev is not specified, automatic detection must find a board with the given serial number. This is an interesting feature when multiple Scaffold boards are connected to the same computer.

class scaffold.Signal(parent, path)

Base class for all connectable signals in Scaffold. Every Signal instance has a Scaffold board parent instance which is used to electrically configure the hardware board when two Signal are connected together.

__init__(parent, path)

Parameters:

parent – Scaffold instance which the signal belongs to.
path – Signal path string. Uniquely identifies a Scaffold board internal signal. For instance ‘/dev/uart0/tx’.

__lshift__(other)

Feed the current signal with another signal.

Parameters:: other – Another Signal instance. The other signal must belong to the same Scaffold instance.

__str__()

Returns:: Signal path. For instance ‘/dev/uart0/tx’.

property name: Signal name (last element of the path). For instance ‘tx’. Read-only.

property parent: Parent Scaffold board instance. Read-only.

property path: Signal path. For instance ‘/dev/uart0/tx’. Read-only.

class scaffold.IO(parent, path, index, pullable=False)

Board I/O.

clear_event()

Clear event register.

Warning:: If an event is received during this call, it may be cleared without being took into account.

property event

I/O event register.

Getter:: Returns 1 if an event has been detected on this input, 0 otherwise.
Setter:: Writing 0 to clears the event flag. Writing 1 has no effect.

property mode

I/O mode. Default is AUTO, but this can be overriden for special applications.

Type:: IOMode

property pull

Pull resistor mode. Can only be written if the I/O supports this feature.

Type:: Pull

property value

Current IO logical state.

Getter:: Senses the input pin of the board and return either 0 or 1.
Setter:: Sets the output to 0, 1 or high-impedance state (None). This will disconnect the I/O from any already connected internal peripheral. Same effect can be achieved using << operator.

class scaffold.IOMode(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)

AUTO = 0

OPEN_DRAIN = 1

PUSH_ONLY = 2

class scaffold.Pull(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)

DOWN = 1

NONE = 0

UP = 3

class scaffold.UARTParity(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)

Possible parity modes for UART peripherals.

EVEN = 2

NONE = 0

ODD = 1

class scaffold.UART(parent, index)

UART module of Scaffold.

property baudrate

Target UART baudrate.

Getter:: Returns current baudrate, or None if no baudrate has been previously set during current session.
Setter:: Set target baudrate. If baudrate cannot be reached within 1% accuracy, a RuntimeError is thrown. Reading the baudrate attribute after setting it will return the real effective baudrate.

flush(): Discard all the received bytes in the FIFO.

property parity

Parity mode. Disabled by default.

Type:: UARTParity

receive(n=1): Receive n bytes from the UART. This function blocks until all bytes have been received or the timeout expires and a TimeoutError is thrown.

reset(): Reset the UART to a default configuration: 9600 bps, no parity, one stop bit, trigger disabled.

transmit(data: bytes, trigger: bool = False)

Transmit data using the UART.

Parameters:

data – Data to be transmitted.
trigger – True or 1 to enable trigger on last byte, False or 0 to disable trigger.

class scaffold.ISO7816(parent)

ISO7816 peripheral of Scaffold. Does not provide convention or protocol management. See scaffold.iso7816.Smartcard for more features.

property clock_frequency

Target ISO7816 clock frequency. According to ISO7816-3 specification, minimum frequency is 1 Mhz and maximum frequency is 5 MHz. Scaffold hardware allows going up to 50 Mhz and down to 195312.5 Hz (although this may not work with the smartcard).

Getter:: Returns current clock frequency, or None if it has not been set previously.
Setter:: Set clock frequency. If requested frequency cannot be reached within 1% accuracy, a RuntimeError is thrown. Reading this attribute after setting it will return the real effective clock frequency.

property empty: True if reception FIFO is empty.

property etu: ISO7816 ETU parameter. Value must be in range [1, 2^11-1]. Default ETU is 372.

flush(): Discard all the received bytes in the FIFO.

property parity_mode: Parity mode. Standard is Even parity, but it can be changed to odd or forced to a fixed value for testing purposes. :type: ISO7816ParityMode

receive(n=1, timeout=None)

Receive bytes. This function blocks until all bytes have been received or the timeout expires and a TimeoutError is thrown.

Parameters:: n – Number of bytes to be read.

reset_config(): Reset ISO7816 peripheral to its default configuration.

transmit(data: bytes, trigger: bool = False)

Transmit data.

Parameters:

data – Data to be transmitted.
trigger – Enable trigger on the last transmitted byte.

property trigger_long

Enable or disable long trigger (set on transmission, cleared on reception). When changing this value, wait until transmission buffer is empty.

Type:: bool

property trigger_rx: Enable or disable trigger upon reception. :type: bool

property trigger_tx: Enable or disable trigger upon transmission. :type: bool

class scaffold.I2C(parent, index)

I2C module of Scaffold.

property clock_stretching

Enable or disable clock stretching support. When clock stretching is enabled, the I2C slave may hold SCL low during a transaction. In this mode, an external pull-up resistor on SCL is required. When clock stretching is disabled, SCL is always controlled by the master and the pull-up resistor is not required.

Type:: bool or int.

flush(): Discards all bytes in the transmission/reception FIFO.

property frequency

Target I2C clock frequency.

Getter:: Returns current frequency.
Setter:: Set target frequency. Effective frequency may be different if target cannot be reached accurately.

raw_transaction(data, read_size, trigger=None)

Executes an I2C transaction. This is a low-level function which does not manage I2C addressing nor read/write mode (those shall already be defined in data parameter).

Parameters:

data (bytes) – Transmitted bytes. First byte is usually the address of the slave and the R/W bit. If the R/W bit is 0 (write), this parameter shall then contain the bytes to be transmitted, and read_size shall be zero.
read_size (int) – Number of bytes to be expected from the slave. 0 in case of a write transaction.
trigger (int or str.) – Trigger configuration. If int and value is 1, trigger is asserted when the transaction starts. If str, it may contain the letter ‘a’ and/or ‘b’, where ‘a’ asserts trigger on transaction start and ‘b’ on transaction end.

Raises:

I2CNackError – If a NACK is received during the transaction.

read(size, address=None, trigger=None)

Perform an I2C read transaction.

Parameters:: address (int or None) – Slave device address. If None, self.address is used by default. If defined and addressing mode is 7 bits, LSB must be 0 (this is the R/W bit). If defined and addressing mode is 10 bits, bit 8 must be 0.
Returns:: Bytes from the slave.
Raises:: I2CNackError – If a NACK is received during the transaction.

reset_config(): Reset the I2C peripheral to a default configuration.

write(data, address=None, trigger=None)

Perform an I2C write transaction.

Parameters:: address (int or None) – Slave device address. If None, self.address is used by default. If defined and addressing mode is 7 bits, LSB must be 0 (this is the R/W bit). If defined and addressing mode is 10 bits, bit 8 must be 0.
Raises:: I2CNackError – If a NACK is received during the transaction.

class scaffold.SPI(parent, index)

SPI peripheral of Scaffold.

append(data: int | bytes)

Append data to be returned by the peripheral when configured as a slave.

Warning

Appended data is stored in an internal FIFO memory of the SPI peripheral. Size is limited to 512 bytes, any write beyond that limit is discarded without any warning.

Parameters:: data – Byte or bytes to be appended.

clear(): Clear the FIFO memory of the data to be returned by the peripheral when configured as a slave.

property frequency

Target SPI clock frequency.

Getter:: Returns current frequency.
Setter:: Set target frequency. Effective frequency may be different if target cannot be reached accurately.
Type:: float

property mode: SPIMode: SPI mode

property phase: Clock phase. 0 or 1.

property polarity: Clock polarity. 0 or 1.

read_data_buffer(n)

Read n bytes from the internal data buffer.

Parameters:: n (int) – In [1, 4]
Returns:: int

transmit(value: int, size: int = 8, trigger=False, read=True)

Performs a SPI transaction to transmit a value and receive data. If a transmission is still pending, this methods waits for the SPI peripheral to be ready.

Parameters:

value – Value to be transmitted. Less significant bit is transmitted last.
size – Number of bits to be transmitted. Minimum is 1, maximum is 32.
trigger (bool or int.) – 1 or True to enable trigger upon SPI transmission.
read – Set 0 or False to disable received value readout (the method will return None). Default is True, but disabling it will make this command faster if the returned value can be discarded.

Returns:

Received value.

Return type:

int

class scaffold.PulseGenerator(parent, path, base)

Pulse generator module of Scaffold. Usually abreviated as pgen.

property count

Number of pulses to be generated. Minimum value is 1. Maximum value is 2^16.

Type:: int

property count_max

Returns:: Maximum possible pulse count.

property count_min

Returns:: Minimum possible pulse count.

property delay

Delay before pulse, in seconds.

Type:: float

property delay_max

Returns:: Maximum possible delay.

property delay_min

Returns:: Minimum possible delay.

fire(): Manually trigger the pulse generation.

property interval

Delay between pulses, in seconds.

Type:: float

property interval_max

Returns:: Maximum possible interval.

property interval_min

Returns:: Minimum possible interval.

property polarity

Pulse polarity. If 0, output is low when idle, and high during pulses. When 1, output is high when idle, and low during pulses.

Type:: int

wait_ready()

Wait while the pulse generator is busy.

This uses the polling mechanism on the ready bit in the status register. It can be used to block next commands and synchronize their execution to the end of the pulse.

property width

Pulse width, in seconds.

Type:: float

property width_max

Returns:: Maximum possible pulse width.

property width_min

Returns:: Minimum possible pulse width.

class scaffold.Clock(parent, index)

Clock generator module. This peripheral allows generating a clock derived from the FPGA system clock using a clock divisor. A second clock can be generated and enabled during a short period of time to override the first clock, generating clock glitches.

property frequency

Base clock frequency, in Hertz. Only divisors of the system frequency can be set: 50 MHz, 25 MHz, 16.66 MHz, 12.5 MHz…

Type:: float

property glitch_count

Number of fast clock edges to be injected when glitching. Maximum value is 255.

Type:: int.

property glitch_frequency

Glitch clock frequency, in Hertz. Only divisors of the system frequency can be set: 50 MHz, 25 MHz, 16.66 MHz, 12.5 MHz…

Type:: float

class scaffold.Chain(parent, index, size)

Chain trigger module.

rearm(): Reset the chain trigger to initial state.

class scaffold.LEDs(parent)

LEDs module of Scaffold.

property brightness

LEDs brightness. 0 is the minimum. 1 is the maximum.

Type:: float

property disabled: If set to True, LEDs driver outputs are all disabled.

property override: If set to True, LEDs state is the value of the leds_n registers.

reset(): Set module registers to default values.

class scaffold.Power(parent)

Controls the platform and DUT sockets power supplies.

property all: All power-supplies state. int. Bit 0 corresponds to the DUT power supply. Bit 1 corresponds to the platform power-supply. When a bit is set to 1, the corresponding power supply is enabled. This attribute can be used to control both power supplies simultaneously.

property dut: DUT power-supply state. int.

property platform: Platform power-supply state. int.

restart_all(toff=0.05, ton=0)

Power-cycle both DUT and platform sockets.

Parameters:

toff (float) – Time to wait in seconds between power-off and power-on.
ton (float) – Time to wait in seconds after power-on.

restart_dut(toff=0.05, ton=0)

Power-cycle the DUT socket.

Parameters:

toff (float) – Time to wait in seconds between power-off and power-on.
ton (float) – Time to wait in seconds after power-on.

restart_platform(toff=0.05, ton=0)

Power-cycle the platform socket.

Parameters:

toff (float) – Time to wait in seconds between power-off and power-on.
ton (float) – Time to wait in seconds after power-on.