This is an automated email from the ASF dual-hosted git repository.
ccollins pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/mynewt-mcumgr.git
commit 373dcb18309a2a42a9819efd887596a3c0496b40
Author: Christopher Collins <ccoll...@apache.org>
AuthorDate: Wed Jan 17 17:16:10 2018 -0800
Documentation.
---
README.md | 126 ++++++++++++++++++++++++++++++++++++++++++++-
transport/smp-bluetooth.md | 50 ++++++++++++++++++
transport/smp-console.md | 56 ++++++++++++++++++++
3 files changed, 231 insertions(+), 1 deletion(-)
diff --git a/README.md b/README.md
index 3a9710e..12141dc 100644
--- a/README.md
+++ b/README.md
@@ -1 +1,125 @@
-# mynewt-mcumgr
+# mcumgr
+
+This is mcumgr, version 0.0.1
+
+mcumgr is a management library for 32-bit MCUs. The goal of mcumgr is to
+define a common management infrastructure with pluggable transport and encoding
+components. In addition, mcumgr provides definitions and handlers for some
+core commands: image management, file system management, and OS managment.
+
+mcumgr is operating system and hardware independent. It relies on hardware
+porting layers from the operating system it runs on. Currently, mcumgr runs on
+both the Apache Mynewt and Zephyr operating systems.
+
+## Command line tool
+
+The `mcumgr` command line tool is available at:
+https://github.com/apache/mynewt-mcumgr-cli. The tool is written in Go, and it
+is installed with the `go get` command:
+
+```
+$ go get github.com/apache/mynewt-mcumgr-cli/mcumgr
+```
+
+The `mcumgr` tool allows you to manage devices running an mcumgr server.
+
+## Architecture
+
+The mcumgr stack has the following layout:
+
+```
++---------------------+---------------------+
+| <command handlers> |
++---------------------+---------------------+
+| mgmt |
++---------------------+---------------------+
+| <transfer encoding(s)> |
++---------------------+---------------------+
+| <transport(s)> |
++---------------------+---------------------+
+```
+
+Items enclosed in angled brackets represent generic components that can be
plugged into mcumgr. The items in this stack diagram are defined below:
+* *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.
+* *mgmt*: The core of mcumgr; facilitates the passing of requests and
responses between the generic command handlers and the concrete transports and
transfer encodings.
+* *Transfer encoding*: Defines how mcumgr requests and responses are encoded
on the wire.
+* *Transport*: Sends and receives mcumgr packets over a particular medium.
+
+Each transport is configured with a single transfer encoding.
+
+As an example, the sample application `smp_svr` uses the following components:
+
+* Command handlers:
+ * Image management (`img_mgmt`)
+ * File system management (`fs_mgmt`)
+ * OS management (`os_mgmt`)
+* Transfer/Transports protocols:
+ * SMP/Bluetooth
+ * SMP/Shell
+
+yielding the following stack diagram:
+
+```
++--------------+--------------+-------------+
+| img_mgmt | fs_mgmt | os_mgmt |
++--------------+--------------+-------------+
+| mgmt |
++---------------------+---------------------+
+| SMP | SMP |
++---------------------+---------------------+
+| Bluetooth | Shell |
++---------------------+---------------------+
+```
+
+## Command definition
+
+An mcumgr request or response consists of the following two components:
+* mcumgr header
+* CBOR key-value map
+
+How these two components are encoded and parsed depends on the transfer
+encoding used.
+
+The mcumgr header structure is defined in `mgmt/include/mgmt/mgmt.h` as
+`struct mgmt_hdr`.
+
+The contents of the CBOR key-value map are specified per command type.
+
+## Supported transfer encodings
+
+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`.
+
+## Supported transports
+
+The mcumgr project defines two transports:
+ * SMP/Console
+ * SMP/Bluetooth
+
+Particulars of these transports are specified in the following documents:
+ * SMP/Console: `transports/smp-console.md`
+ * SMP/Bluetooth: `transports/smp-bluetooth.md`
+
+Implementations, being hardware- and OS-specified, are not included.
+
+## Browsing
+
+Information and documentation for mcumgr is stored within the source.
+
+For more information in the source, here are some pointers:
+
+- [cborattr](https://github.com/apache/mcumgr/tree/master/cborattr): Used for
parsing incoming mcumgr requests. Destructures mcumgr packets and populates
corresponding field variables.
+- [cmd](https://github.com/apache/mcumgr/tree/master/cmd): Built-in command
handlers for the core mcumgr commands.
+- [ext](https://github.com/apache/mcumgr/tree/master/ext): Third-party
libraries that mcumgr depends on.
+- [mgmt](https://github.com/apache/mcumgr/tree/master/mgmt): Code implementing
the `mgmt` layer of mcumgr.
+- [samples](https://github.com/apache/mcumgr/tree/master/samples): Sample
applications utilizing mcumgr.
+- [smp](https://github.com/apache/mcumgr/tree/master/smp): The built-in
transfer encoding: Simple management protocol.
+
+## Known issues
+
+- (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.
+
+## Joining
+
+Developers welcome!
+
+* Our Slack channel: https://mynewt.slack.com/messages/C7Y3K0C2J
diff --git a/transport/smp-bluetooth.md b/transport/smp-bluetooth.md
new file mode 100644
index 0000000..029d995
--- /dev/null
+++ b/transport/smp-bluetooth.md
@@ -0,0 +1,50 @@
+# SMP over Bluetooth
+
+This document specifies how the mcumgr Simple Management Procotol (SMP) is
+transmitted over Bluetooth.
+
+## Overview
+
+All SMP communication utilizes a single GATT characteristic. An SMP request is
+sent in the form of either 1) a GATT Write Command, or 2) a GATT Write Without
+Response command. An SMP response is sent in the form of a GATT Notification
+specifying the same characteristic that was written.
+
+If an SMP request or response is too large to fit in a single GATT command, the
+sender fragments it across several commands. No additional framing is
+introduced when a request or response is fragmented; the payload is simply
+split among several commands. Since Bluetooth guarantees ordered delivery of
+packets, the SMP header in the first fragment contains sufficient information
+for reassembly.
+
+## Services
+
+### SMP service
+
+UUID: `8D53DC1D-1DB7-4CD3-868B-8A527460AA84`
+
+### Characteristics
+
+#### SMP Characteristic
+
+| Field | Value |
+| ----- | ----------------------------------------------------------------- |
+| Name | SMP |
+| Description | Used for both SMP requests and responses. |
+| Read | Excluded |
+| Write | Mandatory |
+| WriteWithoutResponse | Mandatory |
+| SignedWrite | Excluded |
+| Notify | Mandatory |
+| Indicate | Excluded |
+| WritableAuxiliaries | Excluded |
+| Broadcast | Excluded |
+| ExtendedProperties | |
+
+As indicated, SMP requests can be sent in the form of either a Write or a Write
+Without Response. The Write Without Response form is generally preferred, as
+an application-layer response is always sent in the form of a Notification.
+The regular Write form is accepted in case the client requires a GATT response
+to initiate pairing.
+
+Security for this characteristic is optional.
diff --git a/transport/smp-console.md b/transport/smp-console.md
new file mode 100644
index 0000000..cbf9b47
--- /dev/null
+++ b/transport/smp-console.md
@@ -0,0 +1,56 @@
+# SMP over console
+
+This document specifies how the mcumgr Simple Management Procotol (SMP) is
+transmitted over text consoles.
+
+## Overview
+
+Mcumgr packets sent over serial are fragmented into frames of 128 bytes or
+fewer.
+
+The initial frame in a packet has the following format:
+
+```
+ offset 0: 0x06 0x09
+ === Begin base64 encoding ===
+ offset 2: <16-bit packet-length>
+ offset ?: <body>
+ offset ?: <crc16> (if final frame)
+ === End base64 encoding ===
+ offset ?: 0x0a (newline)
+```
+
+All subsequent frames have the following format:
+
+```
+ offset 0: 0x04 0x14
+ === Begin base64 encoding ===
+ offset 2: <body>
+ offset ?: <crc16> (if final frame)
+ === End base64 encoding ===
+ offset ?: 0x0a (newline)
+```
+
+All integers are represented in big-endian. The packet fields are described
+below:
+
+| Field | Description |
+| ----- | ----------- |
+| 0x06 0x09 | Byte pair indicating the start of a packet. |
+| 0x04 0x14 | Byte pair indicating the start of a continuation frame. |
+| Packet length | The combined total length of the *unencoded* body. |
+| Body | The actual SMP data (i.e., 8-byte header and CBOR key-value map). |
+| CRC16 | A CRC16 of the *unencoded* body of the entire packet. This field is
only present in the final frame of a packet. |
+| Newline | A 0x0a byte; terminates a frame. |
+
+The packet is fully received when <packet-length> bytes of body has been
+received.
+
+## CRC details
+
+The CRC16 should be calculated with the following parameters:
+
+| Field | Value |
+| ------------- | ------------- |
+| Polynomial | 0x1021 |
+| Initial Value | 0 |
--
To stop receiving notification emails like this one, please contact
ccoll...@apache.org.
