- update to latest license details
- fix formatting
- fix firmware URL
This commit is contained in:
Oguz Bastemur 2018-04-27 13:37:32 -07:00
Родитель f43bc57568
Коммит 539d191d8e
4 изменённых файлов: 167 добавлений и 66 удалений

Просмотреть файл

@ -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.
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.

Просмотреть файл

@ -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:
<img src="images/device.png" alt="Device features" style="width: 700px;"/>
Pressing the B button will rotate through three screens of information in the following order "data transmission statistics" -&gt; "Device information" -&gt; "Network information" –&gt; 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" -&gt; "Device information" -&gt;
"Network information" –&gt; back to "data transmission statistics". The screens
look like this:
<img src="images/screens.png" alt="Device screens" style="width: 700px;"/>
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&lt;version&gt;.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&lt;version&gt;.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&#39;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&#39;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.
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.

31
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.

Просмотреть файл

@ -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.
****