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 4c4c6de3a6c5e65c9dddd5f436c7ec4d0140aaaa
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.

Reply via email to