mcumgr-toolkit 0.8.0__cp310-abi3-musllinux_1_2_aarch64.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.
- mcumgr_toolkit/__init__.py +5 -0
- mcumgr_toolkit/__init__.pyi +564 -0
- mcumgr_toolkit/mcumgr_toolkit.abi3.so +0 -0
- mcumgr_toolkit/py.typed +0 -0
- mcumgr_toolkit-0.8.0.dist-info/METADATA +107 -0
- mcumgr_toolkit-0.8.0.dist-info/RECORD +8 -0
- mcumgr_toolkit-0.8.0.dist-info/WHEEL +4 -0
- mcumgr_toolkit.libs/libgcc_s-0bf60adc.so.1 +0 -0
|
@@ -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
|
mcumgr_toolkit/py.typed
ADDED
|
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
|
+
[](https://crates.io/crates/mcumgr-toolkit)
|
|
29
|
+
[](https://pypi.org/project/mcumgr-toolkit)
|
|
30
|
+
[](https://pypi.org/project/mcumgr-toolkit)
|
|
31
|
+
[](https://github.com/Finomnis/mcumgr-toolkit/blob/main/LICENSE-MIT)
|
|
32
|
+
[](https://github.com/Finomnis/mcumgr-toolkit/actions/workflows/ci.yml?query=branch%3Amain)
|
|
33
|
+
[](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,8 @@
|
|
|
1
|
+
mcumgr_toolkit/__init__.py,sha256=aNpktJ85aHlzINiO7hf6o5VM4_BTKwfM5ALW9kWbqyk,139
|
|
2
|
+
mcumgr_toolkit/__init__.pyi,sha256=4M7x1y7dj_ugdnE28pi9cPMce_5mUbibKnGd2ytBJW4,19760
|
|
3
|
+
mcumgr_toolkit/mcumgr_toolkit.abi3.so,sha256=iTUBa44pAbiicZpdLaFkyeLJw0YOGXCcU-X76mzUj5E,4656561
|
|
4
|
+
mcumgr_toolkit/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
|
|
5
|
+
mcumgr_toolkit-0.8.0.dist-info/METADATA,sha256=KqzJ9lkiBfcsZT0HdjKDBQQ2hv4JSAd_LsPDNEnc1ws,4350
|
|
6
|
+
mcumgr_toolkit-0.8.0.dist-info/WHEEL,sha256=Ks4MlrbXuBUzn0Sg1pSlfobz-J5L_KK83ofsy7dBTdk,108
|
|
7
|
+
mcumgr_toolkit.libs/libgcc_s-0bf60adc.so.1,sha256=9fhX5YpiwtHdsiLMLz77Pw9jjIEGriteV7UOUrrwvpk,527681
|
|
8
|
+
mcumgr_toolkit-0.8.0.dist-info/RECORD,,
|
|
Binary file
|