pymcuprog

https://microchip-pic-avr-tools.github.io/pymcuprog
Admin
pymcuprog is a utility for programming various Microchip MCU devices using Microchip CMSIS-DAP based...
Tokens:50,596
Snippets:259
Trust Score:9.7
Update:3 months ago
Show doc for...
Tokens:
Raw
### start_session(_sessionconfig_, _user_interaction_callback =None_)

Source: https://microchip-pic-avr-tools.github.io/pymcuprog/pymcuprog.html

Starts a programming session, initializing the tool and device model.

```APIDOC
## start_session(_sessionconfig_ , _user_interaction_callback =None_)

### Description
Start a programming session.
This function will build the device model stack and initialize the tool for a programming session. If a session is already started calling start_session will do an end_session and start a new session from scratch.
Note connect_to_tool must have been called before start_session is called. If not an exception will be thrown.

### Parameters
* **sessionconfig** (_object_) – SessionConfig object wrapping the parameters configuring the session
* **user_interaction_callback** (_function_) – Callback to be called when user interaction is required, for example when doing UPDI high-voltage activation with user target power toggle. This function could ask the user to toggle power and halt execution waiting for the user to respond (this is default behavior if the callback is None), or if the user is another script it could toggle power automatically and then return.

### Raises
* **PymcuprogSessionConfigError** – if starting the session failed due to incorrectly configured session
* **PymcuprogToolConnectionError** – if not connected to any tool (connect_to_tool not run)
* **PymcuprogDeviceLockedError** – if unable to start the session due to the device being locked
* **PymcuprogNotSupportedError** – if configured device is not supported
```

--------------------------------

### Avr32Device Methods

Source: https://microchip-pic-avr-tools.github.io/pymcuprog/pymcuprog.html

Methods for interacting with AVR32 devices, including physical activation and programming session setup.

```APIDOC
## Avr32Device Methods

### Description
Provides methods for controlling and interacting with AVR32 target devices.

### Methods
- `activate_physical()`: Activates the physical connection to the device.
- `deactivate_physical()`: Deactivates the physical connection to the device.
- `setup_prog_session()`: Sets up a programming session for the target device.
```

--------------------------------

### NvmAccessProvider Methods

Source: https://microchip-pic-avr-tools.github.io/pymcuprog/pymcuprog.html

Methods for managing the NVM access session, including holding and releasing the target in reset, starting, and stopping the session.

```APIDOC
## NvmAccessProvider Methods

### hold_in_reset()

#### Description
Hold target in reset.

### release_from_reset()

#### Description
Release target from reset.

### start(user_interaction_callback = None)

#### Description
Start (activate) session.

#### Parameters
* **user_interaction_callback** (function) - Optional - Callback to be called when user interaction is required, for example when doing UPDI high-voltage activation with user target power toggle. This function could ask the user to toggle power and halt execution waiting for the user to respond (this is default behavior if the callback is None), or if the user is another script it could toggle power automatically and then return.

### stop()

#### Description
Stop (deactivate) session.
```

--------------------------------

### Python MCU Programmer Library Usage

Source: https://microchip-pic-avr-tools.github.io/pymcuprog/index.html

Example of setting up logging, configuring a session, and interacting with the pymcuprog backend to read a device ID. This snippet demonstrates the basic workflow for using pymcuprog as a library.

```python
# Setup logging - pymcuprog uses the Python logging module
import logging
logging.basicConfig(format="%(levelname)s: %(message)s", level=logging.WARNING)

# Configure the session:
from pymcuprog.backend import SessionConfig
sessionconfig = SessionConfig("atmega4808")

# Instantiate USB transport (only 1 tool connected)
from pymcuprog.toolconnection import ToolUsbHidConnection
transport = ToolUsbHidConnection()

# Instantiate backend, connect to tool using transport, start session using sessionconfig
#
# The Backend constructor arguments `transport' and `sessionconfig' are optional,
# setting them will cause backend.connect_to_tool() and backend.start_session() respectively
# to be called during construction. Connection and session will be automatically
# torn down when backend object goes out of scope at end of with-block.
#
from pymcuprog.backend import Backend
with Backend(transport, sessionconfig) as backend:
    # Read the target device_id
    device_id = backend.read_device_id()
    print("Device ID is {0:06X}".format(int.from_bytes(device_id, byteorder="little")))

```

--------------------------------

### Avr32Device Class

Source: https://microchip-pic-avr-tools.github.io/pymcuprog/pymcuprog.html

Provides a generic wrapper for AVR32 devices, mapping to the AVR32 protocol. It allows for activation/deactivation of the physical interface and setup of programming sessions.

```APIDOC
## Class: Avr32Device

### Description
Generic AVR32 device wrapper that maps to the avr32 protocol.

### Methods
#### activate_physical()
Activate the physical interface.

#### deactivate_physical()
Deactivate the physical interface.

#### setup_prog_session(interface='jtag')
Setup a programming session on AVR32.

*   **Parameters**:
    *   `interface` (string) - jtag or awire
```

--------------------------------

### XMEGA AVR Target Methods

Source: https://microchip-pic-avr-tools.github.io/pymcuprog/pymcuprog.html

Implements XMEGA (PDI) functionality of the AVR8 protocol, including configuration and session setup.

```APIDOC
## XMEGA AVR Target Methods

### `pymcuprog.avr8target.XmegaAvrTarget.setup_config(device_info)`

#### Description
Sets up the device configuration for a XMEGA AVR device.

#### Parameters
* **device_info** – Target device information as returned by deviceinfo.deviceinfo.getdeviceinfo

### `pymcuprog.avr8target.XmegaAvrTarget.setup_debug_session()`

#### Description
Sets up a debugging session on an XMEGA AVR.

### `pymcuprog.avr8target.XmegaAvrTarget.setup_prog_session(interface, khz)`

#### Description
Sets up a programming session for a XMEGA AVR device.

#### Parameters
* **interface** – Physical interface to use. Defaults to `pyedbglib.protocols.avr8protocol.Avr8Protocol.AVR8_PHY_INTF_PDI`.
* **khz** – Clock speed in kiloHertz / baud in kbps. Defaults to 4000.

```

--------------------------------

### Programmer API Functions

Source: https://microchip-pic-avr-tools.github.io/pymcuprog/index.html

Functions for programming microcontrollers, including memory operations and device setup.

```APIDOC
## Programmer.erase()
### Description
Erases the target device's memory.
### Method
N/A (Method call)
### Endpoint
N/A
### Parameters
None
### Request Example
```python
Programmer.erase()
```
### Response
None specified.
```

```APIDOC
## Programmer.get_device_memory_info()
### Description
Retrieves information about the target device's memory layout.
### Method
N/A (Method call)
### Endpoint
N/A
### Parameters
None
### Request Example
```python
memory_info = Programmer.get_device_memory_info()
```
### Response
Returns a dictionary with memory information.
```

```APIDOC
## Programmer.get_device_model()
### Description
Retrieves the model name of the target device.
### Method
N/A (Method call)
### Endpoint
N/A
### Parameters
None
### Request Example
```python
device_model = Programmer.get_device_model()
```
### Response
Returns the device model name.
```

```APIDOC
## Programmer.hold_in_reset()
### Description
Places the target device in a reset state.
### Method
N/A (Method call)
### Endpoint
N/A
### Parameters
None
### Request Example
```python
Programmer.hold_in_reset()
```
### Response
None specified.
```

```APIDOC
## Programmer.load_device(device_name)
### Description
Loads the configuration for a specific device.
### Method
N/A (Method call)
### Endpoint
N/A
### Parameters
- **device_name** (str) - The name of the device to load.
### Request Example
```python
Programmer.load_device('ATSAMD21J18A')
```
### Response
None specified.
```

```APIDOC
## Programmer.read_device_id()
### Description
Reads the device ID of the target.
### Method
N/A (Method call)
### Endpoint
N/A
### Parameters
None
### Request Example
```python
device_id = Programmer.read_device_id()
```
### Response
Returns the device ID.
```

```APIDOC
## Programmer.read_memory(address, length)
### Description
Reads a specified number of bytes from the target device's memory.
### Method
N/A (Method call)
### Endpoint
N/A
### Parameters
- **address** (int) - The starting memory address.
- **length** (int) - The number of bytes to read.
### Request Example
```python
memory_data = Programmer.read_memory(0x1000, 64)
```
### Response
Returns the read memory data as bytes.
```

```APIDOC
## Programmer.release_from_reset()
### Description
Releases the target device from a reset state.
### Method
N/A (Method call)
### Endpoint
N/A
### Parameters
None
### Request Example
```python
Programmer.release_from_reset()
```
### Response
None specified.
```

```APIDOC
## Programmer.set_options(options)
### Description
Sets various options for the programmer.
### Method
N/A (Method call)
### Endpoint
N/A
### Parameters
- **options** (dict) - A dictionary of options to set.
### Request Example
```python
Programmer.set_options({'frequency': 1000000})
```
### Response
None specified.
```

```APIDOC
## Programmer.setup_device(device_name)
### Description
Sets up the programmer for a specific device.
### Method
N/A (Method call)
### Endpoint
N/A
### Parameters
- **device_name** (str) - The name of the device to set up for.
### Request Example
```python
Programmer.setup_device('ATSAMD21J18A')
```
### Response
None specified.
```

```APIDOC
## Programmer.start()
### Description
Starts the programming process.
### Method
N/A (Method call)
### Endpoint
N/A
### Parameters
None
### Request Example
```python
Programmer.start()
```
### Response
None specified.
```

```APIDOC
## Programmer.stop()
### Description
Stops the programming process.
### Method
N/A (Method call)
### Endpoint
N/A
### Parameters
None
### Request Example
```python
Programmer.stop()
```
### Response
None specified.
```

```APIDOC
## Programmer.verify_memory(address, data)
### Description
Verifies that the target device's memory matches the provided data.
### Method
N/A (Method call)
### Endpoint
N/A
### Parameters
- **address** (int) - The starting memory address for verification.
- **data** (bytes) - The expected data.
### Request Example
```python
Programmer.verify_memory(0x1000, b'\x00\x01\x02')
```
### Response
None specified.
```

```APIDOC
## Programmer.write_memory(address, data)
### Description
Writes data to the target device's memory.
### Method
N/A (Method call)
### Endpoint
N/A
### Parameters
- **address** (int) - The starting memory address.
- **data** (bytes) - The data to write.
### Request Example
```python
Programmer.write_memory(0x1000, b'\x00\x01\x02')
```
### Response
None specified.
```

--------------------------------

### TinyAvrTarget Methods

Source: https://microchip-pic-avr-tools.github.io/pymcuprog/index.html

Methods for setting up debug sessions for Tiny AVR devices.

```APIDOC
## TinyAvrTarget Methods

### Description
Methods for setting up debug sessions for Tiny AVR devices.

### Methods
- `setup_debug_session()`: Sets up a debug session for the target device.
```

--------------------------------

### XmegaAvrTarget Methods

Source: https://microchip-pic-avr-tools.github.io/pymcuprog/index.html

Methods for setting up configuration, debug sessions, and programming sessions for XMEGA AVR devices.

```APIDOC
## XmegaAvrTarget Methods

### Description
Methods for configuring and initiating debug or programming sessions for XMEGA AVR devices.

### Methods
- `setup_config()`: Sets up the configuration for the target device.
- `setup_debug_session()`: Sets up a debug session for the target device.
- `setup_prog_session()`: Sets up a programming session for the target device.
```

--------------------------------

### pymcuprog.hexfileutils.write_memory_to_hex

Source: https://microchip-pic-avr-tools.github.io/pymcuprog/pymcuprog.html

Writes a single memory segment to a hex file with data starting at a specified relative offset.

```APIDOC
## pymcuprog.hexfileutils.write_memory_to_hex

### Description
Write one memory segment to a hex file with data starting at relative offset given by offset parameter.

### Parameters
#### Path Parameters
* **filename** (string) - Required - Name/path of hex file to write to
* **memory_segment** (namedtuple) - Required - namedtuple with two fields: data and memory_info. data contains a byte array of raw data bytes and memory_info is a dictionary with memory information as defined in deviceinfo.deviceinfo.DeviceMemoryInfo).
* **offset** (integer) - Required - Relative offset for the data within the memory segment
```

--------------------------------

### erase_user_row

Source: https://microchip-pic-avr-tools.github.io/pymcuprog/pymcuprog.serialupdi.html

Erases User Row memory starting at the specified address. The size parameter is not used for this variant.

```APIDOC
## erase_user_row

### Description
Erases User Row memory.

### Method
N/A (Method of NvmUpdiP3 class)

### Endpoint
N/A

### Parameters
#### Path Parameters
- **address** (int) - Required - Start address of user row
- **size** (int) - Optional, not used - Size of user row

### Request Example
N/A

### Response
N/A
```

--------------------------------

### wait_nvm_ready

Source: https://microchip-pic-avr-tools.github.io/pymcuprog/pymcuprog.serialupdi.html

Waits for the NVM controller to become ready, with an optional timeout.

```APIDOC
## wait_nvm_ready

### Description
Waits for the NVM controller to be ready.

### Method
N/A (Method of NvmUpdiP3 class)

### Endpoint
N/A

### Parameters
#### Path Parameters
- **timeout_ms** (int) - Optional, defaults to 100 - Timeout period in milliseconds

### Request Example
N/A

### Response
#### Success Response
- **True** (bool) - If the NVM controller is ready within the timeout period.
- **False** (bool) - If the timeout occurred before the NVM controller became ready.

### Raises
PymcuprogSerialUpdiNvmError - If an error condition is encountered.
```

--------------------------------

### AvrDebugger API Functions (alpha)

Source: https://microchip-pic-avr-tools.github.io/pymcuprog/index.html

Functions for debugging AVR microcontrollers, including session setup, memory access, and control flow.

```APIDOC
## AvrDebugger.attach()
### Description
Attaches to a running AVR device for debugging.
### Method
N/A (Method call)
### Endpoint
N/A
### Parameters
None
### Request Example
```python
AvrDebugger.attach()
```
### Response
None specified.
```

```APIDOC
## AvrDebugger.detach()
### Description
Detaches the debugger from the AVR device.
### Method
N/A (Method call)
### Endpoint
N/A
### Parameters
None
### Request Example
```python
AvrDebugger.detach()
```
### Response
None specified.
```

```APIDOC
## AvrDebugger.eeprom_read(address, length)
### Description
Reads data from the EEPROM of the AVR device.
### Method
N/A (Method call)
### Endpoint
N/A
### Parameters
- **address** (int) - The starting EEPROM address.
- **length** (int) - The number of bytes to read.
### Request Example
```python
eeprom_data = AvrDebugger.eeprom_read(0, 16)
```
### Response
Returns the read EEPROM data.
```

```APIDOC
## AvrDebugger.eeprom_write(address, data)
### Description
Writes data to the EEPROM of the AVR device.
### Method
N/A (Method call)
### Endpoint
N/A
### Parameters
- **address** (int) - The starting EEPROM address.
- **data** (bytes) - The data to write.
### Request Example
```python
AvrDebugger.eeprom_write(0, b'\x01\x02\x03')
```
### Response
None specified.
```

```APIDOC
## AvrDebugger.flash_read(address, length)
### Description
Reads data from the flash memory of the AVR device.
### Method
N/A (Method call)
### Endpoint
N/A
### Parameters
- **address** (int) - The starting flash address.
- **length** (int) - The number of bytes to read.
### Request Example
```python
flash_data = AvrDebugger.flash_read(0, 256)
```
### Response
Returns the read flash data.
```

```APIDOC
## AvrDebugger.flush_events()
### Description
Flushes any pending debug events.
### Method
N/A (Method call)
### Endpoint
N/A
### Parameters
None
### Request Example
```python
AvrDebugger.flush_events()
```
### Response
None specified.
```

```APIDOC
## AvrDebugger.hardware_breakpoint_clear(address)
### Description
Clears a hardware breakpoint at a specified address.
### Method
N/A (Method call)
### Endpoint
N/A
### Parameters
- **address** (int) - The address of the hardware breakpoint to clear.
### Request Example
```python
AvrDebugger.hardware_breakpoint_clear(0x1000)
```
### Response
None specified.
```

```APIDOC
## AvrDebugger.hardware_breakpoint_set(address)
### Description
Sets a hardware breakpoint at a specified address.
### Method
N/A (Method call)
### Endpoint
N/A
### Parameters
- **address** (int) - The address to set the hardware breakpoint.
### Request Example
```python
AvrDebugger.hardware_breakpoint_set(0x1000)
```
### Response
None specified.
```

```APIDOC
## AvrDebugger.poll_event()
### Description
Polls for any debug events.
### Method
N/A (Method call)
### Endpoint
N/A
### Parameters
None
### Request Example
```python
AvrDebugger.poll_event()
```
### Response
Returns information about any pending events.
```

```APIDOC
## AvrDebugger.program_counter_read()
### Description
Reads the current value of the program counter.
### Method
N/A (Method call)
### Endpoint
N/A
### Parameters
None
### Request Example
```python
pc = AvrDebugger.program_counter_read()
```
### Response
Returns the program counter value.
```

```APIDOC
## AvrDebugger.program_counter_write(address)
### Description
Sets the program counter to a specified address.
### Method
N/A (Method call)
### Endpoint
N/A
### Parameters
- **address** (int) - The address to set the program counter to.
### Request Example
```python
AvrDebugger.program_counter_write(0x1000)
```
### Response
None specified.
```

```APIDOC
## AvrDebugger.register_file_read(register_name)
### Description
Reads the value of a specified register from the register file.
### Method
N/A (Method call)
### Endpoint
N/A
### Parameters
- **register_name** (str) - The name of the register to read.
### Request Example
```python
register_value = AvrDebugger.register_file_read('R0')
```
### Response
Returns the value of the specified register.
```

```APIDOC
## AvrDebugger.register_file_write(register_name, value)
### Description
Writes a value to a specified register in the register file.
### Method
N/A (Method call)
### Endpoint
N/A
### Parameters
- **register_name** (str) - The name of the register to write to.
- **value** (int) - The value to write.
### Request Example
```python
AvrDebugger.register_file_write('R1', 0x10)
```
### Response
None specified.
```

```APIDOC
## AvrDebugger.reset()
### Description
Resets the AVR device.
### Method
N/A (Method call)
### Endpoint
N/A
### Parameters
None
### Request Example
```python
AvrDebugger.reset()
```
### Response
None specified.
```

```APIDOC
## AvrDebugger.run()
### Description
Resumes execution of the AVR device's program.
### Method
N/A (Method call)
### Endpoint
N/A
### Parameters
None
### Request Example
```python
AvrDebugger.run()
```
### Response
None specified.
```

```APIDOC
## AvrDebugger.run_to(address)
### Description
Resumes execution until a specified address is reached.
### Method
N/A (Method call)
### Endpoint
N/A
### Parameters
- **address** (int) - The address to run to.
### Request Example
```python
AvrDebugger.run_to(0x1050)
```
### Response
None specified.
```

```APIDOC
## AvrDebugger.setup_session(config)
### Description
Sets up the debugging session with the specified configuration.
### Method
N/A (Method call)
### Endpoint
N/A
### Parameters
- **config** (dict) - Configuration parameters for the session.
### Request Example
```python
AvrDebugger.setup_session({'interface': 'JTAG', 'port': '/dev/ttyACM0'})
```
### Response
None specified.
```

```APIDOC
## AvrDebugger.software_breakpoint_clear(address)
### Description
Clears a software breakpoint at a specified address.
### Method
N/A (Method call)
### Endpoint
N/A
### Parameters
- **address** (int) - The address of the software breakpoint to clear.
### Request Example
```python
AvrDebugger.software_breakpoint_clear(0x1000)
```
### Response
None specified.
```

```APIDOC
## AvrDebugger.software_breakpoint_clear_all()
### Description
Clears all software breakpoints.
### Method
N/A (Method call)
### Endpoint
N/A
### Parameters
None
### Request Example
```python
AvrDebugger.software_breakpoint_clear_all()
```
### Response
None specified.
```

```APIDOC
## AvrDebugger.software_breakpoint_set(address)
### Description
Sets a software breakpoint at a specified address.
### Method
N/A (Method call)
### Endpoint
N/A
### Parameters
- **address** (int) - The address to set the software breakpoint.
### Request Example
```python
AvrDebugger.software_breakpoint_set(0x1000)
```
### Response
None specified.
```

```APIDOC
## AvrDebugger.sram_read(address, length)
### Description
Reads data from the SRAM of the AVR device.
### Method
N/A (Method call)
### Endpoint
N/A
### Parameters
- **address** (int) - The starting SRAM address.
- **length** (int) - The number of bytes to read.
### Request Example
```python
sram_data = AvrDebugger.sram_read(0x2000, 32)
```
### Response
Returns the read SRAM data.
```

```APIDOC
## AvrDebugger.sram_write(address, data)
### Description
Writes data to the SRAM of the AVR device.
### Method
N/A (Method call)
### Endpoint
N/A
### Parameters
- **address** (int) - The starting SRAM address.
- **data** (bytes) - The data to write.
### Request Example
```python
AvrDebugger.sram_write(0x2000, b'\xAA\xBB')
```
### Response
None specified.
```

```APIDOC
## AvrDebugger.stack_pointer_read()
### Description
Reads the current value of the stack pointer.
### Method
N/A (Method call)
### Endpoint
N/A
### Parameters
None
### Request Example
```python
sp = AvrDebugger.stack_pointer_read()
```
### Response
Returns the stack pointer value.
```

```APIDOC
## AvrDebugger.status_register_read()
### Description
Reads the value of the status register.
### Method
N/A (Method call)
### Endpoint
N/A
### Parameters
None
### Request Example
```python
status_reg = AvrDebugger.status_register_read()
```
### Response
Returns the status register value.
```

```APIDOC
## AvrDebugger.step()
### Description
Executes a single instruction step.
### Method
N/A (Method call)
### Endpoint
N/A
### Parameters
None
### Request Example
```python
AvrDebugger.step()
```
### Response
None specified.
```

```APIDOC
## AvrDebugger.stop()
### Description
Stops the execution of the AVR device's program.
### Method
N/A (Method call)
### Endpoint
N/A
### Parameters
None
### Request Example
```python
AvrDebugger.stop()
```
### Response
None specified.
```

```APIDOC
## AvrDebugger.stop_debugging()
### Description
Stops the debugging session.
### Method
N/A (Method call)
### Endpoint
N/A
### Parameters
None
### Request Example
```python
AvrDebugger.stop_debugging()
```
### Response
None specified.
```

--------------------------------

### NvmAccessProviderCmsisDapTpi

Source: https://microchip-pic-avr-tools.github.io/pymcuprog/pymcuprog.html

Provides NVM access via TPI/tinytiny. This is an alpha implementation and may not support all features.

```APIDOC
## Class: NvmAccessProviderCmsisDapTpi

### Description
NVM Access the TPI way. This is a stub - not all features are implemented.

### Methods

#### erase(_memory_info =None_, _address =None_)
Do a chip erase of the device.

#### read(_memory_info_ , _offset_ , _numbytes_)
Read the memory in chunks.

Parameters:
* **memory_info** (dict) - dictionary for the memory as provided by the DeviceMemoryInfo class
* **offset** (int) - relative offset in the memory type
* **numbytes** (int) - number of bytes to read

Returns:
array of bytes read

#### read_device_id()
Read the device ID.

Returns:
Device ID raw bytes (little endian)

#### stop()
Stop programming session.

#### write(_memory_info_ , _offset_ , _data_)
Write the memory with data.

Parameters:
* **memory_info** (dict) - dictionary for the memory as provided by the DeviceMemoryInfo class
* **offset** (int) - relative offset within the memory type
* **data** (bytes) - the data to program
```

--------------------------------

### Avr32Device Methods

Source: https://microchip-pic-avr-tools.github.io/pymcuprog/index.html

Methods for activating/deactivating physical connections and setting up programming sessions for AVR32 devices (alpha support).

```APIDOC
## Avr32Device Methods

### Description
Methods for interacting with AVR32 devices, including physical connection management and programming session setup. This functionality is in alpha.

### Methods
- `activate_physical()`: Activates the physical connection to the device.
- `deactivate_physical()`: Deactivates the physical connection to the device.
- `setup_prog_session()`: Sets up a programming session for the target device.
```

--------------------------------

### pymcuprog.deviceinfo.memorynames.MemoryNames.get_all

Source: https://microchip-pic-avr-tools.github.io/pymcuprog/pymcuprog.deviceinfo.html

Gets a list of all memory names that correspond to actual device memories. This method provides a comprehensive overview of the addressable memory regions on a target device.

```APIDOC
## MemoryNames.get_all

### Description
Get a list of all memories representing actual device memories.

### Method
```python
MemoryNames.get_all()
```

### Returns
- List of memory names representing actual device memories
```

--------------------------------

### NVM Access Provider (SAM M0+)

Source: https://microchip-pic-avr-tools.github.io/pymcuprog/pymcuprog.html

Implementation of NVM access for SAM M0+ microcontrollers (alpha).

```APIDOC
## NVM Access Provider (SAM M0+) Methods (alpha)

### `erase()`

**Description**: Erases the NVM of the SAM M0+ device.

### `read(address, length)`

**Description**: Reads data from the NVM of the SAM M0+ device.

*   **address** (int): The starting address for reading.
*   **length** (int): The number of bytes to read.

### `read_device_id()`

**Description**: Reads the device ID of the SAM M0+ device.

### `stop()`

**Description**: Terminates NVM access for SAM M0+.

### `write(address, data)`

**Description**: Writes data to the NVM of the SAM M0+ device.

*   **address** (int): The starting address for writing.
*   **data** (bytes): The data to write.
```

--------------------------------

### DeviceMemoryInfo API

Source: https://microchip-pic-avr-tools.github.io/pymcuprog/pymcuprog.deviceinfo.html

Provides an API to fetch information about device memory segments. It includes methods to get memory details by address, address range, and name.

```APIDOC
## Class: DeviceMemoryInfo

### Description
API to fetch information about device memory segments.

### Methods
#### `_bytes_or_words(_address_param_)`
Returns multiplier for address parameter. The returned multiplier can be used to convert the address parameter to byte address.

Parameters:
* **address_param** (string) - Address parameter (used as key in device info dict)

Returns:
Multiplier to convert the address to byte address.

#### `memory_info_by_address(_byte_address_, _address_type='address'_, _size_type='size'_)`
Returns information about the memory type for a given byte address.

Parameters:
* **byte_address** (integer) - Memory address to check
* **address_type** (string) - Optional. Selects between normal addresses and addresses used in hex files (ADDRESS vs HEXFILE_ADDRESS). Defaults to 'address'.
* **size_type** (string) - Optional. Selects between normal size and size used in hexfiles (size vs hexfile_size). Defaults to 'size'.

#### `memory_info_by_address_range(_start_, _stop_, _address_type='address'_, _size_type='size'_)`
Returns a list of all memories applicable for the address range (start, stop).

Parameters:
* **start** (integer) - Start address (byte)
* **stop** (integer) - End address (byte)
* **address_type** (string) - Optional. Selects between normal addresses and addresses used in hex files (address vs hexfile_address). Defaults to 'address'.
* **size_type** (string) - Optional. Selects between normal size and size used in hexfiles (size vs hexfile_size). Defaults to 'size'.

#### `memory_info_by_name(_name_)`
Returns information about the requested memory.

Parameters:
* **name** (string) - Name of the memory to retrieve information for.
```

--------------------------------

### AvrDevice Methods

Source: https://microchip-pic-avr-tools.github.io/pymcuprog/index.html

Provides methods for interacting with AVR devices, including activating/deactivating physical connections, entering/leaving programming mode, erasing, and reading/writing memory sections.

```APIDOC
## AvrDevice Methods

### Description
Methods for interacting with AVR devices via the PyMCUProg library.

### Methods
- `activate_physical()`: Activates the physical connection to the device.
- `deactivate_physical()`: Deactivates the physical connection to the device.
- `enter_progmode()`: Enters programming mode on the device.
- `erase()`: Erases the device's memory.
- `is_blank()`: Checks if the device is blank.
- `leave_progmode()`: Leaves programming mode on the device.
- `memory_read(address, length)`: Reads a specified number of bytes from the device's memory.
- `memory_write(address, data)`: Writes data to a specified address in the device's memory.
- `memtype_read_from_string(memtype_str)`: Converts a memory type string to its internal representation.
- `read_memory_section(memtype, address, length)`: Reads a specific section of memory.
- `write_memory_section(memtype, address, data)`: Writes a specific section of memory.
```

--------------------------------

### NVM Access Provider (PIC)

Source: https://microchip-pic-avr-tools.github.io/pymcuprog/pymcuprog.html

Implementation of NVM access for PIC microcontrollers.

```APIDOC
## NVM Access Provider (PIC) Methods

### `erase()`

**Description**: Erases the NVM of the PIC device.

### `hold_in_reset()`

**Description**: Holds the PIC device in reset.

### `read(address, length)`

**Description**: Reads data from the NVM of the PIC device.

*   **address** (int): The starting address for reading.
*   **length** (int): The number of bytes to read.

### `read_device_id()`

**Description**: Reads the device ID of the PIC device.

### `release_from_reset()`

**Description**: Releases the PIC device from reset.

### `stop()`

**Description**: Terminates NVM access for PIC.

### `write(address, data)`

**Description**: Writes data to the NVM of the PIC device.

*   **address** (int): The starting address for writing.
*   **data** (bytes): The data to write.
```

--------------------------------

### Backend API

Source: https://microchip-pic-avr-tools.github.io/pymcuprog/pymcuprog.html

Provides methods for interacting with the tool's backend, including reading voltage levels, tool information, and managing sessions.

```APIDOC
## Backend Methods

### `read_supply_voltage_setpoint()`

**Description**: Reads the current supply voltage setpoint.

### `read_target_voltage()`

**Description**: Reads the current target voltage.

### `read_tool_info()`

**Description**: Reads information about the connected tool.

### `read_usb_voltage()`

**Description**: Reads the current USB voltage.

### `reboot_tool()`

**Description**: Reboots the connected tool.

### `release_from_reset()`

**Description**: Releases the target device from reset.

### `set_supply_voltage_setpoint(voltage)`

**Description**: Sets the supply voltage setpoint.

*   **voltage** (float): The desired voltage level.

### `start_session()`

**Description**: Starts a new session with the tool.

### `verify_hex(hex_file_path)`

**Description**: Verifies the integrity of a HEX file.

*   **hex_file_path** (str): Path to the HEX file.

### `verify_memory(address, data)`

**Description**: Verifies memory content at a given address.

*   **address** (int): The memory address to verify.
*   **data** (bytes): The data to compare against.

### `write_hex_to_target(hex_file_path)`

**Description**: Writes a HEX file to the target device's memory.

*   **hex_file_path** (str): Path to the HEX file.

### `write_memory(address, data)`

**Description**: Writes data to the target device's memory at a given address.

*   **address** (int): The memory address to write to.
*   **data** (bytes): The data to write.
```

--------------------------------

### NvmUpdiP0 Specific Methods

Source: https://microchip-pic-avr-tools.github.io/pymcuprog/pymcuprog.serialupdi.html

Implements NVM controller operations specific to P0 devices (tiny0, 1, 2 and mega0).

```APIDOC
## NvmUpdiP0

### Description
Version P:0 UPDI NVM properties.

### Methods

#### `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)`

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

*   **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)`

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
    *   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
```

--------------------------------

### _get_supported_devices

Source: https://microchip-pic-avr-tools.github.io/pymcuprog/pymcuprog.html

Returns a list of all devices supported by the PyMCUProg library, based on the availability of corresponding device files.

```APIDOC
## _get_supported_devices

### Description
Return a list of devices supported by pymcuprog.
This will be the list of devices with a corresponding device file.

### Returns
List of device names.

### Return Type
list
```

--------------------------------

### DeviceInfoKeys and Variants

Source: https://microchip-pic-avr-tools.github.io/pymcuprog/pymcuprog.html

Constants and keys for accessing device information, with specific variants for AVR and PIC devices.

```APIDOC
## DeviceInfoKeys

### Description
Constants and keys for accessing device information.

### Attributes
- `ARCHITECTURE`: The architecture of the device.
- `DEVICE_ID`: The unique identifier of the device.
- `INTERFACE`: The interface used for communication.
- `NAME`: The name of the device.

### Methods
- `get_all()`: Returns all available device info keys.

## DeviceInfoKeysAvr

### Description
Specific keys for AVR devices.

### Attributes
- `ADDRESS_SIZE`: The size of the address.
- `DATA_ADDRESS_SPACE`: The data address space.
- `HV_IMPLEMENTATION`: Hardware verification implementation details.
- `NVMCTRL_BASE`: Base address for NVM controller.
- `OCD_BASE`: Base address for On-Chip Debugger.
- `PROG_CLOCK_KHZ`: Programming clock frequency in kHz.
- `SYSCFG_BASE`: Base address for system configuration registers.

## DeviceInfoKeysAvr32

### Description
Specific keys for AVR32 devices.

### Attributes
- `RESET_DOMAINS`: Information about reset domains.

## DeviceInfoKeysPic

### Description
Specific keys for PIC devices.

### Attributes
- `DEFAULT_BULK_ERASE_ADDRESS`: Default address for bulk erase operations.

## DeviceMemoryInfoKeys

### Description
Keys for accessing memory information.

### Attributes
- `ADDRESS`: Memory address.
- `CHIPERASE_EFFECT`: Effect of chip erase operation.
- `ERASE_ADDRESS`: Address for erase operations.
- `HEXFILE_ADDRESS`: Address for hex file data.
- `HEXFILE_SIZE`: Size of hex file data.
- `ISOLATED_ERASE`: Indicates if erase is isolated.
- `NAME`: Name of the memory region.
- `PAGE_SIZE`: Size of a memory page.
- `READ_SIZE`: Size of data that can be read at once.
- `SIZE`: Total size of the memory region.
- `VERIFY_MASK`: Mask for verification operations.
- `WRITE_SIZE`: Size of data that can be written at once.

### Methods
- `get_all()`: Returns all available memory info keys.
```

--------------------------------

### NvmAccessProviderCmsisDapXmega

Source: https://microchip-pic-avr-tools.github.io/pymcuprog/pymcuprog.html

Provides NVM access for XMEGA devices. This is an alpha implementation and may not support all features.

```APIDOC
## Class: NvmAccessProviderCmsisDapXmega

### Description
NVM Access the Xmega way. This class provides methods to interact with the Non-Volatile Memory of XMEGA devices using a CMSIS-DAP transport.

### Methods

#### erase(_memory_info=None_, _address=None_)
Do a chip erase of the device.

#### _static _read(_memory_info_, _offset_, _numbytes_)
Read the memory in chunks.

Parameters:
- **memory_info** (dict) - Dictionary for the memory as provided by the DeviceMemoryInfo class.
- **offset** (int) - Relative offset in the memory type.
- **numbytes** (int) - Number of bytes to read.

Returns:
- array of bytes read

#### read_device_id()
Read the device info.

Returns:
- Device ID raw bytes (little endian)

#### start(_user_interaction_callback=None_)
Start (activate) session for XMEGA targets.

#### stop()
Stop (deactivate) session for XMEGA targets.

#### _static _write(_memory_info_, _offset_, _data_)
Write the memory with data.

Parameters:
- **memory_info** (dict) - Dictionary for the memory as provided by the DeviceMemoryInfo class.
- **offset** (int) - Relative offset within the memory type.
- **data** (bytes) - The data to program.
```

--------------------------------

### TinyXAvrTarget Methods

Source: https://microchip-pic-avr-tools.github.io/pymcuprog/index.html

Provides a comprehensive set of methods for interacting with TinyX AVR devices, including debugging, programming, and memory operations.

```APIDOC
## TinyXAvrTarget Methods

### Description
Methods for interacting with TinyX AVR devices, supporting debugging, programming, and various low-level operations.

### Methods
- `activate_physical()`: Activates the physical connection.
- `breakpoint_clear(bp_type, address)`: Clears a breakpoint at a specified address.
- `breakpoint_set(bp_type, address)`: Sets a breakpoint at a specified address.
- `execute_instruction(instruction)`: Executes a single instruction.
- `execute_patch(patch)`: Executes a patch of code.
- `memtype_write_from_string(memtype_str)`: Converts a memory type string to its internal representation for writing.
- `ocdregfile_read(reg_name)`: Reads an OCD register file.
- `read_device_id()`: Reads the device identifier.
- `run_with_power_nap()`: Runs the device with power nap enabled.
- `setup_config()`: Sets up the device configuration.
- `setup_debug_session()`: Sets up a debug session.
- `setup_prog_session()`: Sets up a programming session.
- `sib_read()`: Reads from the SIB (Serial Interface Board).
- `stack_pointer_read()`: Reads the stack pointer value.
```

--------------------------------

### MegaAvrJtagTarget Methods

Source: https://microchip-pic-avr-tools.github.io/pymcuprog/index.html

Methods for setting up configuration and programming sessions for Mega AVR devices using JTAG.

```APIDOC
## MegaAvrJtagTarget Methods

### Description
Methods for configuring and initiating programming sessions for Mega AVR devices using JTAG.

### Methods
- `setup_config()`: Sets up the configuration for the target device.
- `setup_prog_session()`: Sets up a programming session for the target device.
```

--------------------------------

### get_supported_devices

Source: https://microchip-pic-avr-tools.github.io/pymcuprog/pymcuprog.deviceinfo.html

Retrieves a list of all devices supported by the pymcuprog tool. A device is considered supported if it has a corresponding device model file in the 'devices' folder.

```APIDOC
## Function: get_supported_devices()

### Description
Return a list of all supported devices.

A device is supported if it has a device model file in the devices folder.

### Returns
* list - A list of supported device names.
```

--------------------------------

### TinyAvrTarget Class

Source: https://microchip-pic-avr-tools.github.io/pymcuprog/pymcuprog.html

Implements Tiny AVR (debugWire) functionality of the AVR8 protocol, inheriting from AvrDevice.

```APIDOC
## Class: TinyAvrTarget

### Description
Implements Tiny AVR (debugWire) functionality of the AVR8 protocol.

### Methods

#### setup_debug_session()

* Description: Sets up a debugging session on an Tiny AVR (debugwire).
```

--------------------------------

### NVM Access Provider (debugWire)

Source: https://microchip-pic-avr-tools.github.io/pymcuprog/pymcuprog.html

Implementation of NVM access for devices using the debugWire interface (alpha).

```APIDOC
## NVM Access Provider (debugWire) Methods (alpha)

### `erase()`

**Description**: Erases the NVM of the debugWire device.

### `read(address, length)`

**Description**: Reads data from the NVM of the debugWire device.

*   **address** (int): The starting address for reading.
*   **length** (int): The number of bytes to read.

### `read_device_id()`

**Description**: Reads the device ID of the debugWire device.

### `write(address, data)`

**Description**: Writes data to the NVM of the debugWire device.

*   **address** (int): The starting address for writing.
*   **data** (bytes): The data to write.
```
Tokens:
Raw