SMP Client

https://intercreate.github.io/smpclient/
Admin
SMP Client is a Python package that implements transport layers for the Simple Management Protocol,...
Tokens:38,914
Snippets:271
Trust Score:9.7
Update:4 months ago
Show doc for...
Tokens:
Raw
### BootloaderInformationRead Request - Python

Source: https://intercreate.github.io/smpclient/latest/os_management

Defines the BootloaderInformationRead request for OS Management. Use this to get information about the bootloader.

```python
class BootloaderInformationRead(smpos.BootloaderInformationReadRequest, _OSGroupBase):
    _Response = smpos.BootloaderInformationReadResponse
```

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

### Check for Potential SMP Packet Start Byte

Source: https://intercreate.github.io/smpclient/latest/transport/serial

Determines if a given byte value matches the first byte of any SMP packet delimiter (START or CONTINUE). This is used for edge case handling when a delimiter might be split across buffer boundaries.

```python
def _could_be_smp_packet_start(self, byte: int) -> bool:
        """Return True if the given byte value matches the start of any SMP packet delimiter."""
        return byte == smppacket.START_DELIMITER[0] or byte == smppacket.CONTINUE_DELIMITER[0]
```

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

### Find SMP Packet Start Delimiter

Source: https://intercreate.github.io/smpclient/latest/transport/serial

Searches a bytearray for the earliest occurrence of either the SMP frame-start or continue delimiter. Returns the index of the earliest delimiter found, or -1 if none are present.

```python
def _find_smp_packet_start(self, buf: bytearray) -> int:
        """Return index of the earliest SMP frame-start delimiter, if any; -1 if none found."""
        indices = [
            i
            for i in (
                buf.find(smppacket.START_DELIMITER),
                buf.find(smppacket.CONTINUE_DELIMITER),
            )
            if i != -1
        ]
        return min(indices) if indices else -1
```

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

### Send and Receive Data via UDP

Source: https://intercreate.github.io/smpclient/latest/transport/udp

Sends encoded SMPRequest data and receives decoded SMPResponse. Requires prior setup of the UDP transport.

```python
@override
async def send_and_receive(self, data: bytes) -> bytes:
    await self.send(data)
    return await self.receive()
```

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

### SMP Client Initialization and Connection

Source: https://intercreate.github.io/smpclient/latest

Details on how to initialize and connect the SMP client to a server.

```APIDOC
## SMPClient

### Description
Client for interacting with an SMP server.

### Parameters
#### Path Parameters
- **address** (str) - The SMP server address.

#### Query Parameters
- **transport** (SMPTransport) - Required - The transport layer for communication.
- **timeout_s** (float) - Optional - The timeout for requests in seconds. Defaults to 2.5.

### Methods
#### `__init__`
Initializes the SMP client.

#### `connect`
Connect to the SMP server.

##### Parameters
- **connect_timeout_s** (float | None) - Optional - The timeout for the connection attempt in seconds.

#### `disconnect`
Disconnect from the SMP server.

#### `request`
Make an `SMPRequest` to the SMP server and return the Response or Error.

##### Parameters
- **request** (SMPRequest[TRep, TEr1, TEr2]) - Required - The `SMPRequest` to send.
- **timeout_s** (float | None) - Optional - The timeout for the request in seconds.

##### Returns
- **TRep | TEr1 | TEr2** - The typed and validated Response or Error.

##### Raises
- **TimeoutError** - If the request times out.
- **SMPBadSequence** - If the response sequence does not match the request sequence.
- **ValidationError** - If the response cannot be parsed as a Response or Error.

### Request Example
```python
response = await client.request(EchoWrite(d="Hello, World!"))
if success(response):
    print(f"Response: {response=}")
elif error(response):
    print(f"Error: {response=}")
else:
    assert_never(response)
```

### Type Safety and Exhaustiveness with Generic Typing
```python
response = await client.request(EchoWrite(d="Hello, World!"))
reveal_type(response)
```
```

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

### Connect to SMP Server

Source: https://intercreate.github.io/smpclient/latest/transport/udp

Establishes a connection to the SMP server.

```APIDOC
## connect(address: str, timeout_s: float, port: int = 1337)

### Description
Connect the SMPTransport to a remote server.

### Parameters
#### Query Parameters
- **address** (str) - Required - The SMP server address.
- **timeout_s** (float) - Required - The connection timeout in seconds.
- **port** (int) - Optional - The server port. Default is 1337.
```

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

### SMPTransport.mtu

Source: https://intercreate.github.io/smpclient/latest/transport/transport

Gets the Maximum Transmission Unit (MTU) in 8-bit bytes.

```APIDOC
## SMPTransport.mtu

### Description
Gets the Maximum Transmission Unit (MTU) in 8-bit bytes.

### Property
`mtu`: int
```

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

### SMPTransport.max_unencoded_size

Source: https://intercreate.github.io/smpclient/latest/transport/transport

Gets the maximum size of an unencoded message that can be sent, in 8-bit bytes.

```APIDOC
## SMPTransport.max_unencoded_size

### Description
Gets the maximum size of an unencoded message that can be sent, in 8-bit bytes.

### Property
`max_unencoded_size`: int
```

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

### Constructor: __init__

Source: https://intercreate.github.io/smpclient/latest/transport/serial

Initializes the serial transport with specific configuration for SMP frame handling and serial port settings.

```APIDOC
## __init__

### Description
Initializes the serial transport. Configures the maximum frame sizes, buffer settings, and serial communication parameters.

### Parameters
#### Arguments
- **max_smp_encoded_frame_size** (int) - Optional - The maximum size of an encoded SMP frame. Default: 256
- **line_length** (int) - Optional - The maximum SMP packet size. Default: 128
- **line_buffers** (int) - Optional - The number of line buffers in the serial buffer. Default: 2
- **baudrate** (int) - Optional - The baudrate of the serial connection. Default: 115200
- **bytesize** (int) - Optional - The number of data bits. Default: 8
- **parity** (str) - Optional - The parity setting. Default: 'N'
- **stopbits** (float) - Optional - The number of stop bits. Default: 1
- **timeout** (float | None) - Optional - The read timeout. Default: None
- **xonxoff** (bool) - Optional - Enable software flow control. Default: False
- **rtscts** (bool) - Optional - Enable hardware (RTS/CTS) flow control. Default: False
- **write_timeout** (float | None) - Optional - The write timeout. Default: None
- **dsrdtr** (bool) - Optional - Enable hardware (DSR/DTR) flow control. Default: False
- **inter_byte_timeout** (float | None) - Optional - The inter-byte timeout. Default: None
- **exclusive** (bool | None) - Optional - The exclusive access timeout. Default: None
```

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

### SMPClient.connect

Source: https://intercreate.github.io/smpclient/latest

Establishes a connection to the SMP server.

```APIDOC
## Method: connect

### Description
Connects to the SMP server.

### Parameters
#### Arguments
- **connect_timeout_s** (float | None) - Optional - The timeout for the connection attempt in seconds. Defaults to the client's default timeout.

### Request Example
```python
await client.connect(connect_timeout_s=5.0)
```
```

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

### SMPBLETransport.mtu

Source: https://intercreate.github.io/smpclient/latest/transport/ble

Property to get the Maximum Write Without Response Size (MTU) for the BLE connection.

```APIDOC
## SMPBLETransport.mtu

### Description
Gets the Maximum Transmission Unit (MTU) size that can be used for writing data without requiring a response. This property reflects the underlying BLE connection's capabilities.

### Method
`@property
def mtu(self) -> int`

### Parameters
None

### Returns
* **int**: The MTU size.
```

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

### Connect to SMP Server

Source: https://intercreate.github.io/smpclient/latest/transport/serial

Establishes a connection to the SMP server with a specified timeout.

```APIDOC
## connect /api/connect

### Description
Connect the `SMPTransport` to the SMP server.

### Method
POST

### Endpoint
/api/connect

### Parameters
#### Query Parameters
- **address** (str) - Required - The SMP server address.
- **timeout_s** (float) - Required - The connection timeout in seconds.

### Request Example
```json
{
  "address": "192.168.1.100",
  "timeout_s": 5.0
}
```

### Response
#### Success Response (200)
- **status** (string) - Indicates successful connection.

#### Response Example
```json
{
  "status": "connected"
}
```
```

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

### Get TLV from Image

Source: https://intercreate.github.io/smpclient/latest/mcuboot

Retrieves a specific TLV from the image based on its type. Raises TLVNotFound if the TLV is not present.

```python
def get_tlv(self, tlv: ImageTLVType) -> ImageTLVValue:
    """Get a TLV from the image or raise `TLVNotFound`."""
    if tlv in self._map_tlv_type_to_value:
        return self._map_tlv_type_to_value[tlv]
    else:
        raise TLVNotFound(f"{tlv} not found in image.")
```

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

### upload

Source: https://intercreate.github.io/smpclient/latest

Iteratively uploads a firmware image to a specified slot on the SMP server.

```APIDOC
## upload

### Description
Iteratively uploads a binary image to a specific slot, yielding the current offset as the upload progresses.

### Parameters
#### Request Body
- **image** (bytes) - Required - The binary image data to upload.
- **slot** (int) - Optional - The target slot index (default 0).
- **upgrade** (bool) - Optional - Whether to mark the image as confirmed (default False).
- **first_timeout_s** (float) - Optional - Timeout for the first request (default 40.0).
- **subsequent_timeout_s** (float) - Optional - Timeout for subsequent requests.
- **use_sha** (bool) - Optional - Whether to include the SHA256 hash in the first packet (default True).

### Response
#### Success Response (200)
- **offset** (AsyncIterator[int]) - Yields the current byte offset as the upload progresses.
```

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

### Iteratively Upload an Image

Source: https://intercreate.github.io/smpclient/latest

Use this method to upload an image to a specified slot on the SMP server. It yields the offset as the upload progresses. Be cautious with the 'upgrade' parameter as it can brick the device if not handled correctly.

```python
async def upload(
        self,
        image: bytes,
        slot: int = 0,
        upgrade: bool = False,
        first_timeout_s: float = 40.0,
        subsequent_timeout_s: float | None = None,
        use_sha: bool = True,
    ) -> AsyncIterator[int]:
```

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

### MemoryPoolStatisticsRead Request - Python

Source: https://intercreate.github.io/smpclient/latest/os_management

Defines the MemoryPoolStatisticsRead request for OS Management. Use this to get statistics about memory pools.

```python
class MemoryPoolStatisticsRead(smpos.MemoryPoolStatisticsReadRequest, _OSGroupBase):
    _Response = smpos.MemoryPoolStatisticsReadResponse
```

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

### OSApplicationInfoRead Request - Python

Source: https://intercreate.github.io/smpclient/latest/os_management

Defines the OSApplicationInfoRead request for OS Management. Use this to retrieve information about the OS application.

```python
class OSApplicationInfoRead(smpos.OSApplicationInfoReadRequest, _OSGroupBase):
    _Response = smpos.OSApplicationInfoReadResponse
```

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

### Initialize SMPBLETransport

Source: https://intercreate.github.io/smpclient/latest/transport/ble

Initializes the SMPBLETransport with optional WinRT client arguments. Sets up internal buffers and events.

```python
class SMPBLETransport(SMPTransport):
    """A Bluetooth Low Energy (BLE) SMPTransport."""

    def __init__(self, winrt: WinRTClientArgs = {}) -> None:
        self._buffer = bytearray()
        self._notify_condition = asyncio.Condition()
        self._disconnected_event = asyncio.Event()
        self._disconnected_event.set()
        self._winrt = winrt

        self._max_write_without_response_size = 20
        """Initially set to BLE minimum; may be mutated by the `connect()` method."""

        logger.debug(f"Initialized {self.__class__.__name__}")
```

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

### initialize

Source: https://intercreate.github.io/smpclient/latest/transport/transport

Initializes the SMPTransport with the specified server transport buffer size. This must be called before other transport operations.

```APIDOC
## initialize

### Description
Initializes the `SMPTransport` with the specified server transport buffer size. This must be called before other transport operations.

### Method
POST

### Endpoint
`/transport/initialize`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **smp_server_transport_buffer_size** (int) - Required - The SMP server transport buffer size, in 8-bit bytes.

### Request Example
```json
{
  "smp_server_transport_buffer_size": 1024
}
```

### Response
#### Success Response (200)
- None (void)

#### Response Example
None
```

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

### SMPTransport.initialize

Source: https://intercreate.github.io/smpclient/latest/transport/transport

Initializes the SMPTransport with the server's transport buffer size.

```APIDOC
## SMPTransport.initialize

### Description
Initializes the SMPTransport with the server's transport buffer size.

### Method
def initialize(self, smp_server_transport_buffer_size: int) -> None

### Parameters
#### Path Parameters
- **smp_server_transport_buffer_size** (int) - Required - The SMP server transport buffer size, in 8-bit bytes.
```

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

### async def request

Source: https://intercreate.github.io/smpclient/latest

Sends an SMPRequest to the SMP server and returns the validated response or error.

```APIDOC
## async def request

### Description
Sends an `SMPRequest` to the SMP server and returns the typed and validated Response or Error. It handles timeouts and sequence validation.

### Parameters
- **request** (SMPRequest[TRep, TEr1, TEr2]) - Required - The SMPRequest object to send.
- **timeout_s** (float | None) - Optional - The timeout for the request in seconds.

### Returns
- **TRep | TEr1 | TEr2** - The typed and validated Response or Error object.

### Raises
- **TimeoutError** - If the request exceeds the specified timeout.
- **SMPBadSequence** - If the response sequence does not match the request sequence.
- **ValidationError** - If the response cannot be parsed as a valid Response or Error type.
```

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

### Download File

Source: https://intercreate.github.io/smpclient/latest

Downloads a file from the SMP server. Requires `SMPUploadError` for error handling.

```python
async def download_file(
    self,
    file_path: str,
    timeout_s: float | None = None,
) -> bytes:
    """Download a file from the SMP server.

    Args:
        file_path: the path to download
        timeout_s: the timeout for each `FileDownload` request

    Returns:
        The downloaded file as `bytes`

    Raises:
        SMPUploadError: if the download routine fails
    """

```

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

### Load ImageHeader from File Path

Source: https://intercreate.github.io/smpclient/latest/mcuboot

Loads an MCUBoot ImageHeader directly from a file path. Opens the file in binary read mode and then loads the header.

```python
@staticmethod
def load_file(path: str) -> ImageHeader:
    """Load an `ImageHeader` the file at `path`."""
    with open(path, 'rb') as f:
        return ImageHeader.load_from(f)

```

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

### Connect to SMP Server

Source: https://intercreate.github.io/smpclient/latest/transport/udp

Connects the SMPTransport to a specified server address and port with a given timeout. It also detects and logs whether the connection is IPv4 or IPv6.

```python
@override
async def connect(self, address: str, timeout_s: float, port: int = 1337) -> None:
    logger.debug(f"Connecting to {address=} {port=}")
    await asyncio.wait_for(self._client.connect(Addr(host=address, port=port)), timeout_s)

    if sock := self._client._transport.get_extra_info('socket'):
        self._is_ipv6 = sock.family == AF_INET6
        logger.debug(f"Detected {'IPv6' if self._is_ipv6 else 'IPv4'} connection")

    logger.info(f"Connected to {address=} {port=}")
```

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

### Download File

Source: https://intercreate.github.io/smpclient/latest

Asynchronously downloads a file from the SMP server. Handles potential errors and retries if necessary.

```APIDOC
## POST /download_file

### Description
Asynchronously downloads a file from the SMP server. This method handles segmented downloads and ensures the entire file is retrieved.

### Method
POST

### Endpoint
/download_file

### Parameters
#### Query Parameters
- **file_path** (str) - Required - The path to the file on the SMP server to download.
- **timeout_s** (float | None) - Optional - The timeout in seconds for each `FileDownload` request. Defaults to the client's default timeout.

### Request Body
This endpoint does not explicitly define a request body in the provided documentation. The `FileDownload` object is constructed internally.

### Response
#### Success Response (200)
- **bytes** - The content of the downloaded file as a byte string.

#### Error Response
- **SMPUploadError** - Raised if the download routine fails at any point, such as if the file is not found or a network issue occurs.

### Request Example
```python
# Assuming 'client' is an initialized SMPClient instance
file_content = await client.download_file("path/to/your/file.txt", timeout_s=30.0)
```

### Response Example
```python
# On success, the response is the file content as bytes
b'This is the content of the downloaded file.'
```

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

### upload(image, slot, upgrade, first_timeout_s, subsequent_timeout_s, use_sha)

Source: https://intercreate.github.io/smpclient/latest

Iteratively uploads an image to a specified slot on the device.

```APIDOC
## upload(image, slot, upgrade, first_timeout_s, subsequent_timeout_s, use_sha)

### Description
Iteratively upload an image to a specified slot, yielding the current offset of the upload process.

### Parameters
- **image** (bytes) - Required - The bytes to upload.
- **slot** (int) - Optional - The slot to upload to (default: 0).
- **upgrade** (bool) - Optional - If True, marks the image as confirmed. Unsafe; can cause boot-loops (default: False).
- **first_timeout_s** (float) - Optional - Timeout for the first ImageUploadWrite request (default: 40.0).
- **subsequent_timeout_s** (float | None) - Optional - Timeout for subsequent ImageUploadWrite requests (default: None).
- **use_sha** (bool) - Optional - If True, includes the SHA256 hash of the image in the first packet (default: True).

### Yields
- **AsyncIterator[int]** - The current offset of the image upload.

### Raises
- **SMPUploadError** - Raised if the upload routine fails.
```

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

### Connection Management

Source: https://intercreate.github.io/smpclient/latest/transport/serial

Methods for establishing and terminating serial connections.

```APIDOC
## connect

### Description
Establishes a connection to the specified serial port with a timeout.

### Parameters
#### Path Parameters
- **address** (str) - Required - The serial port address.
- **timeout_s** (float) - Required - Connection timeout in seconds.

## disconnect

### Description
Closes the current serial connection.
```

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

### ImageVersion loads Method

Source: https://intercreate.github.io/smpclient/latest/mcuboot

The static `loads` method unpacks bytes data to create an ImageVersion object using the IMAGE_VERSION_STRUCT.

```python
@staticmethod
def loads(data: bytes) -> ImageVersion:
    """Load an `ImageVersion` from `bytes`."""
    return ImageVersion(*IMAGE_VERSION_STRUCT.unpack(data))
```

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

### Load MCUBoot Image from File

Source: https://intercreate.github.io/smpclient/latest/mcuboot

Loads an MCUBoot ImageInfo object from a specified file path. Supports both binary and Intel HEX formats.

```python
@staticmethod
def load_file(path: str) -> ImageInfo:
    """Load MCUBoot `ImageInfo` from the file at `path`.

    Files with the `.hex` extension are treated as Intel HEX format.
    All other file extensions are treated as binary.
    """
    file_path = pathlib.Path(path)

    if file_path.suffix != ".hex":
        with open(file_path, 'rb') as _f:
            f = BytesIO(_f.read())
    else:
        f = BytesIO()
        ret = hex2bin(str(file_path), f)
        if ret != 0:
            raise MCUBootImageError(f"hex2bin() ret: {ret}")

    f.seek(0)  # move to the start of the image
    image_header = ImageHeader.load_from(f)

    tlv_offset = image_header.hdr_size + image_header.img_size

    f.seek(tlv_offset)  # move to the start of the TLV area

    # The mcuboot design doc says that optional protected TLV entries come before regular TLV entries
    protected_tlv_info = (
        ImageTLVInfo.load_from(f, IMAGE_TLV_PROT_INFO_MAGIC)
        if image_header.protect_tlv_size > 0
        else None
    )

    if (
        protected_tlv_info is not None
        and protected_tlv_info.tlv_tot != image_header.protect_tlv_size
    ):
        raise MCUBootImageError(
            f"Protected TLV info total size {protected_tlv_info.tlv_tot} does not match header value {image_header.protect_tlv_size}"
        )

    protected_tlvs = (
        protected_tlv_info.load_tlvs_from(f) if protected_tlv_info is not None else None
    )

    tlv_info = ImageTLVInfo.load_from(f, IMAGE_TLV_INFO_MAGIC)
    tlvs = tlv_info.load_tlvs_from(f)

    return ImageInfo(
        file=path,
        header=image_header,
        tlv_info=tlv_info,
        tlvs=tlvs,
        protected_tlv_info=protected_tlv_info,
        protected_tlvs=protected_tlvs,
    )
```

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

### ResetWrite Request - Python

Source: https://intercreate.github.io/smpclient/latest/os_management

Defines the ResetWrite request for OS Management. Use this to trigger a system reset.

```python
class ResetWrite(smpos.ResetWriteRequest, _OSGroupBase):
    _Response = smpos.ResetWriteResponse
```

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

### OS Management Requests

Source: https://intercreate.github.io/smpclient/latest/os_management

A collection of request classes for OS management operations including echo, reset, statistics, and system information.

```APIDOC
## EchoWrite

### Description
Performs an echo write operation.

### Method
WRITE

## ResetWrite

### Description
Performs a system reset write operation.

### Method
WRITE

## TaskStatisticsRead

### Description
Reads task statistics from the device.

### Method
READ

## MemoryPoolStatisticsRead

### Description
Reads memory pool statistics from the device.

### Method
READ

## DateTimeRead

### Description
Reads the current date and time from the device.

### Method
READ

## DateTimeWrite

### Description
Writes the date and time to the device.

### Method
WRITE

## MCUMgrParametersRead

### Description
Reads MCUMgr parameters from the device.

### Method
READ

## OSApplicationInfoRead

### Description
Reads OS application information.

### Method
READ

## BootloaderInformationRead

### Description
Reads bootloader information from the device.

### Method
READ
```

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

### Initialize SMP UDP Transport

Source: https://intercreate.github.io/smpclient/latest/transport/udp

Initializes the SMP UDP transport instance with a specified MTU.

```APIDOC
## __init__(mtu: int = 1500)

### Description
Initialize the SMP UDP transport.

### Parameters
#### Query Parameters
- **mtu** (int) - Optional - The Maximum Transmission Unit (MTU) of the link layer in bytes. Default is 1500.
```

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

### SMPClient.request

Source: https://intercreate.github.io/smpclient/latest

Sends an SMP request to the server and returns the response or error.

```APIDOC
## Method: request

### Description
Sends an SMP request to the server and returns the response or error.

### Parameters
- **request** (SMPRequest) - Required - The SMP request object to send.

### Request Example
```python
response = await client.request(EchoWrite(d="Hello, World!"))
```

### Response
- **response** (SMPResponse) - The response object returned by the server.
```

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

### SMPTransport.connect

Source: https://intercreate.github.io/smpclient/latest/transport/transport

Connects the SMPTransport to an SMP server. It requires the server's address and a connection timeout in seconds.

```APIDOC
## SMPTransport.connect

### Description
Connects the SMPTransport to an SMP server. It requires the server's address and a connection timeout in seconds.

### Method
async def connect(self, address: str, timeout_s: float) -> None

### Parameters
#### Path Parameters
- **address** (str) - Required - The SMP server address.
- **timeout_s** (float) - Required - The connection timeout in seconds.
```

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

### Serial SMPTransport Overview

Source: https://intercreate.github.io/smpclient/latest/transport/serial

Overview of the Serial transport module and its supported interfaces.

```APIDOC
## Serial SMPTransport

### Description
A serial SMPTransport implementation. In addition to standard UART, this transport is compatible with USB CDC ACM and CAN interfaces.

### Module Attribute
- **logger** (logging.Logger) - The logger instance for the module.
```

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

### Initialize SMPSerialTransport

Source: https://intercreate.github.io/smpclient/latest/transport/serial

Initializes the serial transport with various configuration options for the serial port and SMP frame sizes. It includes checks for the consistency of frame size parameters.

```python
class SMPSerialTransport(SMPTransport):
    _POLLING_INTERVAL_S = 0.005
    _CONNECTION_RETRY_INTERVAL_S = 0.500

    @unique
    class BufferState(IntEnum):
        SMP = 0
        """An SMP start or continue delimiter has been received and
        `_buffer` is being parsed as an SMP packet.
        """

        SERIAL = 1
        """The SMP start delimiter has not been received and
        `_buffer` is being parsed as serial data.
        """

    def __init__(  # noqa: DOC301
        self,
        max_smp_encoded_frame_size: int = 256,
        line_length: int = 128,
        line_buffers: int = 2,
        baudrate: int = 115200,
        bytesize: int = 8,
        parity: str = "N",
        stopbits: float = 1,
        timeout: float | None = None,
        xonxoff: bool = False,
        rtscts: bool = False,
        write_timeout: float | None = None,
        dsrdtr: bool = False,
        inter_byte_timeout: float | None = None,
        exclusive: bool | None = None,
    ) -> None:
        """Initialize the serial transport.

        Args:
            max_smp_encoded_frame_size: The maximum size of an encoded SMP
                frame.  The SMP server needs to have a buffer large enough to
                receive the encoded frame packets and to store the decoded frame.
            line_length: The maximum SMP packet size.
            line_buffers: The number of line buffers in the serial buffer.
            baudrate: The baudrate of the serial connection.  OK to ignore for
                USB CDC ACM.
            bytesize: The number of data bits.
            parity: The parity setting.
            stopbits: The number of stop bits.
            timeout: The read timeout.
            xonxoff: Enable software flow control.
            rtscts: Enable hardware (RTS/CTS) flow control.
            write_timeout: The write timeout.
            dsrdtr: Enable hardware (DSR/DTR) flow control.
            inter_byte_timeout: The inter-byte timeout.
            exclusive: The exclusive access timeout.

        """
        if max_smp_encoded_frame_size < line_length * line_buffers:
            logger.error(
                f"{max_smp_encoded_frame_size=} is less than {line_length=} * {line_buffers=}!"
            )
        elif max_smp_encoded_frame_size != line_length * line_buffers:
            logger.warning(
                f"{max_smp_encoded_frame_size=} is not equal to {line_length=} * {line_buffers=}!"
            )

        self._max_smp_encoded_frame_size: Final = max_smp_encoded_frame_size
        self._line_length: Final = line_length
        self._line_buffers: Final = line_buffers
        self._conn: Final = Serial(
            baudrate=baudrate,
            bytesize=bytesize,
            parity=parity,
            stopbits=stopbits,
            timeout=timeout,
            xonxoff=xonxoff,
            rtscts=rtscts,
            write_timeout=write_timeout,
            dsrdtr=dsrdtr,
            inter_byte_timeout=inter_byte_timeout,
            exclusive=exclusive,
        )

        self._smp_packet_queue: asyncio.Queue[bytes] = asyncio.Queue()
        """Contains full SMP packets."""
        self._serial_buffer = bytearray()
        """Contains any non-SMP serial data."""
        self._buffer: bytearray = bytearray([])
        """Contains all incoming data (serial + SMP intertwined, may be incomplete)."""
        self._buffer_state = SMPSerialTransport.BufferState.SERIAL
        """The state of the read buffer."""

        logger.debug(f"Initialized {self.__class__.__name__}")

```

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

### File Download API

Source: https://intercreate.github.io/smpclient/latest

Enables downloading a file from a specified path on the SMP server.

```APIDOC
## GET /download/file

### Description
Downloads a file from the specified `file_path` on the SMP server.

### Method
GET

### Endpoint
/download/file

### Parameters
#### Path Parameters
- **file_path** (str) - Required - The path of the file to download from the SMP server.

#### Query Parameters
- **timeout_s** (float) - Optional - The timeout duration for each file download request.

### Request Body
None

### Response
#### Success Response (200)
- **file_data** (bytes) - The content of the downloaded file.

#### Response Example
```
(Binary data representing the file content)
```

### Raises
- **SMPUploadError**: If the download routine fails.
```

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

### SMPTransport Initialization

Source: https://intercreate.github.io/smpclient/latest/transport/ble

Initializes the SMPTransport with a byte buffer, notification condition, disconnection event, and WinRT client arguments. Sets the initial max write without response size.

```python
def __init__(self, winrt: WinRTClientArgs = {}) -> None:
    self._buffer = bytearray()
    self._notify_condition = asyncio.Condition()
    self._disconnected_event = asyncio.Event()
    self._disconnected_event.set()
    self._winrt = winrt

    self._max_write_without_response_size = 20
    """Initially set to BLE minimum; may be mutated by the `connect()` method."""

    logger.debug(f"Initialized {self.__class__.__name__}")
```

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

### Load ImageTLV from File

Source: https://intercreate.github.io/smpclient/latest/mcuboot

Loads an ImageTLV object from a file-like object. Ensures the TLV header is correctly read from the stream.

```python
@staticmethod
def load_from(file: BytesIO | BufferedReader) -> ImageTLV:
    """Load an `ImageTLV` from a file."""
    return ImageTLV(*IMAGE_TLV_STRUCT.unpack_from(file.read(IMAGE_TLV_STRUCT.size)))

```

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

### request

Source: https://intercreate.github.io/smpclient/latest

Sends an SMPRequest to the server and returns a typed response or error.

```APIDOC
## request

### Description
Sends an `SMPRequest` to the SMP server and returns the parsed Response or Error. It handles timeouts and validates the response sequence.

### Parameters
#### Request Body
- **request** (SMPRequest) - Required - The SMPRequest object to send.
- **timeout_s** (float) - Optional - The timeout for the request in seconds.

### Response
#### Success Response (200)
- **Response/Error** (TRep | TEr1 | TEr2) - The typed and validated response or error object.

### Errors
- **TimeoutError**: Raised if the request exceeds the specified timeout.
- **SMPBadSequence**: Raised if the response sequence does not match the request sequence.
- **ValidationError**: Raised if the response cannot be parsed as a valid Response or Error.
```

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

### ImageHeader.load_from

Source: https://intercreate.github.io/smpclient/latest/mcuboot

Loads an MCUBoot ImageHeader from an open file-like object. It reads the required number of bytes from the file and then uses the `loads` method to parse the header.

```APIDOC
## ImageHeader.load_from

### Description
Loads an `ImageHeader` from an open file-like object (e.g., `BytesIO`, `BufferedReader`). This method reads the exact size of the image header from the provided file object and then delegates the parsing to the `loads` method.

### Method
`staticmethod load_from(file: BytesIO | BufferedReader) -> ImageHeader`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **file** (BytesIO | BufferedReader) - Required - An open file-like object from which to read the image header data.

### Request Example
```python
from io import BytesIO

# Assuming 'file_obj' is an open file-like object
image_header = ImageHeader.load_from(file_obj)
```

### Response
#### Success Response (ImageHeader object)
- **magic** (ImageMagic) - The magic number identifying the header.
- **load_addr** (int) - The load address for the image.
- **hdr_size** (int) - The size of the header.
- **protect_tlv_size** (int) - The size of the protected TLV area.
- **img_size** (int) - The size of the image.
- **flags** (IMAGE_F) - Flags associated with the image.
- **ver** (ImageVersion) - The version information of the image.

#### Response Example
```json
{
  "magic": "0xABCD",
  "load_addr": 1073741824,
  "hdr_size": 32,
  "protect_tlv_size": 16,
  "img_size": 102400,
  "flags": "0x01",
  "ver": {"major": 1, "minor": 0, "revision": 0, "build": 0}
}
```
```

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

### File Management Operations

Source: https://intercreate.github.io/smpclient/latest/file_management

Overview of the available file management request classes in smpclient.

```APIDOC
## File Management Operations

### Description
The smpclient library provides several classes for file management operations. Each class maps to a specific request and response type defined in the underlying smpfs module.

### Available Classes
- **FileDownload**: Handles file download requests.
- **FileUpload**: Handles file upload requests.
- **FileStatus**: Retrieves the status of a file.
- **FileHashChecksum**: Requests the hash checksum of a file.
- **SupportedFileHashChecksumTypes**: Retrieves supported checksum types.
- **FileClose**: Closes an open file handle.
```

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

### ImageHeader.load_file

Source: https://intercreate.github.io/smpclient/latest/mcuboot

Loads an MCUBoot ImageHeader directly from a file path. It opens the file in binary read mode and uses `load_from` to parse the header.

```APIDOC
## ImageHeader.load_file

### Description
Loads an `ImageHeader` from a file located at the specified path. This method opens the file in binary read mode (`'rb'`) and then utilizes the `load_from` method to read and parse the image header data.

### Method
`staticmethod load_file(path: str) -> ImageHeader`

### Parameters
#### Path Parameters
- **path** (str) - Required - The file system path to the image header file.

#### Query Parameters
None

#### Request Body
None

### Request Example
```python
# Assuming 'firmware.bin' is the path to the firmware image file
image_header = ImageHeader.load_file('firmware.bin')
```

### Response
#### Success Response (ImageHeader object)
- **magic** (ImageMagic) - The magic number identifying the header.
- **load_addr** (int) - The load address for the image.
- **hdr_size** (int) - The size of the header.
- **protect_tlv_size** (int) - The size of the protected TLV area.
- **img_size** (int) - The size of the image.
- **flags** (IMAGE_F) - Flags associated with the image.
- **ver** (ImageVersion) - The version information of the image.

#### Response Example
```json
{
  "magic": "0xABCD",
  "load_addr": 1073741824,
  "hdr_size": 32,
  "protect_tlv_size": 16,
  "img_size": 102400,
  "flags": "0x01",
  "ver": {"major": 1, "minor": 0, "revision": 0, "build": 0}
}
```
```

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

### EchoWrite Request - Python

Source: https://intercreate.github.io/smpclient/latest/os_management

Defines the EchoWrite request for OS Management. Use this to echo data back from the managed OS.

```python
class EchoWrite(smpos.EchoWriteRequest, _OSGroupBase):
    _Response = smpos.EchoWriteResponse
```

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

### Initialize SMPTransport Buffer Size

Source: https://intercreate.github.io/smpclient/latest/transport/transport

Initializes the SMPTransport with a specified server transport buffer size. This configuration is essential for setting up the communication channel's capacity.

```python
def initialize(self, smp_server_transport_buffer_size: int) -> None:  # pragma: no cover
    """Initialize the `SMPTransport` with the server transport buffer size.

    Args:
        smp_server_transport_buffer_size: The SMP server transport buffer size, in 8-bit bytes.
    """
    self._smp_server_transport_buffer_size = smp_server_transport_buffer_size

```

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

### ImageVersion __str__ Method

Source: https://intercreate.github.io/smpclient/latest/mcuboot

The __str__ method provides a human-readable string representation of the ImageVersion object.

```python
def __str__(self) -> str:
    return f"{self.major}.{self.minor}.{self.revision}-build{self.build_num}"
```

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

### load_file

Source: https://intercreate.github.io/smpclient/latest/mcuboot

Loads MCUBoot ImageInfo from a file. It supports both binary files and Intel HEX format files. The function determines the file type based on the file extension.

```APIDOC
## load_file

### Description
Load MCUBoot `ImageInfo` from the file at `path`. Files with the `.hex` extension are treated as Intel HEX format. All other file extensions are treated as binary.

### Method
Python static method call

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Parameters
* **path** (str) - The path to the MCUBoot image file.

### Returns
* **ImageInfo** - An object containing the parsed image information, including header, TLVs, and protected TLVs.

### Raises
* **MCUBootImageError** - If there is an error during file parsing or if the hex2bin conversion fails.
```

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

### SMPClient Request Implementation

Source: https://intercreate.github.io/smpclient/latest

The internal implementation of the request method, including timeout handling and response parsing.

```python
async def request(
    self, request: SMPRequest[TRep, TEr1, TEr2], timeout_s: float | None = None
) -> TRep | TEr1 | TEr2:
    """Make an `SMPRequest` to the SMP server and return the Response or Error.

    Args:
        request: the `SMPRequest` to send
        timeout_s: the timeout for the request in seconds

    Returns:
        The typed and validated Response or Error

    Raises:
        TimeoutError: if the request times out
        SMPBadSequence: if the response sequence does not match the request sequence
        ValidationError: if the response cannot be parsed as a Response or Error

    Examples:
    Usage:

    ```python
    response = await client.request(EchoWrite(d="Hello, World!"))
    if success(response):
        print(f"Response: {response=}")
    elif error(response):
        print(f"Error: {response=}")
    else:
        assert_never(response)
    ```

    Type Safety and Exhaustiveness with Generic Typing:

    ```python
    response = await client.request(EchoWrite(d="Hello, World!"))
    reveal_type(response)
    # Revealed type is 'Union[EchoWriteResponse, EchoWriteErrorV1, EchoWriteErrorV2]'
    if success(response):
        reveal_type(response)
        # Revealed type is 'EchoWriteResponse'
    elif error(response):
        reveal_type(response)
        # Revealed type is 'Union[EchoWriteErrorV1, EchoWriteErrorV2]'
        if error_v1(response):
            reveal_type(response)
            # Revealed type is 'EchoWriteErrorV1'
        elif error_v2(response):
            reveal_type(response)
            # Revealed type is 'EchoWriteErrorV2'
        else:
            assert_never(response)
    else:
        assert_never(response)
    ```

    """
    timeout_s = timeout_s if timeout_s is not None else self._timeout_s

    try:
        async with timeout(timeout_s):
            frame = await self._transport.send_and_receive(request.BYTES)
    except asyncio.TimeoutError:
        timeout_message: Final = f"Timeout ({timeout_s}s) waiting for request {request}"
        logger.error(timeout_message)
        raise TimeoutError(timeout_message)

    header = smpheader.Header.loads(frame[: smpheader.Header.SIZE])

    if header.sequence != request.header.sequence:
        raise SMPBadSequence(
            f"Bad sequence {header.sequence}, expected {request.header.sequence}"
        )

    try:
        return request._Response.loads(frame)  # type: ignore
    except ValidationError:
        pass
    try:
        return request._ErrorV1.loads(frame)
    except ValidationError:
        pass
    try:
        return request._ErrorV2.loads(frame)
    except ValidationError:
        error_message = (
            f"Response could not by parsed as one of {request._Response}, "
            f"{request._ErrorV1}, or {request._ErrorV2}. {header=} {frame=}"
        )
        logger.error(error_message)
        raise ValidationError(error_message)
```

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

### File Upload API

Source: https://intercreate.github.io/smpclient/latest

Provides functionality to iteratively upload file data to a specified path on the SMP server. It yields the offset after each successful chunk upload.

```APIDOC
## POST /upload/file

### Description
Iteratively uploads file data to a specified `file_path` on the SMP server, yielding the offset after each chunk. Suitable for uploading arbitrary files.

### Method
POST

### Endpoint
/upload/file

### Parameters
#### Path Parameters
- **file_path** (str) - Required - The destination path for the file on the SMP server.

#### Query Parameters
- **timeout_s** (float) - Optional - The timeout duration for each file upload request.

### Request Body
(Implicitly handled by the `_maximize_file_upload_packet` method, which constructs the `FileUpload` object)

### Request Example
```python
# Example of how the internal FileUpload object might be structured
{
  "name": "/path/to/your/file.txt",
  "off": 0,
  "data": "",
  "len": 2048
}
```

### Response
#### Success Response (200)
- **off** (int) - The current offset of the uploaded data.

#### Response Example
```json
{
  "off": 1024
}
```

### Raises
- **SMPUploadError**: If the upload routine fails or if no offset is received.
```

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

### Load TLV Entries from File

Source: https://intercreate.github.io/smpclient/latest/mcuboot

Reads and parses TLV entries from a file following the ImageTLVInfo header. The number of bytes to read is determined by the `tlv_tot` attribute of the ImageTLVInfo instance.

```python
def load_tlvs_from(self, file: BytesIO | BufferedReader) -> list[ImageTLVValue]:
    """Read and parse the TLV entries that follow this header in `file`."""
    return ImageInfo.parse_tlvs(file.read(self.tlv_tot - IMAGE_TLV_INFO_STRUCT.size))
```

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

### Load ImageTLVInfo from File

Source: https://intercreate.github.io/smpclient/latest/mcuboot

Loads an ImageTLVInfo object by reading a specified number of bytes from a file-like object. This is a convenience method that calls the `loads` method.

```python
@staticmethod
def load_from(file: BytesIO | BufferedReader, magic: MagicT) -> ImageTLVInfo[MagicT]:
    """Load an `ImageTLVInfo` from a file."""
    return ImageTLVInfo.loads(file.read(IMAGE_TLV_INFO_STRUCT.size), magic)
```

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

### Execute Shell Command

Source: https://intercreate.github.io/smpclient/latest/shell_management

The Execute endpoint allows for the execution of shell commands via the SMP protocol.

```APIDOC
## Execute

### Description
Executes a shell command using the SMP Shell Management protocol.

### Method
POST

### Endpoint
/smp/shell/execute

### Request Body
- **command** (string) - Required - The shell command to be executed on the target device.
```

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

### Load ImageTLVInfo from Bytes

Source: https://intercreate.github.io/smpclient/latest/mcuboot

Loads an ImageTLVInfo object from a byte string. It validates the magic number and the total TLV size against expected values.

```python
@staticmethod
def loads(data: bytes, magic: MagicT) -> ImageTLVInfo[MagicT]:
    """Load an `ImageTLVInfo` from bytes."""
    parsed_magic, tlv_tot = IMAGE_TLV_INFO_STRUCT.unpack(data)

    if parsed_magic != magic:
        raise MCUBootImageError(
            f"Expected TLV info magic {hex(magic)}, got {hex(parsed_magic)}"
        )

    if tlv_tot < IMAGE_TLV_INFO_STRUCT.size:
        raise MCUBootImageError(
            f"TLV total size must be at least {IMAGE_TLV_INFO_STRUCT.size}, got {tlv_tot}"
        )

    return ImageTLVInfo(magic=magic, tlv_tot=tlv_tot)
```

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

### Settings Management Requests

Source: https://intercreate.github.io/smpclient/latest/settings_management

Overview of the request classes used for settings management operations.

```APIDOC
## ReadSetting

### Description
Reads a specific setting value.

### Request Class
ReadSetting (inherits from ReadSettingRequest)

### Response Class
ReadSettingResponse

## WriteSetting

### Description
Writes a value to a specific setting.

### Request Class
WriteSetting (inherits from WriteSettingRequest)

### Response Class
WriteSettingResponse

## DeleteSetting

### Description
Deletes a specific setting.

### Request Class
DeleteSetting (inherits from DeleteSettingRequest)

### Response Class
DeleteSettingResponse

## CommitSettings

### Description
Commits pending settings changes.

### Request Class
CommitSettings (inherits from CommitSettingsRequest)

### Response Class
CommitSettingsResponse

## LoadSettings

### Description
Loads settings from the device.

### Request Class
LoadSettings (inherits from LoadSettingsRequest)

### Response Class
LoadSettingsResponse

## SaveSettings

### Description
Saves current settings to the device.

### Request Class
SaveSettings (inherits from SaveSettingsRequest)

### Response Class
SaveSettingsResponse
```
Tokens:
Raw