diff --git a/content/hardware/05.nicla/boards/nicla-sense-me/tutorials/cheat-sheet/cheat-sheet.md b/content/hardware/05.nicla/boards/nicla-sense-me/tutorials/cheat-sheet/cheat-sheet.md index 6f2ff87c4e..af100584a3 100644 --- a/content/hardware/05.nicla/boards/nicla-sense-me/tutorials/cheat-sheet/cheat-sheet.md +++ b/content/hardware/05.nicla/boards/nicla-sense-me/tutorials/cheat-sheet/cheat-sheet.md @@ -33,7 +33,7 @@ featuredImage: 'gear' ![The Arduino Nicla Sense ME](assets/hero.png) -The Arduino® Nicla Sense ME is our smallest form factor yet, with a range of industrial grade sensors packed into a tiny footprint. It features 5 industrial grade Bosch sensors that can accurately measure rotation, acceleration, pressure, humidity, temperature, air quality and CO2 levels. +The Arduino® Nicla Sense ME is our smallest form factor yet, with a range of industrial grade sensors packed into a tiny footprint. It features 4 industrial grade Bosch sensors that can accurately measure rotation, acceleration, pressure, humidity, temperature, air quality and CO2 levels. ## Goals @@ -127,7 +127,7 @@ The Nicla System header is required to use the RGB LED. #include "Nicla_System.h" ``` -Since the functions are scoped under a specific name called "nicla" we can use the following statement to have convenient access without repeating explicitly the namespace before every function call. +Since the functions are scoped under a specific name called "nicla", you can use the following statement to have convenient access without repeating explicitly the namespace before every function call. ```cpp using namespace nicla; @@ -149,7 +149,7 @@ The LED can be set to the desired RGB value using red, green and blue components - magenta - cyan -To turn set the LED to a predefined color (e.g. green or blue): +To set the LED to a predefined color (e.g. green or blue): ```arduino void loop() { @@ -166,7 +166,7 @@ To turn the LED off: leds.setColor(off); ``` -We can also choose a value between 255 - 0 for each color component to set a custom color: +You can also choose a value between 255 - 0 for each color component to set a custom color: ```arduino void loop() { @@ -189,17 +189,17 @@ There are three ways to read from the on-board sensors: 2. Read sensor values through Bluetooth® Low Energy 3. Read sensor values through UART by connecting an ESLOV cable -To read from the sensors in any of these mode, you need to install the **Arduino_BHY2** and **Arduino_BHY2Host** libraries. These can be found in the library manager using the Arduino IDE. To do so in the IDE select **Tools->Manage Libraries...**, now search for **Arduino_BHY2** and **Arduino_BHY2Host** in the new window that opened and click on the install button. +To read from the sensors in any of these mode, you need to install the **Arduino_BHY2** and **Arduino_BHY2Host** libraries. These can be found in the library manager using the Arduino IDE. To do so in the IDE, select **Tools->Manage Libraries...**, now search for **Arduino_BHY2** and **Arduino_BHY2Host** in the new window that opened and click on the install button. -To use the sensors in our sketches, we need to know the sensors ID. You can find them in the section "Sensor IDs" of this article. They can also be found in the header file [here](https://github.com/arduino-libraries/Arduino_BHY2/blob/main/src/sensors/SensorID.h). Additionally, there is an example sketch in the library that will print all available sensors in the serial monitor of the Arduino IDE. This example sketch can be found in **File > Examples > Arduino_BHY2 > ShowSensorList** in the Arduino IDE. +To use the sensors in your sketches, you need to know the sensors ID. You can find them in the section "Sensor IDs" of this article. They can also be found in the header file [here](https://github.com/arduino-libraries/Arduino_BHY2/blob/main/src/sensors/SensorID.h). Additionally, there is an example sketch in the library that will print all available sensors in the Serial Monitor of the Arduino IDE. This example sketch can be found in **File > Examples > Arduino_BHY2 > ShowSensorList** in the Arduino IDE. -In the following section you can see how these ID's are used in an Arduino sketch. +In the following section, you can see how these ID's are used in an Arduino sketch. ### Sensor Classes - **Sensor**: This class handles all the other sensors which have a single value to be read, like temperature, gas, pressure, etc. And also the event sensors, like the step detector. This generic sensor class provides the sensor data through the `value` property. -- **SensorOrientation**: Use this class to handle sensors with the Euler format, used for example with orientation. It allows you to read the `pitch`, `roll` and `heading` property. -- **SensorXYZ**: This class handles sensors with the XYZ format, like the accelerometer and the gyroscope. Contains `x` `y` and `z` values +- **SensorOrientation**: This class handles sensors with the Euler format, used for example with orientation. It allows you to read the `pitch`, `roll` and `heading` property. +- **SensorXYZ**: This class handles sensors with the XYZ format, like the accelerometer and the gyroscope. It contains `x` `y` and `z` values - **SensorQuaternion**: Can be used to handle sensors with the quaternion format, can be used to calculate rotation vector, game rotation vector and geomagnetic rotation vector. You can access the `x`, `y`, `z` and `w` property using this class. - **SensorActivity**: Use this class to handle sensors with the activity format. The activity is encoded as ID and can be retrieved from the `value` property. Use `getActivity` to get a human readable version of the activity e.g. "Walking activity started". - **SensorBSEC**: BSEC stands for Bosch Sensortec Environmental Cluster, basically you can access the air quality (IAQ) level and it contains the following data: @@ -210,7 +210,7 @@ In the following section you can see how these ID's are used in an Arduino sketc | `iaq_s()` | IAQ value for stationary use cases | unsigned 16bit | | `b_voc_eq()` | breath VOC equivalent (ppm) | float | | `co2_eq()` | CO2 equivalent (ppm) [400,] | unsigned 32bit | - | `comp_t()` | compensated temperature (celsius) | float | + | `comp_t()` | compensated temperature (Celsius) | float | | `comp_h()` | compensated humidity | float | | `comp_g()` | compensated gas resistance (Ohms) | unsigned 32bit | | `accuracy()` | accuracy level: [0-3] | unsigned 8bit | @@ -334,10 +334,10 @@ void setup(){ } ``` -The `begin()` function starts the sensor by calling the `configure()` with default parameters, making it easy to start and use on-board sensors. The parameters in the `configure()` function are, sample rate and latency. If specific parameters are needed then simply call `configure()` with your preferred values. E.g.: `configure(10, 1)`. In this case the sample rate would be set to `10 Hz` and the latency would be `1ms`. +The `begin()` function starts the sensor by calling the `configure()` with default parameters, making it easy to start and use on-board sensors. The parameters in the `configure()` function are sample rate and latency. If specific parameters are needed, then simply call `configure()` with your preferred values. E.g.: `configure(10, 1)`. In this case, the sample rate would be set to `10 Hz` and the latency would be `1ms`. - **Sample rate** is used also to enable/disable the sensor. 0 to disable, > 0 to enable. -- **Latency** indicates how much ms time a new value is retained in its fifo before a notification to the host is sent via interrupt expressed in 24 bit +- **Latency** indicates how much ms time a new value is retained in its fifo before a notification to the host is sent via interrupt expressed in 24 bit. Reading the sensor values: @@ -372,7 +372,7 @@ short gyroZ = gyroscope.z(); #### Temperature -To read the temperature in standalone mode you also need to use the Arduino_BHY2 library as described in the section above. +To read the temperature in standalone mode, you also need to use the Arduino_BHY2 library as described in the section above. Follow these steps to use the library to read the sensor values. @@ -415,7 +415,7 @@ void loop(){ #### Gas -To get readings from the gas sensor in standalone mode you also need to use the Arduino_BHY2 library as described in the section above. +To get readings from the gas sensor in standalone mode, you also need to use the Arduino_BHY2 library as described in the section above. Follow these steps to use the library to read the sensor values. @@ -458,7 +458,7 @@ void loop(){ #### Pressure -To get readings from the pressure sensor in standalone mode you also need to use the Arduino_BHY2 library as described in the section above. +To get readings from the pressure sensor in standalone mode, you also need to use the Arduino_BHY2 library as described in the section above. Follow these steps to use the library to read the sensor values. @@ -500,7 +500,7 @@ void loop(){ ``` #### Quaternion Rotation -To get readings from the IMU in a quaternion format in standalone mode you also need to use the Arduino_BHY2 library as described in the section above. +To get readings from the IMU in a quaternion format in standalone mode, you also need to use the Arduino_BHY2 library as described in the section above. Follow these steps to use the library to read the sensor values. @@ -543,7 +543,7 @@ void loop(){ #### Activity -To get activity status in standalone mode you also need to use the Arduino_BHY2 library as described in the section above. +To get activity status in standalone mode, you also need to use the Arduino_BHY2 library as described in the section above. Follow these steps to use the library to read the sensor values. @@ -586,7 +586,7 @@ void loop(){ #### BSEC Data -To get readings from the BME sensor in standalone mode you also need to use the Arduino_BHY2 library as described in the section above. +To get readings from the BME sensor in standalone mode, you also need to use the Arduino_BHY2 library as described in the section above. Follow these steps to use the library to read the sensor values. @@ -635,11 +635,11 @@ In order to transmit data over ESLOV to another Arduino board you need to connec ![Two Arduino boards connected via ESLOV cable](assets/eslov-connection.svg) -1. To have the Nicla Sense ME pass the sensor data through ESLOV you need to upload the **App** sketch. You can find it in the Examples menu in the IDE under **Arduino_BH2 > App**. After you upload the sketch you can disconnect the Nicla Sense ME from the USB cable. It can be powered through the ESLOV connection. +1. To have the Nicla Sense ME pass the sensor data through ESLOV, you need to upload the **App** sketch. You can find it in the Examples menu in the IDE under **Arduino_BH2 > App**. After you upload the sketch, you can disconnect the Nicla Sense ME from the USB cable. It can be powered through the ESLOV connection. -1. For the receiving device you need to upload the passthrough sketch. You can find it in the Examples menu in the IDE under **Arduino_BHY2Host > Passthrough**. After you upload the sketch a separate serial port will be exposed. One port is used for debugging and the other one is used for passing through the sensor data. The latter one is the one you will use for configuring the sensors and reading from them. +2. For the receiving device you need to upload the passthrough sketch. You can find it in the Examples menu in the IDE under **Arduino_BHY2Host > Passthrough**. After you upload the sketch, a separate serial port will be exposed. One port is used for debugging and the other one is used for passing through the sensor data. The latter one is the one you will use to configure the sensors and read from them. -3. When you're done uploading the sketches you can use the **bhy** script to interact with the sensors. In the downloaded package (see [here](#sensors)) navigate into the tools folder. There you will find binaries of the bhy tool for Linux and Windows. If you like you can build the tool yourself (e.g. if you're on macOS). For that, if you haven't installed **Go** yet, please do so by following [there](https://golang.org/doc/install) instructions. +3. When you're done uploading the sketches, you can use the **bhy** script to interact with the sensors. In the downloaded package (see [here](#sensors)), navigate into the tools folder. There you will find binaries of the bhy tool for Linux and Windows. If you like, you can build the tool yourself (e.g. if you are on macOS). For that, if you haven't installed **Go** yet, please do so by following [there](https://golang.org/doc/install) instructions. From the terminal execute this command to start the build: `go build` 4. Use the bhy command as follows: @@ -693,12 +693,12 @@ Sensor id: 10 name: GYRO_PASS values: x : -12.000000 y : 12.000000 z : - Sensor id: 10 name: GYRO_PASS values: x : -13.000000 y : 12.000000 z : -10.000000 ``` -***If there is not ESLOV activity in the first minute after power up, the LDO is disabled and then also ESLOV is disabled. This has been made for low power reasons. However you could change this timeout by calling `BHY2.setLDOTimeout(milliSeconds)` from your sketch.*** +***If there is not ESLOV activity in the first minute after power up, the LDO is disabled and then also ESLOV is disabled. This has been made for low power reasons. However, you could change this timeout by calling `BHY2.setLDOTimeout(milliSeconds)` from your sketch.*** ### Sensor Data Over WebBLE Sensor data from the Nicla Sense ME can also be retrieved through Bluetooth® Low Energy in the web browser. For that you can use the bhy tool. Please follow steps 1 - 3 from the "Sensor Data Over ESLOV" section. Then execute the following command to start the webserver: `./bhy webserver`. -When the server has started you can open the landing page in your browser: [http://localhost:8000/](http://localhost:8000/). Click on "Open sensor page". +When the server has started, you can open the landing page in your browser: [http://localhost:8000/](http://localhost:8000/). Click on "Open sensor page". ![Sensor page in the browser](assets/web-ble-unpaired.png) @@ -714,7 +714,7 @@ Use the sensor IDs from the section "Sensor IDs" to enable and configure the des ## BSX Sensor Fusion Software -The BHI260AP sensor runs a customizable firmware based on the BSX Sensor Fusion library. It provides a complete 9-axis fusion solution, which combines the measurements from 3-axis gyroscope, 3-axis geomagnetic sensor and a 3-axis accelerometer to provide a robust absolute orientation vector. The algorithm fuses the sensor raw data from the accelerometer, geomagnetic sensor and gyroscope in an intelligent way to improve each sensor’s output. +The BHI260AP sensor runs a customizable firmware based on the BSX Sensor Fusion library. It provides a complete 9-axis fusion solution, which combines the measurements from 3-axis gyroscope, 3-axis geomagnetic sensor and a 3-axis accelerometer, to provide a robust absolute orientation vector. The algorithm fuses the sensor raw data from the accelerometer, geomagnetic sensor and gyroscope in an intelligent way to improve each sensor’s output. Go to this [site](https://www.bosch-sensortec.com/software-tools/software/sensor-fusion-software/) or take a look at the BHI260AP's [datasheet](https://www.bosch-sensortec.com/media/boschsensortec/downloads/datasheets/bst-bhi260ap-ds000.pdf) for more information. @@ -733,13 +733,13 @@ The pins used for SPI (Serial Peripheral Interface) on the Nicla Sense ME are th You can refer to the [pinout](#pins) above to find them on the board. -To use SPI, we first need to include the [SPI](https://www.arduino.cc/en/reference/SPI) library. +To use SPI, you first need to include the [SPI](https://www.arduino.cc/en/reference/SPI) library. ```arduino #include ``` -Inside `void setup()` we need to initialize the library. +Inside `void setup()` you need to initialize the library. ```arduino SPI.begin(); @@ -766,19 +766,19 @@ The pins used for I2C (Inter-Integrated Circuit) on the Nicla Sense ME are the f You can refer to the [pinout](#pins) above to find them on the board. -To use I2C, we can use the [Wire](https://www.arduino.cc/en/Reference/wire) library, which we need to include at the top of our sketch. +To use I2C, you can use the [Wire](https://www.arduino.cc/en/Reference/wire) library, which you need to include at the top of your sketch. ```arduino #include ``` -Inside `void setup()` we need to initialize the library. +Inside `void setup()` you need to initialize the library. ```arduino Wire.begin(); ``` -And to write something to a device connected via I2C, we can use the following commands: +And to write something to a device connected via I2C, you can use the following commands: ```arduino Wire.beginTransmission(1); //begin transmit to device 1 @@ -796,13 +796,13 @@ The pins used for UART (Universal asynchronous receiver-transmitter) are the fol You can refer to the pinout above to find them on the board. -To send and receive data through UART, we will first need to set the baud rate inside `void setup()`. +To send and receive data through UART, you will first need to set the baud rate inside `void setup()`. ```arduino Serial1.begin(9600); ``` -To read incoming data, we can use a while loop() to read each individual character and add it to a string. +To read incoming data, you can use a while loop() to read each individual character and add it to a string. ```arduino while(Serial1.available()){ @@ -812,7 +812,7 @@ To read incoming data, we can use a while loop() to read each individual charact } ``` -And to write something, we can use the following command: +And to write something, you can use the following command: ```arduino Serial1.write("Hello world!"); @@ -856,7 +856,7 @@ The parameters of `BHY2Host::begin` are: data pass through and communication con #### Using the Bluetooth® Low Energy Library -To enable Bluetooth® Low Energy on the Nicla Sense ME, we can use the [ArduinoBLE](https://www.arduino.cc/en/Reference/ArduinoBLE) library. The example sketches included in the library work also with Nicla Sense ME with some minor modifications: +To enable Bluetooth® Low Energy on the Nicla Sense ME, you can use the [ArduinoBLE](https://www.arduino.cc/en/Reference/ArduinoBLE) library. The example sketches included in the library work also with Nicla Sense ME with some minor modifications: Include the Nicla System header at the top of your sketch: @@ -872,7 +872,7 @@ nicla::begin(); Here is an example of how to use the Bluetooth® Low Energy library to advertise a byte characteristic that can be used for example to toggle an LED. -Include the library header it at the top of our sketch: +Include the library header it at the top of your sketch: ```arduino #include @@ -906,4 +906,4 @@ BLEDevice central = BLE.central(); ## Conclusion -This cheat sheet is written as a quick reference mainly to look up the features of this product. For a more in-depth walk though experience please have a look at the other tutorials. +This cheat sheet is written as a quick reference mainly to look up the features of this product. For a more in-depth walk though experience, please have a look at the other tutorials.