Repository: incubator-mynewt-site Updated Branches: refs/heads/develop 2044f7b9c -> b6a327e50
1) Updated Enabling Newt Manager" tutorial to reflect current implmentation (i.e no need to create designated task etc) 2) Added information on how to configure an application with other Newt Manager options, such as oicmgr etc. 3) Updated the imgmgr_module_init so that it doesn't show example to create a dedicated task for newtmgr. Mentioned that the function is called by sysinit(). 4) Minor cleanup to the Device Management Using Newt Manager section. Moved the Customizing section to a separate page. 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/f18e165b Tree: http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/tree/f18e165b Diff: http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/diff/f18e165b Branch: refs/heads/develop Commit: f18e165b8320b6a184763d015d05dc6b8e9d6333 Parents: a10075c Author: cwanda <[email protected]> Authored: Sun Jan 22 23:01:27 2017 -0800 Committer: cwanda <[email protected]> Committed: Mon Jan 23 20:12:07 2017 -0800 ---------------------------------------------------------------------- docs/os/modules/devmgmt/oicmgr.md | 58 +---- docs/os/modules/imgmgr/imgmgr_module_init.md | 25 +- docs/os/tutorials/add_newtmgr.md | 266 ++++++++++++++-------- mkdocs.yml | 3 +- 4 files changed, 180 insertions(+), 172 deletions(-) ---------------------------------------------------------------------- http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/f18e165b/docs/os/modules/devmgmt/oicmgr.md ---------------------------------------------------------------------- diff --git a/docs/os/modules/devmgmt/oicmgr.md b/docs/os/modules/devmgmt/oicmgr.md index 96186bd..8943016 100644 --- a/docs/os/modules/devmgmt/oicmgr.md +++ b/docs/os/modules/devmgmt/oicmgr.md @@ -1,4 +1,4 @@ -## Using the OIC framework +## 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> @@ -29,59 +29,3 @@ 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/f18e165b/docs/os/modules/imgmgr/imgmgr_module_init.md ---------------------------------------------------------------------- diff --git a/docs/os/modules/imgmgr/imgmgr_module_init.md b/docs/os/modules/imgmgr/imgmgr_module_init.md index 0e8e310..3c0dc54 100644 --- a/docs/os/modules/imgmgr/imgmgr_module_init.md +++ b/docs/os/modules/imgmgr/imgmgr_module_init.md @@ -1,36 +1,19 @@ ## <font color="#F2853F" style="font-size:24pt"> imgmgr_module_init </font> ```no-highlight - int + void imgmgr_module_init(void) ``` - Registers image manager commands with newtmgr. This function should be called while initializing the project, preferably after newtmgr itself has been initialized. +Registers the image manager commands with the `mgmt` package. `sysinit()` automatically calls this function during +system initialization. #### Arguments N/A #### Returned values - -List any values returned. -Error codes? +N/A #### Notes - -#### Example - -```no-highlight -int main(int argc, char **argv) -{ - ... - - nmgr_task_init(NEWTMGR_TASK_PRIO, newtmgr_stack, NEWTMGR_TASK_STACK_SIZE); - imgmgr_module_init(); - - ... -} -``` - - http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/f18e165b/docs/os/tutorials/add_newtmgr.md ---------------------------------------------------------------------- diff --git a/docs/os/tutorials/add_newtmgr.md b/docs/os/tutorials/add_newtmgr.md index 2c5fe85..4746e6a 100644 --- a/docs/os/tutorials/add_newtmgr.md +++ b/docs/os/tutorials/add_newtmgr.md @@ -1,75 +1,130 @@ -##Enabling Newt Manager (newtmgr) in a project + +##Enabling Newt Manager in Your Application <br> +In order for your application to communicate with the newtmgr tool and process Newt Manager commands, you must +enable Newt Manager device management and the support to process Newt Manager commands +in your application. This tutorial explains how to add the support to your application. + +This tutorial assumes that you have read the [Device Management with Newt Manager](/os/modules/devmgmt/newtmgr/) +guide and are familiar with the `newtmgr` and `oicmgr` frameworks and all the options that are available +to customize your application. + +This tutorial shows you how to configure your application to: + +* Use the newtmgr framework. +* Use serial transport to communicate with the newtmgr tool. +* Support all Newt Manager commands. -This tutorial explains how to add the newtmgr task to a project so that you can interact with your project over newtmgr. +See [Other Configuration Options](#other-configuration-options) on how to customize your application. <br> ### Pre-Requisites +Ensure that you have met the following prerequisites before continuing with this tutorial: -* Ensure you have installed [newt](../../newt/install/newt_mac.md) and that the -newt command is in your system path. -* Ensure that you have installed the newtmgr tool [newtmgr](../../newtmgr/installing.md) -* You must have Internet connectivity to fetch remote Mynewt components. -* You must [install the compiler tools](../get_started/native_tools.md) to +* Installed the [newt tool](../../newt/install/newt_mac.md). +* Installed the [newtmgr tool](../../newtmgr/installing.md). +* Have Internet connectivity to fetch remote Mynewt components. +* Installed the [compiler tools](../get_started/native_tools.md) to support native compiling to build the project this tutorial creates. -* You must install the [Segger JLINK package]( https://www.segger.com/jlink-software.html) to load your project on the board. -* Cable to establish a serial USB connection between the board and the laptop +* Installed the [Segger JLINK package]( https://www.segger.com/jlink-software.html) to load your project on the board. +* Have a cable to establish a serial USB connection between the board and the laptop. <br> -### Use an existing project +### Use an Existing Project -Since all we're doing is adding newtmgr capability to a project, we assume that you have worked through at least some of the other tutorials, and have an existing project. -For this example, we'll be modifying the [ble_tiny](bletiny_project.md) project to enable newtmgr connectivity. We'll be calling our app myble as in that project as well. -Feel free to use whatever project you'd like though. +We assume that you have worked through at least some of the other tutorials and have an existing project. +In this example, we modify the [ble_tiny](bletiny_project.md) project to enable Newt Manager support. +We call our application `myble`. You can create the application using any name you choose. -The first thing you'll need to add is a new dependency for your app. In the repo for the bletiny app you'll need to add the following line to the pkg.yml file: +###Modify Package Dependencies and Configurations -``` - - libs/newtmgr -``` - -Now the application will know to pull in the newtmgr code. -<br> +Add the following packages to the `pkg.deps` parameter in your target or application `pkg.yml` file: -###Modify the source +```no-highlight -First, you'll need to include the newtmgr header file: +pkg.deps: + - mgmt/newtmgr + - mgmt/newtmgr/transport/nmgr_shell + - mgmt/imgmgr + - sys/log/full + - sys/stats/full + - sys/config + - test/crash_test + - test/runtest -``` +``` +Each package provides the following Newt Manager functionality: -#include <newtmgr/newtmgr.h> -``` +* `mgmt/newtmgr`: Supports the newtmgr framework and the +Newt Manager `echo`, `taskstats` `mpstats`, `datetime`, and `reset` commands. +* `mgmt/newtmgr/transport/nmgr_shell`: Supports serial transport. +* `mgmt/imgmgr`: Supports the `newtmgr image` command +* `sys/log/full` : Supports the `newtmgr log` command. +* `sys/stats/full`: Supports the `newtmgr stat` command. +* `sys/config`: Supports the `newtmgr config` command. +* `test/crash_test`: Supports the `newtmgr crash` command. +* `test/runtest`: Supports the `newt run` command. -Next, you'll need to declare a task for the newtmgr: +Add the following configuration setting values to the `syscfg.vals` parameter in the target or +application `syscfg.yml` file: -``` +```no-highlight -#define NEWTMGR_TASK_PRIO (4) -#define NEWTMGR_TASK_STACK_SIZE (OS_STACK_ALIGN(896)) -os_stack_t newtmgr_stack[NEWTMGR_TASK_STACK_SIZE]; +syscfg.vals: + LOG_NEWTMGR: 1 + STATS_NEWTMGR: 1 + CONFIG_NEWTMGR: 1 + CRASH_TEST_NEWTMGR: 1 + RUNTEST_NEWTMGR: 1 + SHELL_TASK: 1 ``` +The first five configuration settings enable support for the Newt Manager `log`, `stats`, `config`, `crash`, +and `run` commands. The `SHELL_TASK` setting enables the shell for serial transport. -Next you'll scroll down (way down) to the ```main()``` function and find the lines: +Note that you may need to override additional configuration settings that are specific to each package to customize the +package functionality. -``` -rc = console_init(shell_console_rx_cb); -assert(rc == 0); -``` +<br> -After those lines, add: +###Modify the Source + +Your application must designate an event queue that the `mgmt` package uses to receive request events from +the newtmgr tool. It must also initialize a task and implement the task handler to +dispatch events from this queue. The `mgmt` package executes and processes newtmgr +request events in the context of this task. Your application, however, does +not need to create a dedicated event queue and task for this purpose and can use its default +event queue. This example uses the application's default event queue. + +The `mgmt` package exports the `void mgmt_evq_set(struct os_eventq *evq)` function that an application must call +to designate the event queue. Modify `main.c` to add this call as follows: + +Add the `mgmt/mgmt.h` header file: + +```no-highlight + +#include <mgmt/mgmt.h> ``` -nmgr_task_init(NEWTMGR_TASK_PRIO, newtmgr_stack, NEWTMGR_TASK_STACK_SIZE); +Add the call to designate the event queue. In the `main()` function, +scroll down to the `os_eventq_dflt_set(&ble_tiny_evq)` function call and add the +following statement below it: + +```no-highlight + +mgmt_eventq_set(&ble_tiny_evq) + ``` +The `mgmt_eventq_set()` function must be called after your application has initialized the event queue and task. + -### Build targets +### Build the Targets -Then build the two targets. +Build the two targets as follows: ``` $ newt build nrf52_boot @@ -85,49 +140,55 @@ Compiling os.c <br> -### Create the app image +### Create the Application Image -Generate a signed application image for the `myble` target. The version number is arbitrary. +Generate a signed application image for the `myble` target. You can use any version number you choose. ``` $ newt create-image myble 1.0.0 -App image succesfully generated: ./bin/makerbeacon/apps/bletiny/bletiny.img +App image successfully generated: ./bin/makerbeacon/apps/bletiny/bletiny.img Build manifest: ./bin/makerbeacon/apps/bletiny/manifest.json ``` <br> -### Load the image +### Load the Image -Make sure the USB connector is in place and the power LED on the board is lit. Use the Power ON/OFF switch to reset the board after loading the image. +Ensure the USB connector is in place and the power LED on the board is lit. Turn the power switch on your board off, +then back on to reset the board after loading the image. ``` $ newt load nrf52_boot $ newt load myble ``` -<br> -### Set up newtmgr connection -Newtmgr requires a connection profile in order to connect to your board. If you haven't yet, follow the [instructions](../../newtmgr/overview.md) for setting up your connection profile. +### Set Up a Connection Profile + +The newtmgr tool requires a connection profile in order to connect to your board. If you have not done so, +follow the [instructions](../../newtmgr/overview.md) for setting up your connection profile. <br> -###Connecting with your app +###Connecting with Your Application -Once you have a connection profile set up, you can connect to your device with ```newtmgr -c myconn <command>``` to run commands agains your app. +Once you have a connection profile set up, you can connect to your device with ```newtmgr -c myconn <command>``` to run commands in your application. -To test and make sure that newtmgr is working, try the echo command: +Issue the `echo` command to ensure that your application is communicating with the newtmgr tool: + +```no-highlight -``` # newtmgr -c myconn echo hello -{"r": "hello"} +hello + ``` -Newtmgr wraped the response in valid JSON notation. Now let's look at some BLE stats using newtmgr: +Test your application to ensure that it can process a Newt Manager command that is supported by a different package. +Issue the `stat` command to see the BLE stats. + +```no-highlight -``` newtmgr -c myconn stat ble_att Return Code = 0 Stats Name: ble_att @@ -139,44 +200,9 @@ Stats Name: ble_att read_group_type_rsp_tx: 0 indicate_req_rx: 0 find_type_value_rsp_tx: 0 - read_mult_rsp_tx: 0 - exec_write_req_rx: 0 - exec_write_rsp_tx: 0 - error_rsp_tx: 0 - find_type_value_rsp_rx: 0 - read_type_req_tx: 0 - read_type_rsp_rx: 0 - read_rsp_tx: 0 - read_blob_req_tx: 0 - mtu_req_tx: 0 - read_req_tx: 0 - read_blob_rsp_tx: 0 - read_mult_req_rx: 0 - write_req_tx: 0 - prep_write_rsp_tx: 0 - indicate_rsp_rx: 0 - write_cmd_rx: 0 - exec_write_rsp_rx: 0 - find_info_req_rx: 0 - mtu_rsp_rx: 0 - prep_write_req_rx: 0 - notify_req_rx: 0 - read_group_type_rsp_rx: 0 - prep_write_rsp_rx: 0 - indicate_rsp_tx: 0 - find_info_rsp_tx: 0 - read_blob_req_rx: 0 - read_group_type_req_rx: 0 - write_cmd_tx: 0 - mtu_req_rx: 0 - read_mult_rsp_rx: 0 - write_rsp_rx: 0 - write_req_rx: 0 - read_type_rsp_tx: 0 - read_mult_req_tx: 0 - error_rsp_rx: 0 - find_info_rsp_rx: 0 - find_type_value_req_tx: 0 + + ... + read_req_rx: 0 read_type_req_rx: 0 notify_req_tx: 0 @@ -187,5 +213,59 @@ Stats Name: ble_att exec_write_req_tx: 0 ``` -Your application is now able to communicate via newtmgr! +Your application is now able to communicate with the newtmgr tool. + + +###Other Configuration Options + +This section explains how to customize your application to use other Newt Manager protocol options. + +####Newtmgr Framework Transport Protocol Options +The newtmgr framework currently supports BLE and serial transport protocols. +To configure the transport protocols that are supported, modify the `pkg.yml` +and `syscfg.yml` files as follows: + +* Add the `mgmt/newtmgr/transport/ble` package to `pkg.deps` parameter to enable BLE transport. +* Add the `mgmt/newtmgr/transport/nmgr_shell` package to +the `pkg.deps` parameter, and add `SHELL_TASK: 1` to the `syscfg.vals` parameter to enable serial transport. + +<br> + +#### Oicmgr Framework Options + +To use the oicmgr framework instead of the newtmgr framework, modify the `pkg.yml` and `syscfg.yml` files +as follows: + +* Add the `mgmt/oicmgr` package (instead of the `mgmt/newtmgr` and `mgmt/newtmgr/transport` packages +as described previously) to the `pkg.deps` parameter. +* Add `OC_SERVER: 1` to the `syscfg.vals` parameter. + +Oicmgr supports the IP, serial, and BLE transport protocols. To configure the transport protocols that are supported, +set the configuration setting values in the `syscfg.vals` parameter as follows: + +* Add `OC_TRANSPORT_IP: 1` to enable IP transport. +* Add `OC_TRANSPORT_GATT: 1` to enable BLE transport. +* Add `OC_TRANSPORT_SERIAL: 1` and `SHELL_TASK: 1` to enable serial transport. + +<br> + +#### Customize the Newt Manager Commands that Your Application Supports + +We recommend that you only enable support for the Newt Manager commands that your application uses +to reduce your application code size. To configure the commands that are supported, set the configuration +setting values in the `syscfg.vals` parameter as follows: + + +* Add `LOG_NEWTMGR: 1` to enable support for the `newtmgr log` command. +* Add `STATS_NEWTMGR: 1` to enable support for the `newtmgr stat` command. +* Add `CONFIG_NEWTMGR: 1` to enable support for the `newtmgr config` command. +* Add `CRASH_TEST_NEWTMGR: 1` to enable support for the `newtmgr crash` command. +* Add `RUNTEST_NEWTMGR: 1` to enable support for the `newtmgr crash` command. + +Notes: +* When you enable Newt Manager support, using either the newtmgr or oicmgr framework, your application automatically +supports the Newt Manager `echo`, `taskstats`, `mpstats`, `datetime`, and `reset` commands. These +commands cannot be configured individually. +* Currently, the `mgmt/imgmgr` package does not provide a configuration setting to enable or disable support +for the `newtmgr image` command. http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/f18e165b/mkdocs.yml ---------------------------------------------------------------------- diff --git a/mkdocs.yml b/mkdocs.yml index b80b434..2179156 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -52,7 +52,7 @@ pages: - 'Project Slinky for remote comms': - 'Slinky on sim device': 'os/tutorials/project-slinky.md' - 'Slinky on STM32 board': 'os/tutorials/project-target-slinky.md' - - 'Enable newtmgr in any app': 'os/tutorials/add_newtmgr.md' + - 'Enable Newt Manager in any app': 'os/tutorials/add_newtmgr.md' - 'Enable the OS Shell and Console': 'os/tutorials/add_shell.md' - 'BLE app to check stats via console': 'os/tutorials/bletiny_project.md' - 'BLE peripheral project': @@ -314,6 +314,7 @@ pages: - Device Management with Newt Manager: - toc: 'os/modules/devmgmt/newtmgr.md' - 'Using Newt Manager in OIC framework': 'os/modules/devmgmt/oicmgr.md' + - 'Customizing Newt Manager Usage with mgmt': 'os/modules/devmgmt/customize_newtmgr.md' - Image Manager: - toc: 'os/modules/imgmgr/imgmgr.md' - 'Functions':
