Skip to content

Nicla Sense ME: Fix Cheat-sheet typos #475

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 1 commit into from
Aug 18, 2022
Merged
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down Expand Up @@ -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;
Expand All @@ -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() {
Expand All @@ -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() {
Expand All @@ -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:
Expand All @@ -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 |
Expand Down Expand Up @@ -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:

Expand Down Expand Up @@ -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.

Expand Down Expand Up @@ -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.

Expand Down Expand Up @@ -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.

Expand Down Expand Up @@ -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.

Expand Down Expand Up @@ -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.

Expand Down Expand Up @@ -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.

Expand Down Expand Up @@ -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:
Expand Down Expand Up @@ -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)

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

Expand All @@ -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 <SPI.h>
```

Inside `void setup()` we need to initialize the library.
Inside `void setup()` you need to initialize the library.

```arduino
SPI.begin();
Expand All @@ -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 <Wire.h>
```

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
Expand All @@ -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()){
Expand All @@ -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!");
Expand Down Expand Up @@ -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:

Expand All @@ -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 <ArduinoBLE.h>
Expand Down Expand Up @@ -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.