You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@mynewt.apache.org by ad...@apache.org on 2016/12/16 01:50:28 UTC
[2/3] incubator-mynewt-site git commit: Updated Newt Manager module
with diagram
Updated Newt Manager module with diagram
Project: http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/repo
Commit: http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/commit/a8067a50
Tree: http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/tree/a8067a50
Diff: http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/diff/a8067a50
Branch: refs/heads/develop
Commit: a8067a50b0a00fccd29959b922b0bd5831f08e41
Parents: 7cd8068
Author: aditihilbert <ad...@runtime.io>
Authored: Thu Dec 15 17:48:41 2016 -0800
Committer: aditihilbert <ad...@runtime.io>
Committed: Thu Dec 15 17:48:41 2016 -0800
----------------------------------------------------------------------
docs/os/modules/devmgmt/device-mgmt.png | Bin 0 -> 77155 bytes
docs/os/modules/devmgmt/newtmgr.md | 21 ++++
docs/os/modules/devmgmt/oicmgr.md | 87 +++++++++++++++++
docs/os/modules/newtmgr.md | 139 ---------------------------
docs/os/modules/newtmgr/newtmgr.md | 112 ---------------------
mkdocs.yml | 5 +-
6 files changed, 111 insertions(+), 253 deletions(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/a8067a50/docs/os/modules/devmgmt/device-mgmt.png
----------------------------------------------------------------------
diff --git a/docs/os/modules/devmgmt/device-mgmt.png b/docs/os/modules/devmgmt/device-mgmt.png
new file mode 100644
index 0000000..534d97f
Binary files /dev/null and b/docs/os/modules/devmgmt/device-mgmt.png differ
http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/a8067a50/docs/os/modules/devmgmt/newtmgr.md
----------------------------------------------------------------------
diff --git a/docs/os/modules/devmgmt/newtmgr.md b/docs/os/modules/devmgmt/newtmgr.md
new file mode 100644
index 0000000..ad775a1
--- /dev/null
+++ b/docs/os/modules/devmgmt/newtmgr.md
@@ -0,0 +1,21 @@
+## Newt Manager
+
+Newt Manager is the protocol that enables your Mynewt application to communicate remotely with your device running the Mynewt OS in order to configure, manage, conduct maintenance, and monitor it. The core device management module is called `mgmt` and offers multiple options for invoking the appropriate newt manager commands for various operations on the device e.g. enabling and collecting logs, configuring and retrieving stats, resetting the device etc.
+
+1. Use the `newtmgr` package if reduced code footprint is your primary requirement and you do not have interoperability requirements upstream for device information, discovery, and connectivity.
+2. Use the `oicmgr` package if interoperability and standards-based connectivity for device interaction is your primary requirement. This package supports the OIC (Open Interconnect Consortium) Specification 1.1.0 framework from Open Connectivity Foundation (OCF).
+
+### Invoking Newt Manager commands
+
+The diagram below indicates the two options available to the application developer to issue Newt Manager commands ('newtmgr commmands`) on a Mynewt device. The application may leverage the `newtmgr` framework or the `oicmgr` framework to call the newtmgr commands. The latter is described in the next chapter.
+
+
+
+### newtmgr
+
+The newtmgr framework uses a simple request and response message format to send commands to the device. A message
+consists of an eight byte header and the message payload. The message header specifies the newtmgr command.
+The message payload contains the newtmgr request/response data and is encoded in
+CBOR (Concise Binary Object Representation) format. newtmgr supports BLE and serial connections.
+
+The newtmgr framework has a smaller code size and memory footprint than oicmgr but does not support open connectivity.
http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/a8067a50/docs/os/modules/devmgmt/oicmgr.md
----------------------------------------------------------------------
diff --git a/docs/os/modules/devmgmt/oicmgr.md b/docs/os/modules/devmgmt/oicmgr.md
new file mode 100644
index 0000000..96186bd
--- /dev/null
+++ b/docs/os/modules/devmgmt/oicmgr.md
@@ -0,0 +1,87 @@
+## Using the OIC framework
+
+Apache Mynewt includes support for the OIC interoperability standard through the `oicmgr` framework. Mynewt defines and exposes oicmgr as an OIC Server resource with the following identity and properties:
+<br>
+<table style="width:50%" align="center">
+<tr>
+<td>**URI**</td>
+<td>/omgr</td>
+</tr>
+<tr>
+<td>**Resource Type**(rt)</td>
+<td>x.mynewt.nmgr</td>
+</tr>
+<td>**Interface**(if)</td>
+<td>oic.if_rw (default), oic.if.baseline</td>
+</tr>
+<td>**Discoverable**</td>
+<td>Yes</td>
+</tr>
+</table>
+The newtmgr application tool uses CoAP (Constrained Application Protocol) requests to send commands to oicmgr.
+It sends a CoAP request for **/omgr** as follows:
+
+* Specifies the newtmgr command to execute in the URI query string.
+* Uses a GET method for newtmgr commands that retreive information
+from your application, for example, the ```taskstats``` and ```mpstats``` commands.
+* Uses a PUT method for newtmgr commands that send data to or modify the state of your application,
+for example, the ```echo``` or ```datetime``` commands.
+* Sends the CBOR-encoded command request data in the CoAP message payload.
+
+The `oicmgr` framework supports transport over BLE, serial, and IP connections to the device.
+
+### Customize Newt Manager usage with mgmt
+
+The **mgmt** package enables you to customize Newt Manager (in either the newtmgr or oicmgr framerwork) to only process the
+commands that your application uses. The newtmgr commands are divided into management groups.
+A manager package implements the commands for a group. It implements the handlers that
+process the commands for the group and registers the handlers with mgmt.
+When newtmgr or oicmgr receives a newtmgr command,
+it looks up the handler for the command (by management group id and command id) from mgmt and calls the
+handler to process the command.
+
+The system level management groups are listed in following table:
+<table style="width:90%" align="center">
+<tt>
+<td>Management Group</td>
+<td>newtmgr Commands</td>
+<td>Package</td>
+</tt>
+<tr>
+<td>MGMT_GROUP_ID_DEFAULT</td>
+<td>```echo``` ```taskstats``` ```mpstats``` ```datetime``` ```reset```</td>
+<td>mgmt/newtmgr/nmgr_os</td>
+</tr>
+<tr>
+<td>MGMT_GROUP_ID_IMAGE</td>
+<td>```image``` </td>
+<td>mgmt/imgmgr</td>
+</tr>
+<tr>
+<td>MGMT_GROUP_ID_STATS</td>
+<td>```stat``` </td>
+<td>sys/stats</td>
+</tr>
+<tr>
+<td>MGMT_GROUP_ID_CONFIG</td>
+<td>```config```</td>
+<td>sys/config</td>
+</tr>
+<tr>
+<td>MGMT_GROUP_ID_LOGS</td>
+<td>```log```</td>
+<td>sys/log</td>
+</tr>
+<tr>
+<td>MGMT_GROUP_ID_CRASH</td>
+<td>```crash```</td>
+<td>test/crash_test</td>
+</tr>
+<tr>
+<td>MGMT_GROUP_ID_RUNTEST</td>
+<td>```runtest```</td>
+<td>test/runtest</td>
+</tr>
+</table>
+Both newtmgr and ocimgr process the MGMT_GROUP_ID_DEFAULT commands by default. You can also
+use mgmt to add user defined management group commands.
http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/a8067a50/docs/os/modules/newtmgr.md
----------------------------------------------------------------------
diff --git a/docs/os/modules/newtmgr.md b/docs/os/modules/newtmgr.md
deleted file mode 100644
index a17a2c5..0000000
--- a/docs/os/modules/newtmgr.md
+++ /dev/null
@@ -1,139 +0,0 @@
-# Bootloader
-
-Insert synopsis here
-
-
-## Description
-
-Describe module here, special features, how pieces fit together etc.
-
-## Data structures
-
-Replace this with the list of data structures used, why, any neat features
-
-## List of Functions
-
-<Comments such as these instructions are placed within angle brackets. List all the functions here. Note how the anchors work. You put the text you want to show up as a link within [] and the relevant #heading within (). Note that the header has to have at least 2 words for the anchor to work - that's how it is. "no-highlight" disables syntax highlighting. You can enable it for a particular language by specifying what the language is instead of "no-highlight". Be warned that this highlighting or no-highlighting specification may not show up nicely on Mou.>
-
-The functions available in this OS feature are:
-
-* [boot_slot_addr](#boot_slot_addr)
-* [boot_find_image_slot](#boot_find_image_slot)
-* add the rest
-
-
-## Function Reference
-
-------------------
-
-## <font color="F2853F" style="font-size:24pt"> boot_slot_addr </font>
-
-```no-highlight
- static void
- boot_slot_addr(int slot_num, uint8_t *flash_id, uint32_t *address)
-```
-
-<Insert short description>
-
-
-#### Arguments
-
-| Arguments | Description |
-|-----------|-------------|
-| xx | explain argument xx |
-| yy | explain argument yy |
-
-#### Returned values
-
-List any values returned.
-Error codes?
-
-#### Notes
-
-Any special feature/special benefit that we want to tout.
-Does it need to be used with some other specific functions?
-Any caveats to be careful about (e.g. high memory requirements).
-
-#### Example
-
-<Add text to set up the context for the example here>
-
-```no-highlight
-<Insert the code snippet here>
-```
-
----------------------
-
-## <font color="#F2853F" style="font-size:24pt"> boot_find_image_slot </font>
-
-```no-highlight
- <Insert function callout here >
-```
-
-<Insert short description>
-
-
-#### Arguments
-
-| Arguments | Description |
-|-----------|-------------|
-| xx | explain argument xx |
-| yy | explain argument yy |
-
-#### Returned values
-
-List any values returned.
-Error codes?
-
-#### Notes
-
-Any special feature/special benefit that we want to tout.
-Does it need to be used with some other specific functions?
-Any caveats to be careful about (e.g. high memory requirements).
-
-#### Example
-
-<Add text to set up the context for the example here>
-
-```no-highlight
-<Insert the code snippet here>
-```
-
----------------------
-
-## <font color="#F2853F" style="font-size:24pt"> next_one </font>
-
-```no-highlight
- <Insert function callout here >
-```
-
-<Insert short description>
-
-
-#### Arguments
-
-| Arguments | Description |
-|-----------|-------------|
-| xx | explain argument xx |
-| yy | explain argument yy |
-
-#### Returned values
-
-List any values returned.
-Error codes?
-
-#### Notes
-
-Any special feature/special benefit that we want to tout.
-Does it need to be used with some other specific functions?
-Any caveats to be careful about (e.g. high memory requirements).
-
-#### Example
-
-<Add text to set up the context for the example here>
-
-```no-highlight
-<Insert the code snippet here>
-```
-
----------------------
http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/a8067a50/docs/os/modules/newtmgr/newtmgr.md
----------------------------------------------------------------------
diff --git a/docs/os/modules/newtmgr/newtmgr.md b/docs/os/modules/newtmgr/newtmgr.md
deleted file mode 100644
index 7a7d0ed..0000000
--- a/docs/os/modules/newtmgr/newtmgr.md
+++ /dev/null
@@ -1,112 +0,0 @@
-## Newt Manager
-
-Newt Manager enables your Mynewt application to communicate with the newtmgr application tool and process
-newtmgr commands. Two Newt Manager implementations are provided: newtmgr and oicmgr. You can build one of
-the two into your application. The one that you select may depend on memory constraints for your application
-and whether your application supports the OIC (Open Interconnect Consortium) interoperability standard.
-
-To reduce your application code size, you can customize Newt Manager (newtmgr or oicmgr) to only
-process the newtmgr commands that your application uses.
-
-### newtmgr
-The newtmgr application tool uses a simple request and response message format to send commands to newtmgr. A message
-consists of an eight byte header and the message payload. The message header specifies the newtmgr command.
-The message payload contains the newtmgr request/response data and is encoded in
-CBOR (Concise Binary Object Representation) format. newtmgr supports BLE and serial connections.
-
-newtmgr has a smaller code size and memory footprint than oicmgr but does not support open connectivity.
-
-### oicmgr
-oicmgr supports the OIC interoperability standard. Mynewt defines and exposes oicmgr as an OIC Server
-resource with the following identity and properties:
-<br>
-<table style="width:50%" align="center">
-<tr>
-<td>**URI**</td>
-<td>/omgr</td>
-</tr>
-<tr>
-<td>**Resource Type**(rt)</td>
-<td>x.mynewt.nmgr</td>
-</tr>
-<td>**Interface**(if)</td>
-<td>oic.if_rw (default), oic.if.baseline</td>
-</tr>
-<td>**Discoverable**</td>
-<td>Yes</td>
-</tr>
-</table>
-The newtmgr application tool uses CoAP (Constrained Application Protocol) requests to send commands to oicmgr.
-It sends a CoAP request for **/omgr** as follows:
-<ul>
-<li>
-Specifies the newtmgr command to execute in the URI query string.
-</li>
-<li>
-Uses a GET method for newtmgr commands that retreive information
-from your application, for example, the ```taskstats``` and ```mpstats``` commands.
-</li>
-<li>
-Uses a PUT method for newtmgr commands that send data to or modify the state of your application,
-for example, the ```echo``` or ```datetime``` commands.
-</li>
-<li>
-Sends the CBOR-encoded command request data in the CoAP message payload.
-</li>
-</ul>
-oicmgr supports BLE, serial, and UDP connections.
-
-### Customize Newt Manager with mgmt
-The **mgmt** package enables you to customize Newt Manager (newtmgr or oicmgr) to only process the
-commands that your application uses. newtmgr commands are divided into management groups.
-A manager package implements the commands for a group. It implements the handlers that
-process the commands for the group and registers the handlers with mgmt.
-When newtmgr or oicmgr receives a newtmgr command,
-it looks up the handler for the command (by management group id and command id) from mgmt and calls the
-handler to process the command.
-
-The system level management groups are listed in following table:
-<table style="width:90%" align="center">
-<tt>
-<td>Management Group</td>
-<td>newtmgr Commands</td>
-<td>Package</td>
-</tt>
-<tr>
-<td>MGMT_GROUP_ID_DEFAULT</td>
-<td>```echo``` ```taskstats``` ```mpstats``` ```datetime``` ```reset```</td>
-<td>mgmt/newtmgr/nmgr_os</td>
-</tr>
-<tr>
-<td>MGMT_GROUP_ID_IMAGE</td>
-<td>```image``` </td>
-<td>mgmt/imgmgr</td>
-</tr>
-<tr>
-<td>MGMT_GROUP_ID_STATS</td>
-<td>```stat``` </td>
-<td>sys/stats</td>
-</tr>
-<tr>
-<td>MGMT_GROUP_ID_CONFIG</td>
-<td>```config```</td>
-<td>sys/config</td>
-</tr>
-<tr>
-<td>MGMT_GROUP_ID_LOGS</td>
-<td>```log```</td>
-<td>sys/log</td>
-</tr>
-<tr>
-<td>MGMT_GROUP_ID_CRASH</td>
-<td>```crash```</td>
-<td>test/crash_test</td>
-</tr>
-<tr>
-<td>MGMT_GROUP_ID_RUNTEST</td>
-<td>```runtest```</td>
-<td>test/runtest</td>
-</tr>
-</table>
-Both newtmgr and ocimgr process the MGMT_GROUP_ID_DEFAULT commands by default. You can also
-use mgmt to add user defined management group commands.
http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/a8067a50/mkdocs.yml
----------------------------------------------------------------------
diff --git a/mkdocs.yml b/mkdocs.yml
index 3b53081..7ffbf1a 100644
--- a/mkdocs.yml
+++ b/mkdocs.yml
@@ -308,8 +308,9 @@ pages:
- 'TEST_CASE': 'os/modules/testutil/test_case.md'
- 'TEST_CASE_DECL': 'os/modules/testutil/test_decl.md'
- 'tu_restart': 'os/modules/testutil/tu_restart.md'
- - Newt Manager:
- - toc: 'os/modules/newtmgr/newtmgr.md'
+ - Device Management with Newt Manager:
+ - toc: 'os/modules/devmgmt/newtmgr.md'
+ - 'Using Newt Manager in OIC framework': 'os/modules/devmgmt/oicmgr.md'
- Image Manager:
- toc: 'os/modules/imgmgr/imgmgr.md'
- 'Functions':