From 539d191d8eb76a5a0b4c4a78ae77e46cb9558b2e Mon Sep 17 00:00:00 2001 From: Oguz Bastemur Date: Fri, 27 Apr 2018 13:37:32 -0700 Subject: [PATCH] update licenses and readme - update to latest license details - fix formatting - fix firmware URL --- AZ3166/LICENSE | 33 +++++---- AZ3166/readme.md | 164 ++++++++++++++++++++++++++++++++---------- LICENSE | 31 ++++---- ThirdPartyNotices.txt | 5 +- 4 files changed, 167 insertions(+), 66 deletions(-) diff --git a/AZ3166/LICENSE b/AZ3166/LICENSE index bc0a5cf..dece23a 100644 --- a/AZ3166/LICENSE +++ b/AZ3166/LICENSE @@ -1,20 +1,23 @@ -microsoft-iot-central-firmware +The MIT License (MIT) + +azure-iot-central-firmware Copyright (c) Microsoft Corporation All rights reserved. -MIT License +Permission is hereby granted, free of charge, to any person obtaining a copy +of this software and associated documentation files (the "Software"), to deal +in the Software without restriction, including without limitation the rights +to use, copy, modify, merge, publish, distribute, sublicense, and/or sell +copies of the Software, and to permit persons to whom the Software is +furnished to do so, subject to the following conditions: -Permission is hereby granted, free of charge, to any person obtaining a copy of this software and -associated documentation files (the Software), to deal in the Software without restriction, including -without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or -sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject -to the following conditions: +The above copyright notice and this permission notice shall be included in all +copies or substantial portions of the Software. -The above copyright notice and this permission notice shall be included in all copies or substantial -portions of the Software. - -THE SOFTWARE IS PROVIDED *AS IS*, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT -LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN -NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, -WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE -SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. \ No newline at end of file +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE +AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, +OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE +SOFTWARE. diff --git a/AZ3166/readme.md b/AZ3166/readme.md index 970aedf..b30daab 100644 --- a/AZ3166/readme.md +++ b/AZ3166/readme.md @@ -2,12 +2,27 @@ ## Description: -An example of writing a firmware solution to send data to Azure IoT Central and to receive events back from Azure IoT Central to be processed by the device. You are free to take this code and the concepts used, and use them as a basis for your own firmware for Azure IoT Central. +An example of writing a firmware solution to send data to Azure IoT Central and +to receive events back from Azure IoT Central to be processed by the device. + +You are free to take this code and the concepts used, and use them as a basis +for your own firmware for Azure IoT Central. The aim of this firmware and code is two-fold: -- To provide a good "out of the box" experience for someone wanting to connect a device to Azure IoT Central and see real data sent to Azure IoT Central. The firmware was designed to simplify the onboarding experience via a web UX configuration and allow non-developer users to get a device onto Azure IoT Central very easily. -- To illustrate how to write a functioning firmware for an mbed device that supports the features of Azure IoT Central. The code pulls together many of the individual samples available in the Azure IoT device C SDK into a cohesive story, using relatively simple code. The code was written in C using the Arduino libraries in an attempt to make it accessible to all development levels from hobbyist to professional. Tooling for the code is done with Visual Studio Code and the Arduino plugin allowing for visual debugging in the IDE of the code. +- To provide a good "out of the box" experience for someone wanting to connect a +device to Azure IoT Central and see real data sent to Azure IoT Central. +The firmware was designed to simplify the onboarding experience via a web UX +configuration and allow non-developer users to get a device onto Azure IoT +Central very easily. + +- To illustrate how to write a functioning firmware for an mbed device that +supports the features of Azure IoT Central. The code pulls together many of the +individual samples available in the Azure IoT device C SDK into a cohesive story, +using relatively simple code. The code was written in C/CPP using the Arduino +libraries in an attempt to make it accessible to all development levels from +hobbyist to professional. Tooling for the code is done with Visual Studio Code +and the Arduino plugin allowing for visual debugging in the IDE of the code. *** @@ -15,16 +30,24 @@ The aim of this firmware and code is two-fold: - Simple onboarding via a web UX - Simple device reset (press and hold the A & B buttons at the same time) -- Display shows count of messages, errors, twin events, network information, and device name (cycle through screens with B button) +- Display shows count of messages, errors, twin events, network information, +and device name (cycle through screens with B button) - Telemetry sent for all onboard sensors (configurable) -- State change telemetry sent when button A pressed and the device cycles through the three states (NORMAL, CAUTION, DANGER) -- Reported twin property die number is sent when shaking the device (uses accelerometer sensor data) -- Desired twin property to simulate turning on a fan (fan sound plays from onboard headphone jack) -- Desired twin properties of current and voltage of the device (trigger a bar graph animation) -- Desired twin property of IR blaster that sends a short burst from the IR emmitter on the board +- State change telemetry sent when button A pressed and the device cycles +through the three states (NORMAL, CAUTION, DANGER) +- Reported twin property die number is sent when shaking the device +(uses accelerometer sensor data) +- Desired twin property to simulate turning on a fan (fan sound plays from +onboard headphone jack) +- Desired twin properties of current and voltage of the device (trigger a bar +graph animation) +- Desired twin property of IR blaster that sends a short burst from the IR +emmitter on the board - Cloud to device messages (supports sending a message to display on the screen) -- Direct twin method calls (supports asking the device to play a rainbow sequence on the RGB LED) -- LED status of network, Azure IoT send events, Azure IoT error events, and current device state (NORMAL=green, CAUTION=amber, DANGER=red) +- Direct twin method calls (supports asking the device to play a rainbow +sequence on the RGB LED) +- LED status of network, Azure IoT send events, Azure IoT error events, and +current device state (NORMAL=green, CAUTION=amber, DANGER=red) *** @@ -32,13 +55,18 @@ The aim of this firmware and code is two-fold: Device features -Pressing the B button will rotate through three screens of information in the following order "data transmission statistics" -> "Device information" -> "Network information" –> back to "data transmission statistics". The screens look like this: +Pressing the B button will rotate through three screens of information in the +following order "data transmission statistics" -> "Device information" -> +"Network information" –> back to "data transmission statistics". The screens +look like this: Device screens -The Data transmission screen (first screen above) has the following information by line: +The Data transmission screen (first screen above) has the following information +by line: -- Count of sent telemetry events (includes telemetry payloads and state change telemetry payloads) +- Count of sent telemetry events (includes telemetry payloads and state change +telemetry payloads) - Count of failed telemetry events - Twin events desired / reported @@ -46,19 +74,31 @@ The Data transmission screen (first screen above) has the following information ## Connecting the device to Azure IoT Central: -Please visit our [general documentation site](https://aka.ms/iotcentral-doc-mxchip) for a tutorial on how to connect the device to Azure IoT Central. +Please visit our [general documentation site](https://aka.ms/iotcentral-doc-mxchip) +for a tutorial on how to connect the device to Azure IoT Central. *** ## Resetting the device: -To reset the board press and hold both the A and the B buttons together until the device displays "Resetting device". The device will then return to the AP mode and display the WiFi hotspot name for you to connect to and reconfigure the board. This action wipes all the configuration data from the device, essentially factory resetting it. +To reset the board press and hold both the A and the B buttons together until +the device displays "Resetting device". The device will then return to the AP +mode and display the WiFi hotspot name for you to connect to and reconfigure the +board. This action wipes all the configuration data from the device, essentially +factory resetting it. *** ## Updating the firmware on the device: -The firmware on the device can be updated by downloading a newer version of the firmware from [https://github.com/Microsoft/microsoft-iot-central-firmware/release](https://github.com/Microsoft/microsoft-iot-central-firmware/release). Then with the device connected to the computer the file (iotCentral<version>.bin) can be copied onto the drive named AZ3166. Once the file has been copied onto the device it will reset itself and boot up with the new firmware version. All configuration will remain on the device and if there are no breaking changes in the configuration the device will connect to Azure IoT and start sending data. +The firmware on the device can be updated by downloading a newer version of the +firmware from [https://aka.ms/devkit/prod/firmware/latest](https://aka.ms/devkit/prod/firmware/latest). +Then with the device connected to the computer the file (iotCentral<version>.bin) +can be copied onto the drive named AZ3166. Once the file has been copied onto +the device it will reset itself and boot up with the new firmware version. +All configuration will remain on the device and if there are no breaking +changes in the configuration the device will connect to Azure IoT and start +sending data. *** @@ -66,24 +106,43 @@ The firmware on the device can be updated by downloading a newer version of the ### Prerequisites: -- Install the Azure IoT Developer Kit by following the manual installation instructions at [https://microsoft.github.io/azure-iot-developer-kit/docs/installation/](https://microsoft.github.io/azure-iot-developer-kit/docs/installation/) . There are instructions for Windows and macOS PC's. You can ignore Step 1 as this is not needed to build the firmware. -- Ensure your device has been upgraded to the latest base firmware. Instructions for downloading the firmware from here [https://microsoft.github.io/azure-iot-developer-kit/versions/](https://microsoft.github.io/azure-iot-developer-kit/versions/) +- Install the Azure IoT Developer Kit by following the manual installation +instructions at [https://microsoft.github.io/azure-iot-developer-kit/docs/installation/](https://microsoft.github.io/azure-iot-developer-kit/docs/installation/) +There are instructions for Windows and macOS PC's. You can ignore Step 1 as +this is not needed to build the firmware. + +- Ensure your device has been upgraded to the latest base firmware. +Instructions for downloading the firmware from here [https://microsoft.github.io/azure-iot-developer-kit/versions/](https://microsoft.github.io/azure-iot-developer-kit/versions/) - Install Git tools for your operating system - Clone the IoTCentral firmware repository on Github [https://github.com/Microsoft/microsoft-iot-central-firmware](https://github.com/Microsoft/microsoft-iot-central-firmware) Opening the code in Visual Studio Code and getting connected to the device: - Connect the development board to your computer via the USB cable -- From the command line change directory into the directory you cloned the repo and use the command: code . -- Once VS Code loads you should set the serial port of the board. Use `CTRL+SHIFT+P` (or `CMD+SHIFT+P` for MacOS) and type **Arduino** then find and select **Arduino: Select Serial Port**. A list of serial ports will be displayed select the one the device is connected to. In windows this can be found by looking at the device manager and looking in Ports for the COM port for the STMicroelectronics STLink Virtual COM Port. On macOS the port will be the one with /dev/cu.usbmodemXXXX STMicroElectronics -- Set the Serial board rate to 250000. Use `CTRL+SHIFT+P` (or `CMD+SHIFT+P` for MacOS) and type **Arduino** then find and select **Arduino: Change Baud rate** and select 250000 from the list. -- Select the board type. Use `CTRL+SHIFT+P` (or `CMD+SHIFT+P` for MacOS) and type **Arduino** and then find and select **Arduino: Change Board Type** and select **MXCHIP AZ3166** from the list. +- From the command line change directory into the directory you cloned the repo +and use the command: code . +- Once VS Code loads you should set the serial port of the board. Use `CTRL+SHIFT+P` +(or `CMD+SHIFT+P` for MacOS) and type **Arduino** then find and select +**Arduino: Select Serial Port**. A list of serial ports will be displayed select +the one the device is connected to. In windows this can be found by looking at +the device manager and looking in Ports for the COM port for the +STMicroelectronics STLink Virtual COM Port. On macOS the port will be the one +with /dev/cu.usbmodemXXXX STMicroElectronics +- Set the Serial board rate to 250000. Use `CTRL+SHIFT+P` (or `CMD+SHIFT+P` for +MacOS) and type **Arduino** then find and select **Arduino: Change Baud rate** +and select 250000 from the list. +- Select the board type. Use `CTRL+SHIFT+P` (or `CMD+SHIFT+P` for MacOS) and +type **Arduino** and then find and select **Arduino: Change Board Type** and +select **MXCHIP AZ3166** from the list. Building and uploading the code to the device: -- To build the code use `CTRL+SHIFT+P` (or `CMD+SHIFT+P` for MacOS) and type **Arduino** then find and select **Arduino: Upload** -- The source will build and be uploaded to the device, this can take several minutes. If there are errors they will be displayed in the Output window -- Once uploaded the device will restart and boot into the newly uploaded firmware and start executing +- To build the code use `CTRL+SHIFT+P` (or `CMD+SHIFT+P` for MacOS) and +type **Arduino** then find and select **Arduino: Upload** +- The source will build and be uploaded to the device, this can take several +minutes. If there are errors they will be displayed in the Output window +- Once uploaded the device will restart and boot into the newly uploaded +firmware and start executing ### Dependencies: @@ -95,32 +154,65 @@ Uses the following libraries: - AzureIoTProtocol_MQTT - https://github.com/Azure/azure-iot-arduino-protocol-mqtt - Third party libraries used: - - ArduinoJson - https://bblanchon.github.io/ArduinoJson/ + - Parson ( http://kgabis.github.com/parson/ ) Copyright (c) 2012 - 2017 Krzysztof Gabis ### Debugging: -You can debug via Serial print commands in the code or with the ST-Link debugger that provides full visual debugging. To observe Serial output you need to start the serial port monitor in VS Code. Use `CTRL+SHIFT+P` macOS (`CMD+SHIFT+P`) and type **Arduino** then find and select **Arduino: Open Serial Monitor**. The Serial port monitor will be opened in the output window and serial port messages will be displayed. If the output is garbled then check to make sure you have the baud rate set at 250000. +You can debug via Serial print commands in the code or with the ST-Link +debugger that provides full visual debugging. To observe Serial output you need +to start the serial port monitor in VS Code. Use `CTRL+SHIFT+P` macOS +(`CMD+SHIFT+P`) and type **Arduino** then find and select +**Arduino: Open Serial Monitor**. The Serial port monitor will be opened in +the output window and serial port messages will be displayed. If the output +is garbled then check to make sure you have the baud rate set at 250000. -For more complete debugging you can select the debug tool on the left-hand toolbar of VS Code. Then set any breakpoints in the code as normal and press the debug play button in the top left-hand corner. The debugger will start shortly and breakpoints will be observed. When a breakpoint fires you can look at variable values and step through the code like any normal debugging session. +For more complete debugging you can select the debug tool on the left-hand +toolbar of VS Code. Then set any breakpoints in the code as normal and press +the debug play button in the top left-hand corner. The debugger will start +shortly and breakpoints will be observed. When a breakpoint fires you can +look at variable values and step through the code like any normal debugging +session. ### Note: -- Debugging the device can be a little unstable at times, placing breakpoints during debugging will sometimes not be honored and stepping through the code is quite slow. -- When exiting debugging (pressing the stop button in the debugger toolbar) the device might be in an inconsistent state (programming LED flashing) this will result in uploads failing and new debugging sessions also failing. To resolve this unplug the USB cable from the computer and plug it back in. the device and COM port will reset and the device will function normally from that point on. -- When debugging a shadow copy of the code is used and will be shown in the VS code editor. Be aware that making changes in the shadow copy will not be persisted in the real source code and you will lose them in subsequent builds – BE AWARE OF THIS!! +- Debugging the device can be a little unstable at times, placing breakpoints +during debugging will sometimes not be honored and stepping through the code is +quite slow. +- When exiting debugging (pressing the stop button in the debugger toolbar) the +device might be in an inconsistent state (programming LED flashing) this will +result in uploads failing and new debugging sessions also failing. To resolve +this unplug the USB cable from the computer and plug it back in. The device and +COM port will reset and the device will function normally from that point on. +- When debugging a shadow copy of the code is used and will be shown in the VS +code editor. Be aware that making changes in the shadow copy will not be +persisted in the real source code and you will lose them in subsequent +builds – BE AWARE OF THIS!! *** ## Troubleshooting: -- Sometimes when resetting the device the web page for configuring the device ( [http://192.168.0.1/start](http://192.168.0.1/start) ) will fail to load or display a blank page. Please reset the device and it will come up in AP mode and you can reconnect to the WiFi hotspot the board supplies and try to access the page again. +- Sometimes when resetting the device the web page for configuring the device +( [http://192.168.0.1/start](http://192.168.0.1/start) ) will fail to load or +display a blank page. Please reset the device and it will come up in AP mode +and you can reconnect to the WiFi hotspot the board supplies and try to access +the page again. *** ## Contributing: -This project welcomes contributions and suggestions. Most contributions require you to agree to a Contributor License Agreement (CLA) declaring that you have the right to, and actually do, grant us the rights to use your contribution. For details, visit [https://cla.microsoft.com](https://cla.microsoft.com/). +This project welcomes contributions and suggestions. Most contributions require +you to agree to a Contributor License Agreement (CLA) declaring that you have +the right to, and actually do, grant us the rights to use your contribution. +For details, visit [https://cla.microsoft.com](https://cla.microsoft.com/). -When you submit a pull request, a CLA-bot will automatically determine whether you need to provide a CLA and decorate the PR appropriately (e.g., label, comment). Simply follow the instructions provided by the bot. You will only need to do this once across all repos using our CLA. +When you submit a pull request, a CLA-bot will automatically determine whether +you need to provide a CLA and decorate the PR appropriately (e.g., label, +comment). Simply follow the instructions provided by the bot. You will only +need to do this once across all repos using our CLA. -This project has adopted the [Microsoft Open Source Code of Conduct](https://opensource.microsoft.com/codeofconduct/). For more information see the [Code of Conduct FAQ](https://opensource.microsoft.com/codeofconduct/faq/) or contact [opencode@microsoft.com](mailto:opencode@microsoft.com) with any additional questions or comments. \ No newline at end of file +This project has adopted the [Microsoft Open Source Code of Conduct](https://opensource.microsoft.com/codeofconduct/). +For more information see the [Code of Conduct FAQ](https://opensource.microsoft.com/codeofconduct/faq/) +or contact [opencode@microsoft.com](mailto:opencode@microsoft.com) with any +additional questions or comments. \ No newline at end of file diff --git a/LICENSE b/LICENSE index d670bb0..dece23a 100644 --- a/LICENSE +++ b/LICENSE @@ -1,20 +1,23 @@ +The MIT License (MIT) + azure-iot-central-firmware Copyright (c) Microsoft Corporation All rights reserved. -MIT License +Permission is hereby granted, free of charge, to any person obtaining a copy +of this software and associated documentation files (the "Software"), to deal +in the Software without restriction, including without limitation the rights +to use, copy, modify, merge, publish, distribute, sublicense, and/or sell +copies of the Software, and to permit persons to whom the Software is +furnished to do so, subject to the following conditions: -Permission is hereby granted, free of charge, to any person obtaining a copy of this software and -associated documentation files (the Software), to deal in the Software without restriction, including -without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or -sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject -to the following conditions: +The above copyright notice and this permission notice shall be included in all +copies or substantial portions of the Software. -The above copyright notice and this permission notice shall be included in all copies or substantial -portions of the Software. - -THE SOFTWARE IS PROVIDED *AS IS*, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT -LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN -NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, -WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE -SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE +AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, +OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE +SOFTWARE. diff --git a/ThirdPartyNotices.txt b/ThirdPartyNotices.txt index 35c31db..c830489 100644 --- a/ThirdPartyNotices.txt +++ b/ThirdPartyNotices.txt @@ -1,6 +1,9 @@ Third Party Software Notices and Information Do not translate or localize -This project incorporates components from the projects listed below. The original copyright notices and the licenses under which Microsoft received such components are set forth below. Microsoft reserves all rights not expressly granted herein, whether by implication, estoppel or otherwise. +This project incorporates components from the projects listed below. +The original copyright notices and the licenses under which Microsoft received +such components are set forth below. Microsoft reserves all rights not expressly +granted herein, whether by implication, estoppel or otherwise. ****