pymcuprog.serialupdi package

Submodules

pymcuprog.serialupdi.application module

Application layer for UPDI stack

class pymcuprog.serialupdi.application.UpdiApplication(serialport, baud, device=None, timeout=None)

Bases: object

Generic application layer for UPDI

Parameters:

  • serialport (str) – serial port to communicate over

  • baud (int) – baud rate to use

  • device (dict) – device information

  • timeout (int) – read timeout for serial port in seconds

enter_progmode()

Enters into NVM programming mode

in_prog_mode()

Checks whether the NVM PROG flag is up

Returns:

True if in NVM PROG, False otherwise

Return type:

bool

leave_progmode()

Disables UPDI which releases any keys enabled

read_data(address, size)

Reads a number of bytes of data from UPDI

Parameters:

  • address (int) – address to write to

  • size (int) – number of bytes to read

Returns:

data requested

Return type:

list of bytes

read_data_words(address, words)

Reads a number of words of data from UPDI

Parameters:

  • address (int) – address to write to

  • words (int) – number of words to read

Returns:

data requested

Return type:

list of bytes

read_device_info()

Reads out device information from various sources

reset(apply_reset)

Applies or releases an UPDI reset condition

Parameters:

apply_reset (bool) – True to apply, False to release

unlock()

Unlock by chip erase

Raises:

PymcuprogSerialUpdiError if an error occurs

wait_unlocked(timeout_ms)

Waits for the device to be unlocked. All devices boot up as locked until proven otherwise.

Parameters:

timeout_ms (int) – number of milliseconds to wait

Returns:

True if success, False otherwise

Return type:

bool

wait_urow_prog(timeout_ms, wait_for_high)

Waits for the device to be in user row write mode. User row is writeable on a locked device using this mechanism.

Parameters:

  • timeout_ms (int) – number of milliseconds to wait

  • wait_for_high (bool) – set True to wait for bit to go high; False to wait for low

Returns:

True if success, False otherwise

Return type:

bool

write_data(address, data)

Writes a number of bytes to memory

Parameters:

  • address (int) – address to write to

  • data (list of bytes) – data to write

write_data_words(address, data)

Writes a number of words to memory

Parameters:

  • address (int) – address to write to

  • data (list of bytes) – data to write

write_user_row_locked_device(address, data)

Writes data to the user row when the device is locked, using a key.

Parameters:

  • address (int) – address to write to

  • data (list of bytes) – data to write

Raises:

PymcuprogSerialUpdiError if an error occurs

pymcuprog.serialupdi.application.decode_sib(sib)

Turns the SIB into something readable

Parameters:

sib (str) – SIB data to decode

pymcuprog.serialupdi.constants module

UPDI protocol constants

pymcuprog.serialupdi.nvm module

NVM implementations on various UPDI device families

class pymcuprog.serialupdi.nvm.NvmUpdi(readwrite, device)

Bases: object

Base class for NVM

chip_erase()

Does a chip erase using the NVM controller

erase_eeprom()

Erase EEPROM memory only

erase_flash_page(address)

Erasing single flash page using the NVM controller

Parameters:

address (int) – Start address of page to erase

erase_user_row(address, size)

Erase User Row memory only

Parameters:

  • address (int) – Start address of user row

  • size (int) – Size of user row

write_eeprom(address, data)

Write data to EEPROM

Parameters:

  • address – address to write to

  • data – data to write

write_flash(address, data)

Writes data to flash

Parameters:

  • address – address to write to

  • data – data to write

write_fuse(address, data)

Writes one fuse value

Parameters:

  • address – address to write to

  • data – data to write

write_user_row(address, data)

Writes data to user row

Parameters:

  • address – address to write to

  • data – data to write

pymcuprog.serialupdi.nvmp0 module

NVM controller implementation for P:0.

Present on tiny0, 1, 2 and mega0 (eg: tiny817 -> mega4809)

class pymcuprog.serialupdi.nvmp0.NvmUpdiP0(readwrite, device)

Bases: NvmUpdi

Version P:0 UPDI NVM properties

NVMCMD_CHIP_ERASE = 5
NVMCMD_ERASE_EEPROM = 6
NVMCMD_ERASE_PAGE = 2
NVMCMD_ERASE_WRITE_PAGE = 3
NVMCMD_NOP = 0
NVMCMD_PAGE_BUFFER_CLR = 4
NVMCMD_WRITE_FUSE = 7
NVMCMD_WRITE_PAGE = 1
NVMCTRL_ADDR = 8
NVMCTRL_CTRLA = 0
NVMCTRL_CTRLB = 1
NVMCTRL_DATA = 6
NVMCTRL_INTCTRL = 3
NVMCTRL_INTFLAGS = 4
NVMCTRL_STATUS = 2
STATUS_EEPROM_BUSY_bp = 1
STATUS_FLASH_BUSY_bp = 0
STATUS_WRITE_ERROR_bp = 2
chip_erase()

Does a chip erase using the NVM controller

Note that on locked devices this is not possible and the ERASE KEY has to be used instead, see the unlock method

erase_eeprom()

Erase EEPROM memory only

erase_flash_page(address)

Erasing single flash page using the NVM controller

Parameters:

address (int) – Start address of page to erase

erase_user_row(address, size)

Erase User Row memory only

Parameters:

  • address (int) – Start address of user row

  • size (int) – Size of user row

execute_nvm_command(command)

Executes an NVM COMMAND on the NVM CTRL

Parameters:

command – command to execute

wait_nvm_ready(timeout_ms=100)

Waits for the NVM controller to be ready

Parameters:

timeout_ms (int, defaults to 100) – Timeout period in milliseconds

Returns:

True if ‘ready’, False if timeout occurred before ready

Return type:

bool

Raises:

PymcuprogSerialUpdiNvmError if an error condition is encountered

write_eeprom(address, data)

Write data to EEPROM

Parameters:

  • address (int) – address to write to

  • data (list of bytes) – data to write

write_flash(address, data)

Writes data to flash

Parameters:

  • address (int) – address to write to

  • data (list of bytes) – data to write

write_fuse(address, data)

Writes one fuse value

Parameters:

  • address (int) – address to write to

  • data (list of bytes) – data to write

write_nvm(address, data, use_word_access=True, nvmcommand=1)

Writes a page of data to NVM

By default the PAGE_WRITE command is used, which requires that the page is already erased. By default word access is used (required for flash)

Parameters:

  • address (int) – address to write to

  • data (list of bytes) – data to write

  • use_word_access (bool, defaults to True) – True for 16-bit writes (eg: flash)

  • nvmcommand (int, defaults to NVMCMD_PAGE_WRITE) – command to use for commit

Raises:

PymcuprogSerialUpdiNvmTimeout if a timeout occurred

Raises:

PymcuprogSerialUpdiNvmError if an error condition is encountered

write_user_row(address, data)

Writes data to user row

Parameters:

  • address (int) – address to write to

  • data (list of bytes) – data to write

pymcuprog.serialupdi.nvmp2 module

NVM controller implementation for P:2.

Present on, for example, AVR DA, DB, DD

class pymcuprog.serialupdi.nvmp2.NvmUpdiP2(readwrite, device)

Bases: NvmUpdi

Version P:2 UPDI NVM properties

NVMCMD_CHIP_ERASE = 32
NVMCMD_EEPROM_BYTE_ERASE = 24
NVMCMD_EEPROM_ERASE = 48
NVMCMD_EEPROM_ERASE_WRITE = 19
NVMCMD_EEPROM_WRITE = 18
NVMCMD_FLASH_PAGE_ERASE = 8
NVMCMD_FLASH_WRITE = 2
NVMCMD_NOCMD = 0
NVMCMD_NOOP = 1
NVMCTRL_ADDR = 8
NVMCTRL_CTRLA = 0
NVMCTRL_CTRLB = 1
NVMCTRL_DATA = 6
NVMCTRL_INTCTRL = 3
NVMCTRL_INTFLAGS = 4
NVMCTRL_STATUS = 2
STATUS_EEPROM_BUSY_bp = 1
STATUS_FLASH_BUSY_bp = 0
STATUS_WRITE_ERROR_bm = 48
STATUS_WRITE_ERROR_bp = 4
chip_erase()

Does a chip erase using the NVM controller

Note that on locked devices this it not possible and the ERASE KEY has to be used instead

erase_eeprom()

Erase EEPROM memory only

erase_flash_page(address)

Erasing single flash page using the NVM controller

Parameters:

address (int) – Start address of page to erase

erase_user_row(address, size=0)

Erase User Row memory only

Parameters:

  • address (int) – Start address of user row

  • size (int, optional, not used for this variant) – Size of user row

execute_nvm_command(command)

Executes an NVM COMMAND on the NVM CTRL

Parameters:

command – command to execute

wait_nvm_ready(timeout_ms=100)

Waits for the NVM controller to be ready

Parameters:

timeout_ms (int, defaults to 100) – Timeout period in milliseconds

Returns:

True if ‘ready’, False if timeout occurred before ready

Return type:

bool

Raises:

PymcuprogSerialUpdiNvmError if an error condition is encountered

write_eeprom(address, data)

Writes data to NVM (EEPROM)

Parameters:

  • address (int) – address to write to

  • data (list of bytes) – data to write

write_flash(address, data)

Writes data to flash

Parameters:

  • address (int) – address to write to

  • data (list of bytes) – data to write

write_fuse(address, data)

Writes one fuse value

Parameters:

  • address (int) – address to write to

  • data (list of bytes) – data to write

write_nvm(address, data, use_word_access=True)

Writes data to NVM.

This version of the NVM block has no page buffer, so words are written directly.

Parameters:

  • address (int) – address to write to

  • data (list of bytes) – data to write

  • use_word_access (bool, defaults to True) – True for 16-bit writes (eg: flash)

Raises:

PymcuprogSerialUpdiNvmTimeout if a timeout occurred

Raises:

PymcuprogSerialUpdiNvmError if an error condition is encountered

write_user_row(address, data)

Writes data to user row

Parameters:

  • address (int) – address to write to

  • data (list of bytes) – data to write

pymcuprog.serialupdi.nvmp3 module

NVM controller implementation for P:3.

Present on, for example, AVR EA

class pymcuprog.serialupdi.nvmp3.NvmUpdiP3(readwrite, device)

Bases: NvmUpdi

Version P:3 UPDI NVM properties

NVMCMD_CHIP_ERASE = 32
NVMCMD_EEPROM_ERASE = 48
NVMCMD_EEPROM_PAGE_BUFFER_CLEAR = 31
NVMCMD_EEPROM_PAGE_ERASE = 23
NVMCMD_EEPROM_PAGE_ERASE_WRITE = 21
NVMCMD_EEPROM_PAGE_WRITE = 20
NVMCMD_FLASH_PAGE_BUFFER_CLEAR = 15
NVMCMD_FLASH_PAGE_ERASE = 8
NVMCMD_FLASH_PAGE_ERASE_WRITE = 5
NVMCMD_FLASH_PAGE_WRITE = 4
NVMCMD_NOCMD = 0
NVMCMD_NOOP = 1
NVMCTRL_ADDR = 12
NVMCTRL_CTRLA = 0
NVMCTRL_CTRLB = 1
NVMCTRL_DATA = 8
NVMCTRL_INTCTRL = 4
NVMCTRL_INTFLAGS = 5
NVMCTRL_STATUS = 6
STATUS_EEPROM_BUSY_bp = 0
STATUS_FLASH_BUSY_bp = 1
STATUS_WRITE_ERROR_bm = 112
STATUS_WRITE_ERROR_bp = 4
chip_erase()

Does a chip erase using the NVM controller

Note that on locked devices this is not possible and the ERASE KEY has to be used instead, see the unlock method

erase_eeprom()

Erase EEPROM memory only

erase_flash_page(address)

Erasing single flash page using the NVM controller

Parameters:

address (int) – Start address of page to erase

erase_user_row(address, size=0)

Erase User Row memory only

Parameters:

  • address (int) – Start address of user row

  • size (int, optional, not used for this variant) – Size of user row

execute_nvm_command(command)

Executes an NVM COMMAND on the NVM CTRL

Parameters:

command – command to execute

wait_nvm_ready(timeout_ms=100)

Waits for the NVM controller to be ready

Parameters:

timeout_ms (int, defaults to 100) – Timeout period in milliseconds

Returns:

True if ‘ready’, False if timeout occurred before ready

Return type:

bool

Raises:

PymcuprogSerialUpdiNvmError if an error condition is encountered

write_eeprom(address, data)

Write data to EEPROM

Parameters:

  • address (int) – address to write to

  • data (list of bytes) – data to write

write_flash(address, data)

Writes data to flash

Parameters:

  • address (int) – address to write to

  • data (list of bytes) – data to write

write_fuse(address, data)

Writes one fuse value

Parameters:

  • address (int) – address to write to

  • data (list of bytes) – data to write

write_nvm(address, data, use_word_access, nvmcommand=4, erasebuffer_command=15)

Writes a page of data to NVM

By default the PAGE_WRITE command is used, which requires that the page is already erased. By default word access is used (required for flash)

Parameters:

  • address (int) – address to write to

  • data (list of bytes) – data to write

  • use_word_access (bool, defaults to True) – True for 16-bit writes (eg: flash)

  • nvmcommand (int, defaults to NVMCMD_PAGE_WRITE) – command to use for commit

  • erasebuffer_command (int, defaults to NVMCMD_FLASH_PAGE_BUFFER_CLEAR) – command to use for erasing the page buffer

Raises:

PymcuprogSerialUpdiNvmTimeout if a timeout occurred

Raises:

PymcuprogSerialUpdiNvmError if an error condition is encountered

write_user_row(address, data)

Writes data to user row

Parameters:

  • address (int) – address to write to

  • data (list of bytes) – data to write

pymcuprog.serialupdi.physical module

Serial driver for UPDI stack

class pymcuprog.serialupdi.physical.UpdiPhysical(port, baud=115200, timeout=None)

Bases: object

PDI physical driver using a given serial port at a given baud

initialise_serial(port, baud, timeout)

Standard serial port initialisation

Parameters:

  • port (str) – Serial port name to connect to

  • baud (int) – Baud rate in bps to use for communications

  • timeout (float) – Timeout value for serial reading. When UPDI is not enabled, attempting to read will return after this timeout period.

receive(size)

Receives a frame of a known number of chars from UPDI

Parameters:

size (int) – bytes to receive

send(command)

Sends a char array to UPDI without inter-byte delay Note that the byte will echo back

Parameters:

command (list of bytes) – command to send

send_double_break()

Sends a double break to reset the UPDI port

BREAK is actually just a slower zero frame A double break is guaranteed to push the UPDI state machine into a known state, albeit rather brutally

sib()

System information block is just a string coming back from a SIB command

pymcuprog.serialupdi.readwrite module

Read/write access provider for UPDI

class pymcuprog.serialupdi.readwrite.UpdiReadWrite(datalink)

Bases: object

Provides various forms of reads and writes for UPDI applications Makes us of the datalink provided

read_byte(address)

Read a single byte from UPDI

Parameters:

address (int) – address to read from

Returns:

value read

Return type:

byte

read_cs(address)

Read from Control/Status space

Parameters:

address (int) – address (index) to read

Returns:

value read

Return type:

byte

read_data(address, size)

Reads a number of bytes of data from UPDI

Parameters:

  • address (int) – address to write to

  • size (int) – number of bytes to read

read_data_words(address, words)

Reads a number of words of data from UPDI

Parameters:

  • address (int) – address to write to

  • words (int) – number of words to read

read_sib()

Read the SIB from UPDI

Returns:

SIB string read

Return type:

bytearray

write_byte(address, value)

Writes a single byte to UPDI

Parameters:

  • address (int) – address to write to

  • value (byte) – value to write

write_cs(address, value)

Write to Control/Status space

Parameters:

  • address (int) – address (index) to write

  • value (byte) – 8-bit value to write

write_data(address, data)

Writes a number of bytes to memory

Parameters:

  • address (int) – address to write to

  • data (list of bytes) – data to write

write_data_words(address, data)

Writes a number of words to memory

Parameters:

  • address (int) – address to write to

  • data (list of bytes) – data to write

write_key(size, key)

Write a KEY into UPDI

Parameters:

  • size (int) – size of key to send

  • key – key value

Type:

key bytearray

pymcuprog.serialupdi.timeout module

Simple timer helper for UPDI stack

class pymcuprog.serialupdi.timeout.Timeout(timeout_ms)

Bases: object

Simple timeout helper in milliseconds.

expired()

Check if the timeout has expired

Returns:

True if expired, False otherwise

Return type:

bool

Module contents