[GitHub] microbuilder commented on a change in pull request #18: Added initial protocol description for NMP/SMP

[GitBox <gi...@apache.org>]

microbuilder commented on a change in pull request #18: Added initial protocol description for NMP/SMP
URL: https://github.com/apache/mynewt-mcumgr/pull/18#discussion_r241027189
 
 

 ##########
 File path: protocol.md
 ##########
 @@ -0,0 +1,240 @@
+# SMP (Simple Management Protocol) Protocol
+
+The `mcumgr` SMP server and `mcumgr-cli` SMP client tool ([source](https://github.com/apache/mynewt-mcumgr-cli))
+use a custom protocol to send commands and responses between the server and client using a
+variety of transports (currently TTY serial or BLE).
+
+The protocol isn't documented but the following information has been inferred
+from the source code available on Github and using the `-l DEBUG` flag When
+executing commands.
+
+## Source Code
+
+**SMP** is based on the earlier **NMP**, which is part of [Apache Mynewt](https://mynewt.apache.org/).
+
+The golang source for the original **newtmgr** is [available here](https://github.com/apache/mynewt-newtmgr),
+and can be used to provide some insight into how data is exchanged between the
+utility and the device under test.
+
+This repository (`mynewt-mcumgr`) implements an SMP server in **C**,
+and a new command-line SMP client called **mcumgr** was created at 
+[apache/mynewt-mcumgr](https://github.com/apache/mynewt-mcumgr).
+
+## SMP Frame Format
+
+TODO: High level introduction.
+
+### Endianness
+
+Frames are normally serialized as **Big Endian** when dealing with values > 8 bits. This is
+mandatory in NMP, but the SMP implementation does add support for **Little Endian** as an
+option at the struct level, as shown below.
+
+### Frame format
+
+Frames in SMP have the following format:
+
+```
+struct mgmt_hdr {
+#if __BYTE_ORDER__ == __ORDER_LITTLE_ENDIAN__
+    uint8_t  nh_op:3;           /* MGMT_OP_[...] */
+    uint8_t  _res1:5;
+#endif
+#if __BYTE_ORDER__ == __ORDER_BIG_ENDIAN__
+    uint8_t  _res1:5;
+    uint8_t  nh_op:3;           /* MGMT_OP_[...] */
+#endif
+    uint8_t  nh_flags;          /* Reserved for future flags */
+    uint16_t nh_len;            /* Length of the payload */
+    uint16_t nh_group;          /* MGMT_GROUP_ID_[...] */
+    uint8_t  nh_seq;            /* Sequence number */
+    uint8_t  nh_id;             /* Message ID within group */
+};
+```
+
+The NMP/newtmgr [go source](https://github.com/apache/mynewt-newtmgr/blob/master/nmxact/nmp/nmp.go) is as follows,
+without the option to select endianness:
+
+```
+type NmpHdr struct {
+	Op    uint8 /* 3 bits of opcode */
+	Flags uint8
+	Len   uint16
+	Group uint16
+	Seq   uint8
+	Id    uint8
+}
+```
+
+`nh_op` (or `Op` in newtmgr) can be one of the following values:
+
+```
+/** Opcodes; encoded in first byte of header. */
+#define MGMT_OP_READ            0
+#define MGMT_OP_READ_RSP        1
+#define MGMT_OP_WRITE           2
+#define MGMT_OP_WRITE_RSP       3
+```
+
+- **`op`**: The operation code
+- **`Flags`**: TBD
+- **`Len`**:  The payload len when `Data` is present
+- **`Group`**: Commands are organized into groups. Groups are defined
+  [here](https://github.com/apache/mynewt-mcumgr/blob/master/mgmt/include/mgmt/mgmt.h).
+- **`Seq`**: TBD
+- **`Id`**: The command ID to send. Commands in the default `Group` are defined
+  [here](https://github.com/apache/mynewt-mcumgr/blob/master/mgmt/include/mgmt/mgmt.h).
+- **`Data`**: The payload associated with the command `Id` above
 
 Review comment:
   Resolved in a subsequent addition to this PR, thanks. Earlier versions of the protocol had `Data` in the struct itself.

----------------------------------------------------------------
This is an automated message from the Apache Git Service.
To respond to the message, please log on GitHub and use the
URL above to go to the specific comment.
 
For queries about this service, please contact Infrastructure at:
users@infra.apache.org


With regards,
Apache Git Services