Repository: incubator-mynewt-site Updated Branches: refs/heads/master fb4a7c7e8 -> ac5f20e4c
Updated CO2 air quality sensor tutorial to work with Arduino Primo and have BLE enabled to advertise the data. This closes #143. Added sys config error scenarios. This closes #142. Closed the PR for ADC tutorial as it is being rewritten to use updated HAL and driver framework. 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/ac5f20e4 Tree: http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/tree/ac5f20e4 Diff: http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/diff/ac5f20e4 Branch: refs/heads/master Commit: ac5f20e4cf4dc07bab62a3c11853724476f8641a Parents: fb4a7c7 Author: aditihilbert <[email protected]> Authored: Thu Jan 19 15:18:04 2017 -0800 Committer: aditihilbert <[email protected]> Committed: Thu Jan 19 15:18:04 2017 -0800 ---------------------------------------------------------------------- .../os/modules/sysinitconfig/sysconfig_error.md | 330 +++++++++++++++++++ docs/os/tutorials/air_quality_ble.md | 222 +++++++++++++ docs/os/tutorials/pics/MyNewtSensorReader.jpg | Bin 0 -> 141358 bytes docs/os/tutorials/pics/Senseair1.png | Bin 0 -> 1215822 bytes docs/os/tutorials/pics/Senseair2.png | Bin 0 -> 1077537 bytes 5 files changed, 552 insertions(+) ---------------------------------------------------------------------- http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/ac5f20e4/docs/os/modules/sysinitconfig/sysconfig_error.md ---------------------------------------------------------------------- diff --git a/docs/os/modules/sysinitconfig/sysconfig_error.md b/docs/os/modules/sysinitconfig/sysconfig_error.md new file mode 100644 index 0000000..68b5afe --- /dev/null +++ b/docs/os/modules/sysinitconfig/sysconfig_error.md @@ -0,0 +1,330 @@ +##Validation and Error Messages + +With multiple packages defining and overriding system configuration settings, it +is easy to introduce conflicts and violations that are difficult to find. The +`newt build <target-name>` command validates the setting definitions and value +overrides for all the packages in the target to ensure a valid and consistent build. +It aborts the build when it detects violations or ambiguities between packages. +The following sections describe the error conditions that newt detects and +the error messages that it outputs. For most errors, newt also outputs +the `Setting history` with the order of package overrides to help +you resolve the errors. + +**Note:** The `newt target config <target-name>` command also detects +errors and outputs error messages at the top of the command output. +The command outputs the package setting definitions and values after it +outputs the error messages. It is easy to miss the error messages at the top. + + +###Value Override Violations + +The newt tool uses package priorities to resolve override conflicts. It uses +the value override from the highest priority package when multiple +packages override the same setting. Newt checks for the following +override violations: + +* Ambiguity Violation - Two packages of the same priority override a setting with +different values. And no higher priority package overrides the setting. +* Priority Violation - A package overrides a setting defined by a package with higher or +equal priority (TODO: Change error message to indicate a more general priority violation instead of only lateral overrides) + +####Example: Ambiguity Violation Error Message + +The following example shows the error message that newt outputs for an ambiguity violation: + +```no-highlight + +Error: Syscfg ambiguities detected: + Setting: LOG_NEWTMGR, Packages: [apps/slinky, apps/splitty] +Setting history (newest -> oldest): + LOG_NEWTMGR: [apps/splitty:0, apps/slinky:1, sys/log:0] + +``` + +The above error occurs because the `apps/slinky` and `apps/splitty` packages +in the split image target both override the same setting with different +values. The `apps/slinky` package sets the `sys/log` package `LOG_NEWTMGR` +setting to 1, and the `apps/splitty` package sets the setting to 0. The +overrides are ambiguous because both are `app` packages and +have the same priority. The following are excerpts of the defintion +and the two overrides from the `syscfg.yml` files that cause the error: + + +```no-highlight + +#Package: sys/log/ +syscfg.defs: + LOG_NEWTMGR: + description: 'Enables or disables newtmgr command tool logging' + value: 0 + +#Package: apps/slinky +syscfg.vals: + LOG_NEWTMGR: 1 + +#Package: apps/splitty +syscfg.vals: + LOG_NEWTMGR: 0 + +``` + +####Example: Priority Violation Error Message + +The following example shows the error message that newt outputs for a lateral violation where a package tries to change the setting that was defined by another package at the same priority level: + +```no-highlight + + +Error: Lateral overrides detected (bottom-priority packages cannot override settings): + Package: mgmt/newtmgr, Setting: LOG_NEWTMGR + +Setting history (newest -> oldest): + LOG_NEWTMGR: [sys/log:0] + +``` + +The above error occurs because the `mgmt/newtmgr` lib package +overrides the `LOG_NEWTMGR` setting that the `sys/log` lib package +defines. The following are excerpts of the definition and the override from the +`syscfg.yml` files that cause this error: + +```no-highlight + +#Package: sys/log +syscfg.defs: + LOG_NEWTMGR: + description: 'Enables or disables newtmgr command tool logging' + value: 0 + +#Package: mgmt/newtmgr +syscfg.vals: + LOG_NEWTMGR: 1 + +``` +<br> + +###Flash Area Violations + +For `flash_owner` type setting definitions, newt checks +for the following violations: + +* An undefined flash area is assigned to a setting. +* A flash area is assigned to multiple settings. + +####Example: Undefined Flash Area Error Message + +The following example shows the error message that newt outputs for an undefined flash area. + +```no-highlight + +Building target targets/sim_slinky +Error: Flash errors detected: + Setting REBOOT_LOG_FLASH_AREA specifies unknown flash area: FLASH_AREA_NOEXIST + +Setting history (newest -> oldest): + REBOOT_LOG_FLASH_AREA: [hw/bsp/native:FLASH_AREA_NOEXIST, sys/reboot:] + +``` +The above error occurs because the `hw/bsp/native` package assigns the +undefined `FLASH_AREA_NOEXIST` flash area to the `sys/reboot` package +`REBOOT_LOG_FLASH_AREA` setting. The following are excerpts of the definition +and the override from the `syscfg.yml` files that cause the error: + +```no-highlight + +#Package: sys/reboot +syscfg.defs: + REBOOT_LOG_FLASH_AREA: + description: 'Flash Area to use for reboot log.' + type: flash_owner + value: + +#Package: hw/bsp/native +syscfg.vals: + REBOOT_LOG_FLASH_AREA: FLASH_AREA_NOEXIST + +``` + +####Example: Multiple Flash Area Assignment Error Message + +The following example shows the error message that newt outputs when multiple +settings are assigned the same flash area: + +```no-highlight + +Error: Flash errors detected: + Multiple flash_owner settings specify the same flash area + settings: REBOOT_LOG_FLASH_AREA, CONFIG_FCB_FLASH_AREA + flash area: FLASH_AREA_NFFS + +Setting history (newest -> oldest): + CONFIG_FCB_FLASH_AREA: [hw/bsp/native:FLASH_AREA_NFFS, sys/config:] + REBOOT_LOG_FLASH_AREA: [apps/slinky:FLASH_AREA_NFFS, sys/reboot:] + +``` + +The above error occurs because the `hw/bsp/native` package assigns +the `FLASH_AREA_NFFS` flash area to the `sys/config/` package +`CONFIG_FCB_FLASH_AREA` setting, and the `apps/slinky` package +also assigns `FLASH_AREA_NFFS` to the `sys/reboot` package +`REBOOT_LOG_FLASH_AREA` setting. The following are excerpts of the +two definitions and the two overrides from the `syscfg.yml` files +that cause the error: + +```no-highlight + +# Package: sys/config +syscfg.defs.CONFIG_FCB: + CONFIG_FCB_FLASH_AREA: + description: 'The flash area for the Config Flash Circular Buffer' + type: 'flash_owner' + value: + +# Package: sys/reboot +syscfg.defs: + REBOOT_LOG_FLASH_AREA: + description: 'The flash area for the reboot log' + type: 'flash_owner' + value: + +#Package: hw/bsp/native +syscfg.vals: + CONFIG_FCB_FLASH_AREA: FLASH_AREA_NFFS + +#Package: apps/slinky +syscfg.vals: + REBOOT_LOG_FLASH_AREA: FLASH_AREA_NFFS + +``` +<br> +###Restriction Violations +For setting definitions with `restrictions` specified, newt checks for +the following violations: + +* A setting with a `$notnull` restriction does not have a value. +* For a setting with expression restrictions, some required setting +values in the expressions evaluate to false. + +####Example: $notnull Restriction Violation Error Message + +The following example shows the error message that newt outputs when +a setting with `$notnull` restriction does not have a value: + +```no-highlight + +Error: Syscfg restriction violations detected: + NFFS_FLASH_AREA must not be null + +Setting history (newest -> oldest): + NFFS_FLASH_AREA: [fs/nffs:] + +``` + +The above error occurs because the `fs/nffs` package defines the `NFFS_FLASH_AREA` +setting with a `$notnull` restriction and no packages override the setting. The +following is an excerpt of the definition in the `syscfg.yml` file that causes the error: + +```no-highlight + +#Package: fs/nffs +syscfg.defs: + NFFS_FLASH_AREA: + description: 'The flash area to use for the Newtron Flash File System' + type: flash_owner + value: + restrictions: + - $notnull +``` +####Example: Expression Restriction Violation Error Message + +The following example shows the error message that newt outputs for +an expression restriction violation: + +```no-highlight + +Error: Syscfg restriction violations detected: + CONFIG_FCB=1 requires CONFIG_FCB_FLASH_AREA be set, but CONFIG_FCB_FLASH_AREA= + +Setting history (newest -> oldest): + CONFIG_FCB: [targets/sim_slinky:1, sys/config:0] + CONFIG_FCB_FLASH_AREA: [sys/config:] + +``` + +The above error occurs because the `sys/config` package defines the `CONFIG_FCB` setting with +a restriction that when set, requires that the `CONFIG_FCB_FLASH_AREA` setting must +also be set. The following are excerpts of the definition and the override from the `syscfg.yml` +files that cause the error: + +```no-highlight + +# Package: sys/config +syscfg.defs: + CONFIG_FCB: + description: 'Uses Config Flash Circular Buffer' + value: 0 + restrictions: + - '!CONFIG_NFFS' + - 'CONFIG_FCB_FLASH_AREA' + +# Package: targets/sim_slinky +syscfg.vals: + CONFIG_FCB: 1 +``` +<br> +###Task Priority Violations + +For `task_priority` type setting definitions, newt checks for the following violations: + +* A task priority number is assigned to multiple settings. +* The task priority number is greater than 239. + +####Example: Duplicate Task Priority Assignment Error Message + +The following example shows the error message that newt outputs when +a task priority number is assigned to multiple settings. + +**Note:** The settings used in this example are not actual `apps/slinky` and `sys/shell` settings. +These settings are created for this example because currently only one Mynewt package +defines a `task_priority` type setting. + +```no-highlight + +Error: duplicate priority value: setting1=SHELL_TASK_PRIORITY setting2=SLINKY_TASK_PRIORITY pkg1=apps/slinky pkg2=sys/shell value=1 + +``` + +The above error occurs because the `apps/slinky` package defines a `SLINKY_TASK_PRIORITY` +setting with a default task priority of 1 and the `sys/shell` package also defines a +`SHELL_TASK_PRIORITY` setting with a default task priority of 1. + +####Example: Invalid Task Priority Error Message + +The following example shows the error message that newt outputs when +a setting is assigned an invalid task priority value: + +```no-highlight + +Error: invalid priority value: value too great (> 239); setting=SLINKY_TASK_PRIORITY value=240 pkg=apps/slinky + +``` + +The above error occurs because the `apps/slinky` package defines the `SLINKY_TASK_PRIORITY` setting +with 240 for the default task priority value. + +**Note:** Newt does not output the `Setting history` with task priority violation error messages. + + +<br> +###Duplicate System Configuration Setting Definition + +A setting definition must be unique. Newt checks that only one package in the +target defines a setting. The following example shows the error message that newt +outputs when multiple packages define the `LOG_NEWTMGR` setting: + +```no-highlight + +Error: setting LOG_NEWTMGR redefined + +``` +**Note:** Newt does not output the `Setting history` with duplicate setting error messages. http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/ac5f20e4/docs/os/tutorials/air_quality_ble.md ---------------------------------------------------------------------- diff --git a/docs/os/tutorials/air_quality_ble.md b/docs/os/tutorials/air_quality_ble.md new file mode 100644 index 0000000..7497d19 --- /dev/null +++ b/docs/os/tutorials/air_quality_ble.md @@ -0,0 +1,222 @@ +## Air quality sensor project via Bluetooth + +This is a follow-on project to the [Basic Air Quality Sensor](air_quality_sensor.md) project; so it is +assumed that you have worked through that project and have your CO<sub>2</sub> sensor working properly with +your Arduino Primo board. + +So let's get started making this thing Bluetooth enabled! + +### Add Bluetooth GATT Services + +Since we already built the previous demo on the [bluetooth peripheral](bleprph/bleprph-app.md) basic +app most of the bluetooth plumbing has already been taken care of for us. What's left is for us +to add the required GATT services for advertising the Carbon Dioxide sensor so that +other devices can get those values. + +First, we'll define the GATT Services in `apps/air_quality/src/bleprph.h`. + +```c +/* Sensor Data */ +/* e761d2af-1c15-4fa7-af80-b5729002b340 */ +static const uint8_t gatt_svr_svc_co2_uuid[16] = { + 0x40, 0xb3, 0x20, 0x90, 0x72, 0xb5, 0x80, 0xaf, + 0xa7, 0x4f, 0x15, 0x1c, 0xaf, 0xd2, 0x61, 0xe7 }; +#define CO2_SNS_TYPE 0xDEAD +#define CO2_SNS_STRING "SenseAir K30 CO2 Sensor" +#define CO2_SNS_VAL 0xBEAD + +uint16_t gatt_co2_val; +``` + +You can use any hex values you choose for the sensor type and sensor values, and you can +even forget the sensor type and sensor string definitions altogether but they make +the results look nice in our Bleutooth App. + +Next we'll add those services to `apps/air_quality/src/gatt_svr.c`. + +```c +static int +gatt_svr_sns_access(uint16_t conn_handle, uint16_t attr_handle, + struct ble_gatt_access_ctxt *ctxt, + void *arg); + +static uint16_t gatt_co2_val_len; + +``` + +Make sure it is added as *primary* service. + +```c +static const struct ble_gatt_svc_def gatt_svr_svcs[] = { + { + /*** Service: Security test. */ + .type = BLE_GATT_SVC_TYPE_PRIMARY, + .uuid128 = gatt_svr_svc_sec_test_uuid, + .characteristics = (struct ble_gatt_chr_def[]) { { + /*** Characteristic: Random number generator. */ + .uuid128 = gatt_svr_chr_sec_test_rand_uuid, + .access_cb = gatt_svr_chr_access_sec_test, + .flags = BLE_GATT_CHR_F_READ | BLE_GATT_CHR_F_READ_ENC, + }, { + /*** Characteristic: Static value. */ + .uuid128 = gatt_svr_chr_sec_test_static_uuid, + .access_cb = gatt_svr_chr_access_sec_test, + .flags = BLE_GATT_CHR_F_READ | + BLE_GATT_CHR_F_WRITE | BLE_GATT_CHR_F_WRITE_ENC, + }, { + 0, /* No more characteristics in this service. */ + } }, + }, + { + /*** CO2 Level Notification Service. */ + .type = BLE_GATT_SVC_TYPE_PRIMARY, + .uuid128 = gatt_svr_svc_co2_uuid, + .characteristics = (struct ble_gatt_chr_def[]) { { + .uuid128 = BLE_UUID16(CO2_SNS_TYPE), + .access_cb = gatt_svr_sns_access, + .flags = BLE_GATT_CHR_F_READ, + }, { + .uuid128 = BLE_UUID16(CO2_SNS_VAL), + .access_cb = gatt_svr_sns_access, + .flags = BLE_GATT_CHR_F_NOTIFY, + }, { + 0, /* No more characteristics in this service. */ + } }, + }, + { + 0, /* No more services. */ + }, +}; +``` + +Next we need to tell the GATT Server how to handle requests for CO<sub>2</sub> readings : + +```c +static int +gatt_svr_sns_access(uint16_t conn_handle, uint16_t attr_handle, + struct ble_gatt_access_ctxt *ctxt, + void *arg) +{ + uint16_t uuid16; + int rc; + + uuid16 = ble_uuid_128_to_16(ctxt->chr->uuid128); + assert(uuid16 != 0); + + switch (uuid16) { + case CO2_SNS_TYPE: + assert(ctxt->op == BLE_GATT_ACCESS_OP_READ_CHR); + rc = os_mbuf_append(ctxt->om, CO2_SNS_STRING, sizeof CO2_SNS_STRING); + BLEPRPH_LOG(INFO, "CO2 SENSOR TYPE READ: %s\n", CO2_SNS_STRING); + return rc == 0 ? 0 : BLE_ATT_ERR_INSUFFICIENT_RES; + + case CO2_SNS_VAL: + if (ctxt->op == BLE_GATT_ACCESS_OP_WRITE_CHR) { + rc = gatt_svr_chr_write(ctxt->om, 0, + sizeof gatt_co2_val, + &gatt_co2_val, + &gatt_co2_val_len); + return rc; + } else if (ctxt->op == BLE_GATT_ACCESS_OP_READ_CHR) { + rc = os_mbuf_append(ctxt->om, &gatt_co2_val, + sizeof gatt_co2_val); + return rc == 0 ? 0 : BLE_ATT_ERR_INSUFFICIENT_RES; + } + + default: + assert(0); + return BLE_ATT_ERR_UNLIKELY; + } +} +``` + +Now it's time to go into our `apps/air_quality/src/main.c` and change how we read CO<sub>2</sub> readings and +respond to requests. + +We'll need a task handler with an event queue for the CO<sub>2</sub> readings -- they were handled by the shell task in the previous tutorial but now it needs to be replaced by a different handler as shown below. + +```c +/* CO2 Task settings */ +#define CO2_TASK_PRIO 5 +#define CO2_STACK_SIZE (OS_STACK_ALIGN(336)) +struct os_eventq co2_evq; +struct os_task co2_task; +bssnz_t os_stack_t co2_stack[CO2_STACK_SIZE]; +``` + +And of course we'll need to go to our `main()` and do all the standard task and event setup we +normally do by adding the following. Again, remember to delete all the shell event queues and tasks. + +```c +/* Initialize sensor eventq */ +os_eventq_init(&co2_evq); + +/* Create the CO2 reader task. + * All sensor reading operations are performed in this task. + */ +os_task_init(&co2_task, "sensor", co2_task_handler, + NULL, CO2_TASK_PRIO, OS_WAIT_FOREVER, + co2_stack, CO2_STACK_SIZE); + +``` + +We'll also need to add a task handler -- since we initialized it above: + +```c +/** + * Event loop for the sensor task. + */ +static void +co2_task_handler(void *unused) +{ + while (1) { + co2_read_event(); + /* Wait 2 second */ + os_time_delay(OS_TICKS_PER_SEC * 2); + + } +} +``` + +And finally, we'll take care of that `co2_read_event()` function: + +```c +int +co2_read_event(void) +{ + int value; + enum senseair_read_type type = SENSEAIR_CO2; + uint16_t chr_val_handle; + int rc; + + value = senseair_read(type); + if (value >= 0) { + console_printf("Got %d\n", value); + } else { + console_printf("Error while reading: %d\n", value); + goto err; + } + gatt_co2_val = value; + rc = ble_gatts_find_chr(gatt_svr_svc_co2_uuid, BLE_UUID16(CO2_SNS_VAL), NULL, &chr_val_handle); + assert(rc == 0); + ble_gatts_chr_updated(chr_val_handle); + return (0); +err: + return (rc); +} +``` + +You'll notice that it looks eeirily similar to a portion of the shell event we created +earlier. This one simply reads and updates the CO<sub>2</sub> value and sends that over BLE to any +connected clients instead. + +We can now build, create-image and load the app onto our Arduino Primo board, and then +connect and see the updated values! The image below shows the results using MyNewt Sensor Reader, +a Mac OS X app developed for connecting to MyNewt devices over Bluetooth but you can also use LightBlue +or any other application that can connect to, and read, Bluetooth data. + + + +Congratulations!! + + http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/ac5f20e4/docs/os/tutorials/pics/MyNewtSensorReader.jpg ---------------------------------------------------------------------- diff --git a/docs/os/tutorials/pics/MyNewtSensorReader.jpg b/docs/os/tutorials/pics/MyNewtSensorReader.jpg new file mode 100644 index 0000000..997a359 Binary files /dev/null and b/docs/os/tutorials/pics/MyNewtSensorReader.jpg differ http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/ac5f20e4/docs/os/tutorials/pics/Senseair1.png ---------------------------------------------------------------------- diff --git a/docs/os/tutorials/pics/Senseair1.png b/docs/os/tutorials/pics/Senseair1.png new file mode 100644 index 0000000..9b469b3 Binary files /dev/null and b/docs/os/tutorials/pics/Senseair1.png differ http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/ac5f20e4/docs/os/tutorials/pics/Senseair2.png ---------------------------------------------------------------------- diff --git a/docs/os/tutorials/pics/Senseair2.png b/docs/os/tutorials/pics/Senseair2.png new file mode 100644 index 0000000..38be672 Binary files /dev/null and b/docs/os/tutorials/pics/Senseair2.png differ
