README-mynewt.md
1## Building and using mcumgr with Apache Mynewt
2
3NOTE: The *mcumgr* library consists of functionality that is already present in
4the `apache-mynewt-core` repo. There is currently no need to use the external
5*mcumgr* library with Mynewt, as the functionality is already built in to the
6OS. To use this library with a Mynewt application, you will need to remove the
7duplicate functionality from your copy of the `apache-mynewt-core` repo.
8
9### Configuration
10
11To use *mcumgr*, your Mynewt app needs to be configured to use:
121. An mcumgr transfer encoding
132. An mcumgr transport
143. (optional) Command handlers.
15
16This is done by adding the necessary dependencies to your app or target. The following list of dependencies adds support for the SMP transfer encoding, the Bluetooth and shell transports, and all the built-in command handlers:
17
18```
19 - '@apache-mynewt-core/mgmt/smp/transport/ble'
20 - '@apache-mynewt-core/mgmt/smp/transport/smp_shell'
21 - '@mynewt-mcumgr/cmd/fs_mgmt'
22 - '@mynewt-mcumgr/cmd/img_mgmt'
23 - '@mynewt-mcumgr/cmd/os_mgmt'
24 - '@mynewt-mcumgr/smp'
25```
26
27For an example of an app that uses mcumgr, see the `smp_svr` sample app in `samples/smp_svr/mynewt`.
28
29### Building
30
31With the necessary dependencies in place, your project can be built using the usual `newt build <target-name>` or `newt run <target-name>`
32
README-zephyr.md
1## Using mcumgr with Zephyr
2
3### Configuration
4
5The `samples/smp_svr/zephyr/prj.conf` file provides a good starting point for
6configuring an application to use *mcumgr*. The major configuration settings
7are described below:
8
9| Setting | Description | Default |
10| ------------- | ------------- | ------- |
11| `CONFIG_MCUMGR` | Enable the mcumgr management library. | n |
12| `CONFIG_MCUMGR_CMD_FS_MGMT` | Enable mcumgr handlers for file management | n |
13| `CONFIG_MCUMGR_CMD_IMG_MGMT` | Enable mcumgr handlers for image management | n |
14| `CONFIG_MCUMGR_CMD_LOG_MGMT` | Enable mcumgr handlers for log management | n |
15| `CONFIG_MCUMGR_CMD_OS_MGMT` | Enable mcumgr handlers for OS management | n |
16
README.md
1# mcumgr
2
3This is mcumgr, version 0.2.0
4
5mcumgr is a management library for 32-bit MCUs. The goal of mcumgr is to
6define a common management infrastructure with pluggable transport and encoding
7components. In addition, mcumgr provides definitions and handlers for some
8core commands: image management, file system management, and OS management.
9
10mcumgr is operating system and hardware independent. It relies on hardware
11porting layers from the operating system it runs on. Currently, mcumgr runs on
12both the Apache Mynewt and Zephyr operating systems.
13
14## Getting started
15
16For tips on using mcumgr with your particular OS, see the appropriate file from
17the list below:
18
19* [Mynewt](README-mynewt.md)
20* [Zephyr](README-zephyr.md)
21
22## Dependencies
23
24To use mcumgr's image management support, your device must be running version
251.1.0 or later of the [MCUboot boot
26loader](https://github.com/runtimeco/mcuboot). The other mcumgr features do
27not require MCUboot.
28
29## Command line tool
30
31The `mcumgr` command line tool is available at:
32https://github.com/apache/mynewt-mcumgr-cli. The command line tool requires [Go
331.7 or later](https://golang.org/dl/). Once Go is installed and set up on your
34system, you can install the mcumgr CLI tool by issuing the following `go get`
35command:
36
37```
38$ go get github.com/apache/mynewt-mcumgr-cli/mcumgr
39```
40
41The `mcumgr` tool allows you to manage devices running an mcumgr server.
42
43## Architecture
44
45The mcumgr stack has the following layout:
46
47```
48+---------------------+---------------------+
49| <command handlers> |
50+---------------------+---------------------+
51| mgmt |
52+---------------------+---------------------+
53| <transfer encoding(s)> |
54+---------------------+---------------------+
55| <transport(s)> |
56+---------------------+---------------------+
57```
58
59Items enclosed in angled brackets represent generic components that can be plugged into mcumgr. The items in this stack diagram are defined below:
60* *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.
61* *mgmt*: The core of mcumgr; facilitates the passing of requests and responses between the generic command handlers and the concrete transports and transfer encodings.
62* *Transfer encoding*: Defines how mcumgr requests and responses are encoded on the wire.
63* *Transport*: Sends and receives mcumgr packets over a particular medium.
64
65Each transport is configured with a single transfer encoding.
66
67As an example, the sample application `smp_svr` uses the following components:
68
69* Command handlers:
70 * Image management (`img_mgmt`)
71 * File system management (`fs_mgmt`)
72 * Log management (`log_mgmt`)
73 * OS management (`os_mgmt`)
74* Transfer/Transports protocols:
75 * SMP/Bluetooth
76 * SMP/Shell
77
78yielding the following stack diagram:
79
80```
81+----------+----------+----------+----------+
82| img_mgmt | fs_mgmt | log_mgmt | os_mgmt |
83+----------+----------+----------+----------+
84| mgmt |
85+---------------------+---------------------+
86| SMP | SMP |
87+---------------------+---------------------+
88| Bluetooth | Shell |
89+---------------------+---------------------+
90```
91
92## Command definition
93
94An mcumgr request or response consists of the following two components:
95* mcumgr header
96* CBOR key-value map
97
98How these two components are encoded and parsed depends on the transfer
99encoding used.
100
101The mcumgr header structure is defined in `mgmt/include/mgmt/mgmt.h` as
102`struct mgmt_hdr`.
103
104The contents of the CBOR key-value map are specified per command type.
105
106## Supported transfer encodings
107
108Mcumgr comes with one built-in transfer encoding: Simple Management Protocol
109(SMP). SMP requests and responses have a very basic structure. For details,
110see the comments at the top of `smp/include/smp/smp.h`.
111
112## Supported transports
113
114The mcumgr project defines two transports:
115* [SMP/Console](transport/smp-console.md)
116* [SMP/Bluetooth](transport/smp-bluetooth.md)
117
118Implementations, being hardware- and OS-specific, are not included.
119
120## Browsing
121
122Information and documentation for mcumgr is stored within the source.
123
124For more information in the source, here are some pointers:
125
126- [cborattr](cborattr): Used for parsing incoming mcumgr requests. Destructures mcumgr packets and populates corresponding field variables.
127- [cmd](cmd): Built-in command handlers for the core mcumgr commands.
128- [ext](ext): Third-party libraries that mcumgr depends on.
129- [mgmt](mgmt): Code implementing the `mgmt` layer of mcumgr.
130- [samples](samples): Sample applications utilizing mcumgr.
131- [smp](smp): The built-in transfer encoding: Simple management protocol.
132
133## Joining
134
135Developers welcome!
136
137* Our Slack channel: https://mynewt.slack.com/messages/C7Y3K0C2J
138
