Revision 10:3f30c0e55a8e, committed 2018-05-10

Comitter:

maclobdell

Date:

Thu May 10 06:28:36 2018 -0500

Parent:

9:ae1f6fe932dc

Child:

11:6669e1e62d6f

Commit message:

add license, readme, resources file

Changed in this revision

--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/LICENSE.txt	Thu May 10 06:28:36 2018 -0500
@@ -0,0 +1,165 @@
+Apache License
+Version 2.0, January 2004
+http://www.apache.org/licenses/
+
+TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+1. Definitions.
+
+"License" shall mean the terms and conditions for use, reproduction, and
+distribution as defined by Sections 1 through 9 of this document.
+
+"Licensor" shall mean the copyright owner or entity authorized by the copyright
+owner that is granting the License.
+
+"Legal Entity" shall mean the union of the acting entity and all other entities
+that control, are controlled by, or are under common control with that entity.
+For the purposes of this definition, "control" means (i) the power, direct or
+indirect, to cause the direction or management of such entity, whether by
+contract or otherwise, or (ii) ownership of fifty percent (50%) or more of the
+outstanding shares, or (iii) beneficial ownership of such entity.
+
+"You" (or "Your") shall mean an individual or Legal Entity exercising
+permissions granted by this License.
+
+"Source" form shall mean the preferred form for making modifications, including
+but not limited to software source code, documentation source, and configuration
+files.
+
+"Object" form shall mean any form resulting from mechanical transformation or
+translation of a Source form, including but not limited to compiled object code,
+generated documentation, and conversions to other media types.
+
+"Work" shall mean the work of authorship, whether in Source or Object form, made
+available under the License, as indicated by a copyright notice that is included
+in or attached to the work (an example is provided in the Appendix below).
+
+"Derivative Works" shall mean any work, whether in Source or Object form, that
+is based on (or derived from) the Work and for which the editorial revisions,
+annotations, elaborations, or other modifications represent, as a whole, an
+original work of authorship. For the purposes of this License, Derivative Works
+shall not include works that remain separable from, or merely link (or bind by
+name) to the interfaces of, the Work and Derivative Works thereof.
+
+"Contribution" shall mean any work of authorship, including the original version
+of the Work and any modifications or additions to that Work or Derivative Works
+thereof, that is intentionally submitted to Licensor for inclusion in the Work
+by the copyright owner or by an individual or Legal Entity authorized to submit
+on behalf of the copyright owner. For the purposes of this definition,
+"submitted" means any form of electronic, verbal, or written communication sent
+to the Licensor or its representatives, including but not limited to
+communication on electronic mailing lists, source code control systems, and
+issue tracking systems that are managed by, or on behalf of, the Licensor for
+the purpose of discussing and improving the Work, but excluding communication
+that is conspicuously marked or otherwise designated in writing by the copyright
+owner as "Not a Contribution."
+
+"Contributor" shall mean Licensor and any individual or Legal Entity on behalf
+of whom a Contribution has been received by Licensor and subsequently
+incorporated within the Work.
+
+2. Grant of Copyright License.
+
+Subject to the terms and conditions of this License, each Contributor hereby
+grants to You a perpetual, worldwide, non-exclusive, no-charge, royalty-free,
+irrevocable copyright license to reproduce, prepare Derivative Works of,
+publicly display, publicly perform, sublicense, and distribute the Work and such
+Derivative Works in Source or Object form.
+
+3. Grant of Patent License.
+
+Subject to the terms and conditions of this License, each Contributor hereby
+grants to You a perpetual, worldwide, non-exclusive, no-charge, royalty-free,
+irrevocable (except as stated in this section) patent license to make, have
+made, use, offer to sell, sell, import, and otherwise transfer the Work, where
+such license applies only to those patent claims licensable by such Contributor
+that are necessarily infringed by their Contribution(s) alone or by combination
+of their Contribution(s) with the Work to which such Contribution(s) was
+submitted. If You institute patent litigation against any entity (including a
+cross-claim or counterclaim in a lawsuit) alleging that the Work or a
+Contribution incorporated within the Work constitutes direct or contributory
+patent infringement, then any patent licenses granted to You under this License
+for that Work shall terminate as of the date such litigation is filed.
+
+4. Redistribution.
+
+You may reproduce and distribute copies of the Work or Derivative Works thereof
+in any medium, with or without modifications, and in Source or Object form,
+provided that You meet the following conditions:
+
+You must give any other recipients of the Work or Derivative Works a copy of
+this License; and
+You must cause any modified files to carry prominent notices stating that You
+changed the files; and
+You must retain, in the Source form of any Derivative Works that You distribute,
+all copyright, patent, trademark, and attribution notices from the Source form
+of the Work, excluding those notices that do not pertain to any part of the
+Derivative Works; and
+If the Work includes a "NOTICE" text file as part of its distribution, then any
+Derivative Works that You distribute must include a readable copy of the
+attribution notices contained within such NOTICE file, excluding those notices
+that do not pertain to any part of the Derivative Works, in at least one of the
+following places: within a NOTICE text file distributed as part of the
+Derivative Works; within the Source form or documentation, if provided along
+with the Derivative Works; or, within a display generated by the Derivative
+Works, if and wherever such third-party notices normally appear. The contents of
+the NOTICE file are for informational purposes only and do not modify the
+License. You may add Your own attribution notices within Derivative Works that
+You distribute, alongside or as an addendum to the NOTICE text from the Work,
+provided that such additional attribution notices cannot be construed as
+modifying the License.
+You may add Your own copyright statement to Your modifications and may provide
+additional or different license terms and conditions for use, reproduction, or
+distribution of Your modifications, or for any such Derivative Works as a whole,
+provided Your use, reproduction, and distribution of the Work otherwise complies
+with the conditions stated in this License.
+
+5. Submission of Contributions.
+
+Unless You explicitly state otherwise, any Contribution intentionally submitted
+for inclusion in the Work by You to the Licensor shall be under the terms and
+conditions of this License, without any additional terms or conditions.
+Notwithstanding the above, nothing herein shall supersede or modify the terms of
+any separate license agreement you may have executed with Licensor regarding
+such Contributions.
+
+6. Trademarks.
+
+This License does not grant permission to use the trade names, trademarks,
+service marks, or product names of the Licensor, except as required for
+reasonable and customary use in describing the origin of the Work and
+reproducing the content of the NOTICE file.
+
+7. Disclaimer of Warranty.
+
+Unless required by applicable law or agreed to in writing, Licensor provides the
+Work (and each Contributor provides its Contributions) on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied,
+including, without limitation, any warranties or conditions of TITLE,
+NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A PARTICULAR PURPOSE. You are
+solely responsible for determining the appropriateness of using or
+redistributing the Work and assume any risks associated with Your exercise of
+permissions under this License.
+
+8. Limitation of Liability.
+
+In no event and under no legal theory, whether in tort (including negligence),
+contract, or otherwise, unless required by applicable law (such as deliberate
+and grossly negligent acts) or agreed to in writing, shall any Contributor be
+liable to You for damages, including any direct, indirect, special, incidental,
+or consequential damages of any character arising as a result of this License or
+out of the use or inability to use the Work (including but not limited to
+damages for loss of goodwill, work stoppage, computer failure or malfunction, or
+any and all other commercial damages or losses), even if such Contributor has
+been advised of the possibility of such damages.
+
+9. Accepting Warranty or Additional Liability.
+
+While redistributing the Work or Derivative Works thereof, You may choose to
+offer, and charge a fee for, acceptance of support, warranty, indemnity, or
+other liability obligations and/or rights consistent with this License. However,
+in accepting such obligations, You may act only on Your own behalf and on Your
+sole responsibility, not on behalf of any other Contributor, and only if You
+agree to indemnify, defend, and hold each Contributor harmless for any liability
+incurred by, or claims asserted against, such Contributor by reason of your
+accepting any such warranty or additional liability.

--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/README.md	Thu May 10 06:28:36 2018 -0500
@@ -0,0 +1,369 @@
+# Simple Mbed Cloud Client template application
+
+## Overview
+
+This is a template application for platform vendors. It demonstrates how to create a simple Mbed Cloud Client application that can connect to Mbed Cloud, register resources and get ready to receive a firmware update.
+
+It's intended to be customized to add platform-specific features (such as sensors and actuators) and configure the connectivity and storage to work **out-of-the-box**. The Simple Mbed Cloud Client template application works in **developer mode** by default.
+
+## Setup process
+
+This is a summary of the process for developers to get started and get a device connected to Mbed Cloud.
+
+### Mbed Online IDE
+
+1. Import the application into the Online IDE.
+2. Add the API key to establish connection to Mbed Cloud.
+3. Install the developer certificate.
+4. Compile and program.
+
+### Mbed CLI tools
+
+1. Import the application in developer's desktop:
+
+    ```
+    mbed import https://os.mbed.com/teams/mbed-os-examples/code/mbed-cloud-example
+    cd mbed-cloud-example
+    ```
+
+2. Download the developer certificate from Mbed Cloud.
+3. Compile and program:
+
+    ```
+    mbed compile -t <toolchain> -m <target> -f
+    ```
+
+## Porting to a new platform
+
+### Requirements
+
+The hardware requirements for Mbed OS platforms to support Mbed Cloud Client are [here](https://cloud.mbed.com/docs/current/cloud-requirements/index.html).
+
+In general, to start creating a secure connected product, you need a microcontroller that has the following features.
+* RAM: 96K or more
+* Flash: 512K or more
+* True Random Number Generator (TRNG)
+* Real Time Clock (RTC)
+
+Additionally, to use Mbed Cloud Client, the microcontroller needs to support the following in Mbed OS (latest version preferred) or in a compatible driver library:
+* A storage device (SDcard, SPI Flash, Data Flash)
+* IP connectivity (Ethernet, WiFi, Cellular, 6LoWPAN, Thread)
+
+For the Firmware update over the air (FOTA), you need the following:
+* [FlashIAP](https://github.com/ARMmbed/mbed-os/blob/master/drivers/FlashIAP.h) - Flash In-Application Programming (IAP)
+* [Mbed Bootloader](https://github.com/ARMmbed/mbed-bootloader) or a bootloader compatible with Mbed Cloud Client.
+
+### References
+
+* Check which Mbed OS platforms are supported in the [Mbed Cloud quick-start guide](https://cloud.test.mbed.com/quick-start).
+* Check which storage options are available [here](https://os.mbed.com/docs/v5.8/reference/storage.html).
+* Check which network options are available [here](https://os.mbed.com/docs/v5.8/reference/network-socket.html).
+
+
+### Porting steps
+
+Supporting a new derivative platform requires the following steps:
+
+* Fork the template and create an example application for your platform in https://os.mbed.com.
+* (Optional) Change the connectivity interface. Ethernet is the default - see `main.cpp`.
+* (Optional) Change the filesystem and/or the block device for storage. FAT filesystem over SD card is the default. See `main.cpp`.
+* (Optional) Make minor changes in `mbed_app.json` to support multiple platforms with same connectivity and storage.
+
+<span class="notes">**Note:** Make sure that the application works out-of-the-box and no changes are required in the `main.cpp` file. The goal is to deliver a great UX to our developers.</span>
+
+### Porting example
+
+In this example, an app with an SD card and on-chip Ethernet is taken to a custom board that has an MCU + Wi-Fi module.
+
+#### Changing the storage option
+
+##### For an SD card
+
+1. Add the SD card driver (`sd-driver.lib`) if it is not already added.
+
+    On the command line:
+
+    ```
+    mbed add https://github.com/armmbed/sd-driver
+    ```
+
+2. In the online compiler, click **Import**, then click here to import from URL.
+3. Then enter https://github.com/armmbed/sd-driver for the **Source URL** and **Import As:** Library.
+4. Include the header files for the SD driver and FAT file system:
+
+    ```cpp
+    #include "SDBlockDevice.h"
+    #include "FATFileSystem.h"
+    ```
+
+5. Declare the global objects for the SD card and file system.
+
+    ```cpp
+    SDBlockDevice bd(SPI_MOSI, SPI_MISO, SPI_CLK, SPI_CS);
+    FATFileSystem fs("sd", &sd);
+    ```
+
+<span class="notes">**Note:** The `SPI_*` macros represent the pin names. The names can be defined in a variety of places including the sd-driver, your project’s configuration file (`mbed_app.json`) or the `pinnames.h` file for the target that defines the default pin names. You can use other pin names depending on the platform and the connections.</span>
+
+For example, if the SPI signals for the SD card interface are connected on an Arduino compatible shield, you may define them like this:
+
+```cpp
+SDBlockDevice sd(D11, D12, D13, D10);
+```
+
+##### For SPI Flash (devices that support SFDP)
+
+<Please note that this section of the document is under construction.  More information is needed.>
+
+1. Add the SPI Flash driver (`spif-driver`) if it is not already added.
+
+    ```
+    mbed add https://github.com/ARMmbed/spif-driver
+    ```
+
+2. Include the header files for the SPI Flash driver and LitteFS file system. For SPI Flash, we recommend LittleFS file system which supports wear leveling.
+
+    ```cpp
+    #include "SPIFBlockDevice.h"
+    #include "LittleFileSystem.h"
+    ```
+
+3. Declare the global objects for the SD card and file system:
+
+    ```cpp
+    SPIFBlockDevice spif(SPI_MOSI, SPI_MISO, SPI_CLK, SPI_CS);
+    LittleFileSystem fs("fs", &spif);
+    ```
+
+4. Update the construction of the `SimpleMbedCloudClient` object to pass in the file system and block device:
+
+    ```cpp
+    SimpleMbedCloudClient client(&net, &spif, &fs);
+    ```
+
+#### Changing the network interface
+
+##### For Ethernet
+
+The Ethernet interface is included within Mbed OS, so you do not need to add a library.
+
+1. Include the header file for the interface.
+
+    ```
+    #include "EthernetInterface.h"
+    ```
+
+2. Declare the network interface object.
+
+    ```
+    EthernetInterface net;
+    ```
+
+3. Connect the interface.
+
+    ```
+    status = net.connect();
+    ```
+
+4. When the Mbed Cloud Client is started, pass the network interface.
+
+    ```
+    SimpleMbedCloudClient client(&net, &sd, &fs);
+    ```
+
+##### For WiFi
+
+This example references the ESP8266 WiFi module, but the instructions are applicable to other modules.
+
+1. Add the ESP8266 WiFi interface driver (esp8266-driver) if it is not already added.
+
+    ```
+    Mbed add https://github.com/ARMmbed/esp8266-driver
+    ```
+
+    <span class="notes">**Note:** You may have to update the firmware inside the ESP8266 module.</span>
+
+2. Include the header file for the interface.
+
+    ```cpp
+    #include "ESP8266Interface.h"
+    ```
+
+3. Add the driver configuration information in `mbed_app.json` (located at the top level of the Mbed Cloud Connect example project).
+
+    ```json
+        "config": {
+            "wifi-ssid": {
+                "help": "WiFi SSID",
+                "value": "\"SSID\""
+            },
+            "wifi-password": {
+                "help": "WiFi Password",
+                "value": "\"PASSWORD\""
+            }
+        }
+    ```
+
+4. Declare the network interface object.
+
+    ```cpp
+    ESP8266Interface net(D1, D0);
+    ```
+
+5. Connect the interface.
+
+    ```cpp
+    nsapi_error_t status = net.connect(MBED_CONF_APP_WIFI_SSID, MBED_CONF_APP_WIFI_PASSWORD, NSAPI_SECURITY_WPA_WPA2);
+    ```
+
+6. When the Mbed Cloud Client is started, pass the network interface.
+
+    ```cpp
+    SimpleMbedCloudClient client(&net, &sd, &fs);
+    ```
+
+#### Changing the target MCU
+
+To change the target board to another board that is supported by Mbed OS, simply change the target name.
+
+##### Using the command line
+
+Use the -m option.
+
+```
+mbed compile -m Hexiwear -t GCC_ARM
+```
+
+##### Using the online compiler
+
+Click the platform name on the top right corner, then select another platform.
+
+##### Using an IDE
+
+First re-export (create project files) for the target with the command line.
+
+```
+mbed export -m Hexiwear -i uvision
+```
+
+#### Creating a custom target board
+
+Read the Mbed OS [Contributing](https://os.mbed.com/docs/latest/reference/porting-targets.html) documentation on how to add a new target.
+
+#### Update the application logic
+
+The template example uses a ticker object to periodically fire a software interrupt to simulate button presses. Let’s say you want to make an actual button press.
+
+By default, there is a Ticker object, which fires every five seconds and invokes a callback function.
+
+```cpp
+Ticker timer;
+timer.attach(eventQueue.event(&fake_button_press), 5.0);
+```
+
+This callback function changes the `button_res` resource:
+
+```cpp
+void fake_button_press() {
+    int v = button_res->get_value_int() + 1;
+
+    button_res->set_value(v);
+
+    printf("Simulated button clicked %d times\n", v);
+}
+```
+
+If you want to change this to an actual button, here is how to do it:
+
+1. Remove:
+
+    ```cpp
+    Ticker timer;
+    timer.attach(eventQueue.event(&fake_button_press), 5.0);
+    ```
+
+1. Declare an `InterruptIn` object on the button, and attach the callback function to the `fall` handler:
+
+    ```cpp
+    InterruptIn btn(BUTTON1);
+    btn.fall(eventQueue.event(&fake_button_press), 5.0);
+    ```
+
+1. Rename `fake_button_press` to `real_button_press`.
+
+
+#### Updating the LwM2M objects
+
+See guide at [TODO]
+
+## Enabling firmware updates
+
+To enable firmware updates, a compatible bootloader needs to be added in the `tools/` folder. The process to merge the application with the bootloader currently only works when building with Mbed CLI. In the future, this combine process will be done automatically by Mbed tools.
+
+1. Compile [mbed-bootloader](https://github.com/armmbed/mbed-bootloader) for the platform and storage configuration used in this application. Place the binary in the tools folder.
+
+1. Add a section to `mbed_app.json` under `target_overrides` with the bootloader configuration. For example:
+
+    ```json
+        "K64F": {
+            "target.mbed_app_start"            : "0x0000a400",
+            "update-client.bootloader-details" : "0x00007188",
+            "sotp-section-1-address"           : "(32*1024)",
+            "sotp-section-1-size"              : "( 4*1024)",
+            "sotp-section-2-address"           : "(36*1024)",
+            "sotp-section-2-size"              : "( 4*1024)",
+            "update-client.application-details": "(40*1024)"
+        }
+    ```
+
+Next, instruct your users to do the following:
+
+1. Install the [manifest tool](https://github.com/armmbed/manifest-tool).
+1. Generate an update certificate:
+
+    ```
+    $ manifest-tool init -a YOUR_MBED_CLOUD_API_KEY -d yourdomain.com -m device-model-id -q --force
+    ```
+
+    <span class="notes">**Note:** Make sure to replace `YOUR_MBED_CLOUD_API_KEY` with an Mbed Cloud API key.
+
+1. Build the application and combine it with the bootloader:
+
+    ```
+    $ mbed compile -m YOUR_TARGET -t GCC_ARM
+    $ tools/combine_bootloader_with_app.py -m YOUR_TARGET -a BUILD/YOUR_TARGET/GCC_ARM/simple-mbed-cloud-client-example_application.bin -o combined.bin
+    ```
+
+1. Flash `combined.bin` to the development board.
+1. Write down the endpoint ID of the board. You need it to start the update.
+
+Now, a firmware update can be scheduled as explained in the [Mbed Cloud documentation](https://cloud.mbed.com/docs/current/updating-firmware/index.html). You can do it with the manifest tool itself or via the Mbed Cloud portal. Here we explain how to do it with the manifest tool.
+
+1. Change the application, for example by changing some strings in `main.cpp`.
+1. Compile the application:
+
+    ```
+    $ mbed compile -m YOUR_TARGET -t GCC_ARM
+    ```
+
+1. The manifest tool can both sign the update - using the private key generated earlier - and upload it to Mbed Cloud in a single command. Run:
+
+    ```
+    $ manifest-tool update device -p BUILD/YOUR_BOARD_NAME/GCC_ARM/simple-mbed-cloud-client-example_application.bin -D YOUR_ENDPOINT_NAME
+    ```
+
+    Replace `YOUR_BOARD_NAME` with the name of your development board, and replace `YOUR_ENDPOINT_NAME` with the endpoint name in Mbed Cloud.
+
+1. Inspect the logs on the device to see the update progress. It looks similar to:
+
+    ```
+    Firmware download requested
+    Authorization granted
+    Downloading: [+++- ] 6 %
+    ```
+
+1. When the download completes, the firmware is verified. If everything is OK, the firmware update is applied.
+
+## Known issues
+
+Please check the issues reported on github.

--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/update_default_resources.c	Thu May 10 06:28:36 2018 -0500
@@ -0,0 +1,41 @@
+// ----------------------------------------------------------------------------
+// Copyright 2016-2018 ARM Ltd.
+//
+// SPDX-License-Identifier: Apache-2.0
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+// ----------------------------------------------------------------------------
+
+#ifdef MBED_CLOUD_CLIENT_USER_CONFIG_FILE
+#include MBED_CLOUD_CLIENT_USER_CONFIG_FILE
+#endif
+
+#include <stdint.h>
+
+#ifdef MBED_CLOUD_DEV_UPDATE_ID
+const uint8_t arm_uc_vendor_id[16] = { "dev_manufacturer" };
+const uint16_t arm_uc_vendor_id_size = sizeof(arm_uc_vendor_id);
+
+const uint8_t arm_uc_class_id[16]  = { "dev_model_number" };
+const uint16_t arm_uc_class_id_size = sizeof(arm_uc_class_id);
+#endif
+
+#ifdef MBED_CLOUD_DEV_UPDATE_CERT
+const uint8_t arm_uc_default_fingerprint[32] = { 0 };
+const uint16_t arm_uc_default_fingerprint_size =
+    sizeof(arm_uc_default_fingerprint);
+
+const uint8_t arm_uc_default_certificate[1] = { 0 };
+const uint16_t arm_uc_default_certificate_size =
+    sizeof(arm_uc_default_certificate);
+#endif