mcumgr-toolkit 0.8.0__cp310-abi3-win32.whl

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,5 @@
1
+ from .mcumgr_toolkit import *
2
+
3
+ __doc__ = mcumgr_toolkit.__doc__
4
+ if hasattr(mcumgr_toolkit, "__all__"):
5
+ __all__ = mcumgr_toolkit.__all__
@@ -0,0 +1,564 @@
1
+ # This file is automatically generated by pyo3_stub_gen
2
+ # ruff: noqa: E501, F401
3
+
4
+ import builtins
5
+ import collections.abc
6
+ import datetime
7
+ import enum
8
+ import typing
9
+
10
+ @typing.final
11
+ class FileChecksum:
12
+ r"""
13
+ Return value of `MCUmgrClient.fs_file_checksum`.
14
+ """
15
+ @property
16
+ def type(self) -> builtins.str:
17
+ r"""
18
+ type of hash/checksum that was performed
19
+ """
20
+ @property
21
+ def offset(self) -> builtins.int:
22
+ r"""
23
+ offset that hash/checksum calculation started at
24
+ """
25
+ @property
26
+ def length(self) -> builtins.int:
27
+ r"""
28
+ length of input data used for hash/checksum generation (in bytes)
29
+ """
30
+ @property
31
+ def output(self) -> bytes:
32
+ r"""
33
+ output hash/checksum
34
+ """
35
+
36
+ @typing.final
37
+ class FileChecksumProperties:
38
+ r"""
39
+ Properties of a hash/checksum algorithm
40
+ """
41
+ @property
42
+ def format(self) -> 'FileChecksumDataFormat':
43
+ r"""
44
+ format that the hash/checksum returns
45
+ """
46
+ @property
47
+ def size(self) -> builtins.int:
48
+ r"""
49
+ size (in bytes) of output hash/checksum response
50
+ """
51
+
52
+ @typing.final
53
+ class FileStatus:
54
+ r"""
55
+ Return value of `MCUmgrClient.fs_file_status`.
56
+ """
57
+ @property
58
+ def length(self) -> builtins.int:
59
+ r"""
60
+ length of file (in bytes)
61
+ """
62
+
63
+ @typing.final
64
+ class ImageState:
65
+ r"""
66
+ The state of an image slot
67
+ """
68
+ @property
69
+ def image(self) -> builtins.int:
70
+ r"""
71
+ image number
72
+ """
73
+ @property
74
+ def slot(self) -> builtins.int:
75
+ r"""
76
+ slot number within “image”
77
+ """
78
+ @property
79
+ def version(self) -> builtins.str:
80
+ r"""
81
+ string representing image version, as set with `imgtool`
82
+ """
83
+ @property
84
+ def hash(self) -> typing.Optional[bytes]:
85
+ r"""
86
+ SHA256 hash of the image header and body
87
+
88
+ Note that this will not be the same as the SHA256 of the whole file, it is the field in the
89
+ MCUboot TLV section that contains a hash of the data which is used for signature
90
+ verification purposes.
91
+ """
92
+ @property
93
+ def bootable(self) -> builtins.bool:
94
+ r"""
95
+ true if image has bootable flag set
96
+ """
97
+ @property
98
+ def pending(self) -> builtins.bool:
99
+ r"""
100
+ true if image is set for next swap
101
+ """
102
+ @property
103
+ def confirmed(self) -> builtins.bool:
104
+ r"""
105
+ true if image has been confirmed
106
+ """
107
+ @property
108
+ def active(self) -> builtins.bool:
109
+ r"""
110
+ true if image is currently active application
111
+ """
112
+ @property
113
+ def permanent(self) -> builtins.bool:
114
+ r"""
115
+ true if image is to stay in primary slot after the next boot
116
+ """
117
+
118
+ @typing.final
119
+ class MCUmgrClient:
120
+ r"""
121
+ A high-level client for Zephyr's MCUmgr SMP functionality
122
+ """
123
+ @staticmethod
124
+ def serial(serial: builtins.str, baud_rate: builtins.int = 115200, timeout_ms: builtins.int = 10000) -> 'MCUmgrClient':
125
+ r"""
126
+ Creates a new serial port based Zephyr MCUmgr SMP client.
127
+
128
+ ### Arguments
129
+
130
+ * `serial` - The identifier of the serial device. (Windows: `COMxx`, Linux: `/dev/ttyXX`)
131
+ * `baud_rate` - The baud rate of the serial port.
132
+ * `timeout_ms` - The communication timeout, in ms.
133
+ """
134
+ @staticmethod
135
+ def usb_serial(identifier: builtins.str, baud_rate: builtins.int = 115200, timeout_ms: builtins.int = 10000) -> 'MCUmgrClient':
136
+ r"""
137
+ Creates a Zephyr MCUmgr SMP client based on a USB serial port identified by VID:PID.
138
+
139
+ Useful for programming many devices in rapid succession, as Windows usually
140
+ gives each one a different COMxx identifier.
141
+
142
+ ### Arguments
143
+
144
+ * `identifier` - A regex that identifies the device.
145
+ * `baud_rate` - The baud rate the port should operate at.
146
+ * `timeout_ms` - The communication timeout, in ms.
147
+
148
+ ### Identifier examples
149
+
150
+ - `1234:89AB` - Vendor ID 1234, Product ID 89AB. Will fail if product has multiple serial ports.
151
+ - `1234:89AB:12` - Vendor ID 1234, Product ID 89AB, Interface 12.
152
+ - `1234:.*:[2-3]` - Vendor ID 1234, any Product Id, Interface 2 or 3.
153
+ """
154
+ def set_frame_size(self, smp_frame_size: builtins.int) -> None:
155
+ r"""
156
+ Configures the maximum SMP frame size that we can send to the device.
157
+
158
+ Must not exceed [`MCUMGR_TRANSPORT_NETBUF_SIZE`](https://github.com/zephyrproject-rtos/zephyr/blob/v4.2.1/subsys/mgmt/mcumgr/transport/Kconfig#L40),
159
+ otherwise we might crash the device.
160
+ """
161
+ def use_auto_frame_size(self) -> None:
162
+ r"""
163
+ Configures the maximum SMP frame size that we can send to the device automatically
164
+ by reading the value of [`MCUMGR_TRANSPORT_NETBUF_SIZE`](https://github.com/zephyrproject-rtos/zephyr/blob/v4.2.1/subsys/mgmt/mcumgr/transport/Kconfig#L40)
165
+ from the device.
166
+ """
167
+ def set_timeout_ms(self, timeout_ms: builtins.int) -> None:
168
+ r"""
169
+ Changes the communication timeout.
170
+
171
+ When the device does not respond to packets within the set
172
+ duration, an error will be raised.
173
+ """
174
+ def check_connection(self) -> None:
175
+ r"""
176
+ Checks if the device is alive and responding.
177
+
178
+ Runs a simple echo with random data and checks if the response matches.
179
+
180
+ Raises an error if the device is not alive and responding.
181
+ """
182
+ def firmware_update(self, firmware: bytes, checksum: typing.Optional[builtins.str | builtins.bytes] = None, bootloader_type: typing.Optional[typing.Literal['MCUboot']] = None, skip_reboot: builtins.bool = False, force_confirm: builtins.bool = False, upgrade_only: builtins.bool = False, progress: typing.Optional[collections.abc.Callable[[builtins.str, typing.Optional[builtins.tuple[builtins.int, builtins.int]]], None]] = None) -> None:
183
+ r"""
184
+ High-level firmware update routine.
185
+
186
+ ### Arguments
187
+
188
+ * `firmware` - The firmware image data.
189
+ * `checksum` - SHA256 of the firmware image. Optional.
190
+ * `bootloader_type` - The type of bootloader. Auto-detect bootloader if missing.
191
+ * `skip_reboot` - Do not reboot device after the update.
192
+ * `force_confirm` - Skip test boot and confirm directly.
193
+ * `upgrade_only` - Prevent firmware downgrades.
194
+ * `progress` - A callback that receives progress updates.
195
+ """
196
+ def os_echo(self, msg: builtins.str) -> builtins.str:
197
+ r"""
198
+ Sends a message to the device and expects the same message back as response.
199
+
200
+ This can be used as a sanity check for whether the device is connected and responsive.
201
+ """
202
+ def os_task_statistics(self) -> 'builtins.dict[builtins.str, TaskStatistics]':
203
+ r"""
204
+ Queries live task statistics
205
+
206
+ ### Note
207
+
208
+ Converts `stkuse` and `stksiz` to bytes.
209
+ Zephyr originally reports them as number of 4 byte words.
210
+
211
+ ### Return
212
+
213
+ A map of task names with their respective statistics
214
+ """
215
+ def os_set_datetime(self, datetime: datetime.datetime) -> None:
216
+ r"""
217
+ Sets the RTC of the device to the given datetime.
218
+
219
+ Uses the contained local time and discards timezone information.
220
+ """
221
+ def os_get_datetime(self) -> datetime.datetime:
222
+ r"""
223
+ Retrieves the device RTC's datetime.
224
+
225
+ Will not contain timezone information.
226
+ """
227
+ def os_system_reset(self, force: builtins.bool = False, boot_mode: typing.Optional[builtins.int] = None) -> None:
228
+ r"""
229
+ Issues a system reset.
230
+
231
+ ### Arguments
232
+
233
+ * `force` - Issues a force reset.
234
+ * `boot_mode` - Overwrites the default boot mode.
235
+
236
+ Known `boot_mode` values:
237
+ * `0` - Normal system boot
238
+ * `1` - Bootloader recovery mode
239
+
240
+ Note that `boot_mode` only works if [`MCUMGR_GRP_OS_RESET_BOOT_MODE`](https://docs.zephyrproject.org/latest/kconfig.html#CONFIG_MCUMGR_GRP_OS_RESET_BOOT_MODE) is enabled.
241
+ """
242
+ def os_mcumgr_parameters(self) -> 'MCUmgrParameters':
243
+ r"""
244
+ Fetch parameters from the MCUmgr library
245
+ """
246
+ def os_application_info(self, format: typing.Optional[builtins.str] = None) -> builtins.str:
247
+ r"""
248
+ Fetch information on the running image
249
+
250
+ Similar to Linux's `uname` command.
251
+
252
+ ### Arguments
253
+
254
+ * `format` - Format specifier for the returned response
255
+
256
+ For more information about the format specifier fields, see
257
+ the [SMP documentation](https://docs.zephyrproject.org/latest/services/device_mgmt/smp_groups/smp_group_0.html#os-application-info-request).
258
+ """
259
+ def os_bootloader_info(self) -> typing.Any:
260
+ r"""
261
+ Fetch information on the device's bootloader
262
+ """
263
+ def image_get_state(self) -> 'builtins.list[ImageState]':
264
+ r"""
265
+ Obtain a list of images with their current state.
266
+ """
267
+ def image_set_state(self, hash: typing.Optional[builtins.str | builtins.bytes] = None, confirm: builtins.bool = False) -> 'builtins.list[ImageState]':
268
+ r"""
269
+ Modify the current image state and return the new state
270
+
271
+ ### Arguments
272
+
273
+ * `hash` - the SHA256 id of the image.
274
+ * `confirm` - mark the given image as 'confirmed'
275
+
276
+ If `confirm` is `false`, perform a test boot with the given image and revert upon hard reset.
277
+
278
+ If `confirm` is `true`, boot to the given image and mark it as `confirmed`. If `hash` is omitted,
279
+ confirm the currently running image.
280
+
281
+ Note that `hash` will not be the same as the SHA256 of the whole firmware image,
282
+ it is the field in the MCUboot TLV section that contains a hash of the data
283
+ which is used for signature verification purposes.
284
+ """
285
+ def image_upload(self, data: bytes, image: typing.Optional[builtins.int] = None, checksum: typing.Optional[builtins.str | builtins.bytes] = None, upgrade_only: builtins.bool = False, progress: typing.Optional[collections.abc.Callable[[builtins.int, builtins.int], None]] = None) -> None:
286
+ r"""
287
+ Upload a firmware image to an image slot.
288
+
289
+ ### Arguments
290
+
291
+ * `data` - The firmware image data
292
+ * `image` - Selects target image on the device. Defaults to `0`.
293
+ * `checksum` - The SHA256 checksum of the image. If missing, will be computed from the image data.
294
+ * `upgrade_only` - If true, allow firmware upgrades only and reject downgrades.
295
+ * `progress` - A callable object that takes (transmitted, total) values as parameters.
296
+ Any return value is ignored. Raising an exception aborts the operation.
297
+
298
+ ### Performance
299
+
300
+ Uploading files with Zephyr's default parameters is slow.
301
+ You want to increase [`MCUMGR_TRANSPORT_NETBUF_SIZE`](https://github.com/zephyrproject-rtos/zephyr/blob/v4.2.1/subsys/mgmt/mcumgr/transport/Kconfig#L40)
302
+ to maybe `4096` and then enable larger chunking through either `set_frame_size`
303
+ or `use_auto_frame_size`.
304
+ """
305
+ def image_erase(self, slot: typing.Optional[builtins.int] = None) -> None:
306
+ r"""
307
+ Erase image slot on target device.
308
+
309
+ ### Arguments
310
+
311
+ * `slot` - The slot ID of the image to erase. Slot `1` if omitted.
312
+ """
313
+ def image_slot_info(self) -> 'builtins.list[SlotInfoImage]':
314
+ r"""
315
+ Obtain a list of available image slots.
316
+ """
317
+ def fs_file_download(self, name: builtins.str, progress: typing.Optional[collections.abc.Callable[[builtins.int, builtins.int], None]] = None) -> bytes:
318
+ r"""
319
+ Load a file from the device.
320
+
321
+ ### Arguments
322
+
323
+ * `name` - The full path of the file on the device.
324
+ * `progress` - A callable object that takes (transmitted, total) values as parameters.
325
+ Any return value is ignored. Raising an exception aborts the operation.
326
+
327
+ ### Return
328
+
329
+ The file content
330
+
331
+ ### Performance
332
+
333
+ Downloading files with Zephyr's default parameters is slow.
334
+ You want to increase [`MCUMGR_TRANSPORT_NETBUF_SIZE`](https://github.com/zephyrproject-rtos/zephyr/blob/v4.2.1/subsys/mgmt/mcumgr/transport/Kconfig#L40)
335
+ to maybe `4096` or larger.
336
+ """
337
+ def fs_file_upload(self, name: builtins.str, data: bytes, progress: typing.Optional[collections.abc.Callable[[builtins.int, builtins.int], None]] = None) -> None:
338
+ r"""
339
+ Write a file to the device.
340
+
341
+ ### Arguments
342
+
343
+ * `name` - The full path of the file on the device.
344
+ * `data` - The file content.
345
+ * `progress` - A callable object that takes (transmitted, total) values as parameters.
346
+ Any return value is ignored. Raising an exception aborts the operation.
347
+
348
+ ### Performance
349
+
350
+ Uploading files with Zephyr's default parameters is slow.
351
+ You want to increase [`MCUMGR_TRANSPORT_NETBUF_SIZE`](https://github.com/zephyrproject-rtos/zephyr/blob/v4.2.1/subsys/mgmt/mcumgr/transport/Kconfig#L40)
352
+ to maybe `4096` and then enable larger chunking through either `set_frame_size`
353
+ or `use_auto_frame_size`.
354
+ """
355
+ def fs_file_status(self, name: builtins.str) -> 'FileStatus':
356
+ r"""
357
+ Queries the file status
358
+ """
359
+ def fs_file_checksum(self, name: builtins.str, algorithm: typing.Optional[builtins.str] = None, offset: builtins.int = 0, length: typing.Optional[builtins.int] = None) -> 'FileChecksum':
360
+ r"""
361
+ Computes the hash/checksum of a file
362
+
363
+ For available algorithms, see `fs_supported_checksum_types`.
364
+
365
+ ### Arguments
366
+
367
+ * `name` - The absolute path of the file on the device
368
+ * `algorithm` - The hash/checksum algorithm to use, or default if None
369
+ * `offset` - How many bytes of the file to skip
370
+ * `length` - How many bytes to read after `offset`. None for the entire file.
371
+ """
372
+ def fs_supported_checksum_types(self) -> 'builtins.dict[builtins.str, FileChecksumProperties]':
373
+ r"""
374
+ Queries which hash/checksum algorithms are available on the target
375
+ """
376
+ def fs_file_close(self) -> None:
377
+ r"""
378
+ Close all device files MCUmgr has currently open
379
+ """
380
+ def shell_execute(self, argv: typing.Sequence[builtins.str]) -> builtins.str:
381
+ r"""
382
+ Run a shell command.
383
+
384
+ ### Arguments
385
+
386
+ * `argv` - The shell command to be executed.
387
+
388
+ ### Return
389
+
390
+ The command output
391
+ """
392
+ def zephyr_erase_storage(self) -> None:
393
+ r"""
394
+ Erase the `storage_partition` flash partition.
395
+ """
396
+ def raw_command(self, write_operation: builtins.bool, group_id: builtins.int, command_id: builtins.int, data: typing.Any) -> typing.Any:
397
+ r"""
398
+ Execute a raw MCUmgrCommand.
399
+
400
+ Only returns if no error happened, so the
401
+ user does not need to check for an `rc` or `err`
402
+ field in the response.
403
+
404
+ Read Zephyr's [SMP Protocol Specification](https://docs.zephyrproject.org/latest/services/device_mgmt/smp_protocol.html)
405
+ for more information.
406
+
407
+ ### Arguments
408
+
409
+ * `write_operation` - Whether the command is a read or write operation.
410
+ * `group_id` - The group ID of the command
411
+ * `command_id` - The command ID
412
+ * `data` - Anything that can be serialized as a proper packet payload.
413
+
414
+ ### Example
415
+
416
+ ```python
417
+ client.raw_command(True, 0, 0, {"d": "Hello!"})
418
+ # Returns: {'r': 'Hello!'}
419
+ ```
420
+ """
421
+ def __enter__(self) -> 'MCUmgrClient': ...
422
+ def __exit__(self, _exc_type: typing.Any, _exc_value: typing.Any, _traceback: typing.Any) -> builtins.bool:
423
+ r"""
424
+ Closes the connection
425
+ """
426
+
427
+ @typing.final
428
+ class MCUmgrParameters:
429
+ r"""
430
+ Return value of `MCUmgrClient.os_mcumgr_parameters`.
431
+ """
432
+ @property
433
+ def buf_size(self) -> builtins.int:
434
+ r"""
435
+ Single SMP buffer size, this includes SMP header and CBOR payload
436
+ """
437
+ @property
438
+ def buf_count(self) -> builtins.int:
439
+ r"""
440
+ Number of SMP buffers supported
441
+ """
442
+
443
+ @typing.final
444
+ class McubootImageInfo:
445
+ r"""
446
+ Information about an MCUboot firmware image
447
+ """
448
+ @property
449
+ def version(self) -> builtins.str:
450
+ r"""
451
+ Firmware version
452
+ """
453
+ @property
454
+ def hash(self) -> bytes:
455
+ r"""
456
+ The identifying hash for the firmware
457
+
458
+ Note that this will not be the same as the SHA256 of the whole file, it is the field in the
459
+ MCUboot TLV section that contains a hash of the data which is used for signature
460
+ verification purposes.
461
+ """
462
+
463
+ @typing.final
464
+ class SlotInfoImage:
465
+ r"""
466
+ Information about a firmware image type returned by `MCUmgrClient.image_slot_info`
467
+ """
468
+ @property
469
+ def image(self) -> builtins.int:
470
+ r"""
471
+ number of the image
472
+ """
473
+ @property
474
+ def slots(self) -> 'builtins.list[SlotInfoImageSlot]':
475
+ r"""
476
+ slots available for the image
477
+ """
478
+ @property
479
+ def max_image_size(self) -> typing.Optional[builtins.int]:
480
+ r"""
481
+ maximum size of an application that can be uploaded to that image number
482
+ """
483
+
484
+ @typing.final
485
+ class SlotInfoImageSlot:
486
+ r"""
487
+ Information about a slot that can hold a firmware image
488
+ """
489
+ @property
490
+ def slot(self) -> builtins.int:
491
+ r"""
492
+ slot inside the image being enumerated
493
+ """
494
+ @property
495
+ def size(self) -> builtins.int:
496
+ r"""
497
+ size of the slot
498
+ """
499
+ @property
500
+ def upload_image_id(self) -> typing.Optional[builtins.int]:
501
+ r"""
502
+ specifies the image ID that can be used by external tools to upload an image to that slot
503
+ """
504
+
505
+ @typing.final
506
+ class TaskStatistics:
507
+ r"""
508
+ Statistics of an MCU task/thread
509
+ """
510
+ @property
511
+ def prio(self) -> builtins.int:
512
+ r"""
513
+ task priority
514
+ """
515
+ @property
516
+ def tid(self) -> builtins.int:
517
+ r"""
518
+ numeric task ID
519
+ """
520
+ @property
521
+ def state(self) -> builtins.int:
522
+ r"""
523
+ numeric task state
524
+ """
525
+ @property
526
+ def stkuse(self) -> typing.Optional[builtins.int]:
527
+ r"""
528
+ task’s/thread’s stack usage
529
+ """
530
+ @property
531
+ def stksiz(self) -> typing.Optional[builtins.int]:
532
+ r"""
533
+ task’s/thread’s stack size
534
+ """
535
+ @property
536
+ def cswcnt(self) -> typing.Optional[builtins.int]:
537
+ r"""
538
+ task’s/thread’s context switches
539
+ """
540
+ @property
541
+ def runtime(self) -> typing.Optional[builtins.int]:
542
+ r"""
543
+ task’s/thread’s runtime in “ticks”
544
+ """
545
+
546
+ @typing.final
547
+ class FileChecksumDataFormat(enum.Enum):
548
+ r"""
549
+ Data format of the hash/checksum type
550
+ """
551
+ Numerical = ...
552
+ r"""
553
+ Data is a number
554
+ """
555
+ ByteArray = ...
556
+ r"""
557
+ Data is a bytes array
558
+ """
559
+
560
+ def mcuboot_get_image_info(image_data: bytes) -> 'McubootImageInfo':
561
+ r"""
562
+ Extract information from an MCUboot image file
563
+ """
564
+
Binary file
File without changes
@@ -0,0 +1,107 @@
1
+ Metadata-Version: 2.4
2
+ Name: mcumgr-toolkit
3
+ Version: 0.8.0
4
+ Classifier: Programming Language :: Python :: 3
5
+ Classifier: Programming Language :: Python :: 3 :: Only
6
+ Classifier: Programming Language :: Python :: 3.10
7
+ Classifier: Programming Language :: Python :: 3.11
8
+ Classifier: Programming Language :: Python :: 3.12
9
+ Classifier: Programming Language :: Python :: 3.13
10
+ Classifier: Programming Language :: Python :: 3.14
11
+ Classifier: Programming Language :: Rust
12
+ Classifier: License :: OSI Approved :: MIT License
13
+ Classifier: License :: OSI Approved :: Apache Software License
14
+ Classifier: Operating System :: OS Independent
15
+ Summary: Python API for Zephyr's MCUmgr protocol
16
+ Keywords: zephyr,mcumgr,smp
17
+ Author: Finomnis <finomnis@gmail.com>
18
+ Author-email: Finomnis <finomnis@gmail.com>
19
+ License: MIT OR Apache-2.0
20
+ Requires-Python: >=3.10
21
+ Description-Content-Type: text/markdown; charset=UTF-8; variant=GFM
22
+ Project-URL: Documentation, https://finomnis.github.io/mcumgr-toolkit
23
+ Project-URL: Issues, https://github.com/Finomnis/mcumgr-toolkit/issues
24
+ Project-URL: Repository, https://github.com/Finomnis/mcumgr-toolkit
25
+
26
+ # MCUmgr Client for Zephyr
27
+
28
+ [![Crates.io](https://img.shields.io/crates/v/mcumgr-toolkit)](https://crates.io/crates/mcumgr-toolkit)
29
+ [![PyPI - Version](https://img.shields.io/pypi/v/mcumgr_toolkit)](https://pypi.org/project/mcumgr-toolkit)
30
+ [![PyPI - Downloads](https://img.shields.io/pypi/dw/mcumgr-toolkit)](https://pypi.org/project/mcumgr-toolkit)
31
+ [![License](https://img.shields.io/crates/l/mcumgr-toolkit)](https://github.com/Finomnis/mcumgr-toolkit/blob/main/LICENSE-MIT)
32
+ [![Build Status](https://img.shields.io/github/actions/workflow/status/Finomnis/mcumgr-toolkit/ci.yml?branch=main)](https://github.com/Finomnis/mcumgr-toolkit/actions/workflows/ci.yml?query=branch%3Amain)
33
+ [![Docs Status](https://img.shields.io/github/actions/workflow/status/Finomnis/mcumgr-toolkit/python-docs.yml?branch=main&label=docs)](https://finomnis.github.io/mcumgr-toolkit)
34
+
35
+ This library provides a Rust-based Python API for Zephyr's [MCUmgr protocol](https://docs.zephyrproject.org/latest/services/device_mgmt/mcumgr.html).
36
+
37
+ It might be compatible with other MCUmgr/SMP-based systems, but it is developed with Zephyr in mind.
38
+
39
+ Its primary design goals are:
40
+ - Completeness
41
+ - cover all use cases of Zephyr's MCUmgr
42
+ - for implementation progress, see this [tracking issue](https://github.com/Finomnis/mcumgr-toolkit/issues/32)
43
+ - Performance
44
+ - use static memory and large buffers to prioritize performance
45
+ over memory footprint
46
+ - see further down for more information regarding performance
47
+ optimizations required on Zephyr side
48
+
49
+
50
+ ## Usage Example
51
+
52
+ Connect to a serial port:
53
+
54
+ ```python no_run
55
+ from mcumgr_toolkit import MCUmgrClient
56
+
57
+ with MCUmgrClient.serial("/dev/ttyACM0") as client:
58
+ client.use_auto_frame_size()
59
+
60
+ print(client.os_echo("Hello world!"))
61
+ ```
62
+
63
+ ```none
64
+ Hello world!
65
+ ```
66
+
67
+ Or a USB-based serial port:
68
+
69
+ ```python no_run
70
+ from mcumgr_toolkit import MCUmgrClient
71
+
72
+ with MCUmgrClient.usb_serial("2fe3:0004") as client:
73
+ client.use_auto_frame_size()
74
+
75
+ print(client.os_echo("Hello world!"))
76
+ ```
77
+
78
+ ```none
79
+ Hello world!
80
+ ```
81
+
82
+ For more information, take a look at the [API reference](https://finomnis.github.io/mcumgr-toolkit).
83
+
84
+ ## Performance
85
+
86
+ Zephyr's default buffer sizes are quite small and reduce the read/write performance drastically.
87
+
88
+ The central most important setting is [`MCUMGR_TRANSPORT_NETBUF_SIZE`](https://github.com/zephyrproject-rtos/zephyr/blob/v4.2.1/subsys/mgmt/mcumgr/transport/Kconfig#L40). Its default of 384 bytes is very limiting, both for performance and as cutoff for large responses, like `os_task_statistics()` or some shell commands.
89
+
90
+ Be aware that changing this value also requires an increase of `MCUMGR_TRANSPORT_WORKQUEUE_STACK_SIZE` to prevent overflow crashes.
91
+
92
+ In practice, I found that the following values work quite well (on i.MX RT1060)
93
+ and give me 410 KB/s read and 120 KB/s write throughput, which is an order of magnitude faster than the default settings.
94
+
95
+ ```kconfig
96
+ CONFIG_MCUMGR_TRANSPORT_NETBUF_SIZE=4096
97
+ CONFIG_MCUMGR_TRANSPORT_WORKQUEUE_STACK_SIZE=8192
98
+ ```
99
+
100
+ If the experience differs on other chips, please open an issue and let me know.
101
+
102
+ ## Contributions
103
+
104
+ Contributions are welcome!
105
+
106
+ I primarily wrote this crate for myself, so any ideas for improvements are greatly appreciated.
107
+
@@ -0,0 +1,7 @@
1
+ mcumgr_toolkit\__init__.py,sha256=aNpktJ85aHlzINiO7hf6o5VM4_BTKwfM5ALW9kWbqyk,139
2
+ mcumgr_toolkit\__init__.pyi,sha256=m_K6yfQmHAgEpPbf6vZHYrpq2u8Sd2i9amSouVLoodE,20324
3
+ mcumgr_toolkit\mcumgr_toolkit.pyd,sha256=NkyJrXWp4phC1IqPrnSVhYDWV7vnbNw6BNHQWPFV37g,2546688
4
+ mcumgr_toolkit\py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
5
+ mcumgr_toolkit-0.8.0.dist-info\METADATA,sha256=buJyXA4IZQcdPoSsLasvp0al4Q9_9jV1gTYnukSEW30,4431
6
+ mcumgr_toolkit-0.8.0.dist-info\WHEEL,sha256=z9yqb7908wvFs7GY83MYuVP32iUSjiPZrYKqUOj5aiM,92
7
+ mcumgr_toolkit-0.8.0.dist-info\RECORD,,
@@ -0,0 +1,4 @@
1
+ Wheel-Version: 1.0
2
+ Generator: maturin (1.11.5)
3
+ Root-Is-Purelib: false
4
+ Tag: cp310-abi3-win32