Skip to content

Commit 433ad4e

Browse files
ccollins476adccollins476ad
committed
Documentation.
1 parent 71f5c18 commit 433ad4e

File tree

3 files changed

+231
-1
lines changed

3 files changed

+231
-1
lines changed

‎README.md

Lines changed: 125 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1 +1,125 @@
1-
# mynewt-mcumgr
1+
# mcumgr
2+
3+
This is mcumgr, version 0.0.1
4+
5+
mcumgr is a management library for 32-bit MCUs. The goal of mcumgr is to
6+
define a common management infrastructure with pluggable transport and encoding
7+
components. In addition, mcumgr provides definitions and handlers for some
8+
core commands: image management, file system management, and OS managment.
9+
10+
mcumgr is operating system and hardware independent. It relies on hardware
11+
porting layers from the operating system it runs on. Currently, mcumgr runs on
12+
both the Apache Mynewt and Zephyr operating systems.
13+
14+
## Command line tool
15+
16+
The `mcumgr` command line tool is available at:
17+
https://github.com/apache/mynewt-mcumgr-cli. The tool is written in Go, and it
18+
is installed with the `go get` command:
19+
20+
```
21+
$ go get github.com/apache/mynewt-mcumgr-cli/mcumgr
22+
```
23+
24+
The `mcumgr` tool allows you to manage devices running an mcumgr server.
25+
26+
## Architecture
27+
28+
The mcumgr stack has the following layout:
29+
30+
```
31+
+---------------------+---------------------+
32+
| <command handlers> |
33+
+---------------------+---------------------+
34+
| mgmt |
35+
+---------------------+---------------------+
36+
| <transfer encoding(s)> |
37+
+---------------------+---------------------+
38+
| <transport(s)> |
39+
+---------------------+---------------------+
40+
```
41+
42+
Items enclosed in angled brackets represent generic components that can be plugged into mcumgr. The items in this stack diagram are defined below:
43+
* *Command handler*: Processes incoming mcumgr requests and generates corresponding responses. A command handler is associated with a single command type, defined by a (group ID, command ID) pair.
44+
* *mgmt*: The core of mcumgr; facilitates the passing of requests and responses between the generic command handlers and the concrete transports and transfer encodings.
45+
* *Transfer encoding*: Defines how mcumgr requests and responses are encoded on the wire.
46+
* *Transport*: Sends and receives mcumgr packets over a particular medium.
47+
48+
Each transport is configured with a single transfer encoding.
49+
50+
As an example, the sample application `smp_svr` uses the following components:
51+
52+
* Command handlers:
53+
* Image management (`img_mgmt`)
54+
* File system management (`fs_mgmt`)
55+
* OS management (`os_mgmt`)
56+
* Transfer/Transports protocols:
57+
* SMP/Bluetooth
58+
* SMP/Shell
59+
60+
yielding the following stack diagram:
61+
62+
```
63+
+--------------+--------------+-------------+
64+
| img_mgmt | fs_mgmt | os_mgmt |
65+
+--------------+--------------+-------------+
66+
| mgmt |
67+
+---------------------+---------------------+
68+
| SMP | SMP |
69+
+---------------------+---------------------+
70+
| Bluetooth | Shell |
71+
+---------------------+---------------------+
72+
```
73+
74+
## Command definition
75+
76+
An mcumgr request or response consists of the following two components:
77+
* mcumgr header
78+
* CBOR key-value map
79+
80+
How these two components are encoded and parsed depends on the transfer
81+
encoding used.
82+
83+
The mcumgr header structure is defined in `mgmt/include/mgmt/mgmt.h` as
84+
`struct mgmt_hdr`.
85+
86+
The contents of the CBOR key-value map are specified per command type.
87+
88+
## Supported transfer encodings
89+
90+
Mcumgr comes with one built-in transfer encoding: Simple Management Protocol (SMP). SMP requests and responses have a very basic structure. For details, see the comments at the top of `smp/include/smp/smp.h`.
91+
92+
## Supported transports
93+
94+
The mcumgr project defines two transports:
95+
* SMP/Console
96+
* SMP/Bluetooth
97+
98+
Particulars of these transports are specified in the following documents:
99+
* SMP/Console: `transports/smp-console.md`
100+
* SMP/Bluetooth: `transports/smp-bluetooth.md`
101+
102+
Implementations, being hardware- and OS-specified, are not included.
103+
104+
## Browsing
105+
106+
Information and documentation for mcumgr is stored within the source.
107+
108+
For more information in the source, here are some pointers:
109+
110+
- [cborattr](https://github.com/apache/mcumgr/tree/master/cborattr): Used for parsing incoming mcumgr requests. Destructures mcumgr packets and populates corresponding field variables.
111+
- [cmd](https://github.com/apache/mcumgr/tree/master/cmd): Built-in command handlers for the core mcumgr commands.
112+
- [ext](https://github.com/apache/mcumgr/tree/master/ext): Third-party libraries that mcumgr depends on.
113+
- [mgmt](https://github.com/apache/mcumgr/tree/master/mgmt): Code implementing the `mgmt` layer of mcumgr.
114+
- [samples](https://github.com/apache/mcumgr/tree/master/samples): Sample applications utilizing mcumgr.
115+
- [smp](https://github.com/apache/mcumgr/tree/master/smp): The built-in transfer encoding: Simple management protocol.
116+
117+
## Known issues
118+
119+
- (Zephyr) If the Bluetooth stack runs out of ACL transmit buffers while a large mcumgr response is being sent, the buffers never get freed. This appears to trigger a net_buf leak in the stack.
120+
121+
## Joining
122+
123+
Developers welcome!
124+
125+
* Our Slack channel: https://mynewt.slack.com/messages/C7Y3K0C2J

‎transport/smp-bluetooth.md

Lines changed: 50 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,50 @@
1+
# SMP over Bluetooth
2+
3+
This document specifies how the mcumgr Simple Management Procotol (SMP) is
4+
transmitted over Bluetooth.
5+
6+
## Overview
7+
8+
All SMP communication utilizes a single GATT characteristic. An SMP request is
9+
sent in the form of either 1) a GATT Write Command, or 2) a GATT Write Without
10+
Response command. An SMP response is sent in the form of a GATT Notification
11+
specifying the same characteristic that was written.
12+
13+
If an SMP request or response is too large to fit in a single GATT command, the
14+
sender fragments it across several commands. No additional framing is
15+
introduced when a request or response is fragmented; the payload is simply
16+
split among several commands. Since Bluetooth guarantees ordered delivery of
17+
packets, the SMP header in the first fragment contains sufficient information
18+
for reassembly.
19+
20+
## Services
21+
22+
### SMP service
23+
24+
UUID: `8D53DC1D-1DB7-4CD3-868B-8A527460AA84`
25+
26+
### Characteristics
27+
28+
#### SMP Characteristic
29+
30+
| Field | Value |
31+
| ----- | ----------------------------------------------------------------- |
32+
| Name | SMP |
33+
| Description | Used for both SMP requests and responses. |
34+
| Read | Excluded |
35+
| Write | Mandatory |
36+
| WriteWithoutResponse | Mandatory |
37+
| SignedWrite | Excluded |
38+
| Notify | Mandatory |
39+
| Indicate | Excluded |
40+
| WritableAuxiliaries | Excluded |
41+
| Broadcast | Excluded |
42+
| ExtendedProperties | |
43+
44+
As indicated, SMP requests can be sent in the form of either a Write or a Write
45+
Without Response. The Write Without Response form is generally preferred, as
46+
an application-layer response is always sent in the form of a Notification.
47+
The regular Write form is accepted in case the client requires a GATT response
48+
to initiate pairing.
49+
50+
Security for this characteristic is optional.

‎transport/smp-console.md

Lines changed: 56 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,56 @@
1+
# SMP over console
2+
3+
This document specifies how the mcumgr Simple Management Procotol (SMP) is
4+
transmitted over text consoles.
5+
6+
## Overview
7+
8+
Mcumgr packets sent over serial are fragmented into frames of 128 bytes or
9+
fewer.
10+
11+
The initial frame in a packet has the following format:
12+
13+
```
14+
offset 0: 0x06 0x09
15+
=== Begin base64 encoding ===
16+
offset 2: <16-bit packet-length>
17+
offset ?: <body>
18+
offset ?: <crc16> (if final frame)
19+
=== End base64 encoding ===
20+
offset ?: 0x0a (newline)
21+
```
22+
23+
All subsequent frames have the following format:
24+
25+
```
26+
offset 0: 0x04 0x14
27+
=== Begin base64 encoding ===
28+
offset 2: <body>
29+
offset ?: <crc16> (if final frame)
30+
=== End base64 encoding ===
31+
offset ?: 0x0a (newline)
32+
```
33+
34+
All integers are represented in big-endian. The packet fields are described
35+
below:
36+
37+
| Field | Description |
38+
| ----- | ----------- |
39+
| 0x06 0x09 | Byte pair indicating the start of a packet. |
40+
| 0x04 0x14 | Byte pair indicating the start of a continuation frame. |
41+
| Packet length | The combined total length of the *unencoded* body. |
42+
| Body | The actual SMP data (i.e., 8-byte header and CBOR key-value map). |
43+
| CRC16 | A CRC16 of the *unencoded* body of the entire packet. This field is only present in the final frame of a packet. |
44+
| Newline | A 0x0a byte; terminates a frame. |
45+
46+
The packet is fully received when <packet-length> bytes of body has been
47+
received.
48+
49+
## CRC details
50+
51+
The CRC16 should be calculated with the following parameters:
52+
53+
| Field | Value |
54+
| ------------- | ------------- |
55+
| Polynomial | 0x1021 |
56+
| Initial Value | 0 |

0 commit comments

Comments
 (0)