Skip to content

Commit 1c84702

Browse files
quentin-cyquentin-cy
committed
Restructured documentation of ML-based scent detection example
1 parent b33a556 commit 1c84702

3 files changed

Lines changed: 159 additions & 88 deletions

File tree

‎README.md‎

Lines changed: 3 additions & 25 deletions
Original file line numberDiff line numberDiff line change
@@ -185,32 +185,10 @@ exampleSGP43Classifier, and upload. Open Tools ➔ Serial Monitor at 115200 baud
185185
</p>
186186
</details>
187187

188-
## Quick Start
188+
## ML-based smell detection
189189

190-
For details on using the **SEK-SGP4x** evaluation board for machine learning-based smell detection, please see
191-
application note **GAS_AN_SGP43**.
192-
193-
1. Install the libraries and dependencies according to [Installation of the library](#installation-of-the-library)
194-
195-
2. Connect the SGP43 sensor to your Arduino as explained in [Connect the sensor](#connect-the-sensor)
196-
197-
3. Open the `exampleSGP43Classifier` sample project within the Arduino IDE:
198-
199-
`File` ➔ `Examples` ➔ `Sensirion I2C SGP43` ➔ `exampleSGP43Classifier`
200-
201-
4. Click the `Upload` button in the Arduino IDE or `Sketch` ➔ `Upload`
202-
203-
5. When the upload process has finished, open the `Serial Monitor` or `Serial
204-
Plotter` via the `Tools` menu to observe the measurement values. Note that
205-
the `Baud Rate` in the used tool has to be set to `115200 baud`.
206-
207-
You can now use the python_sgp43_classifier package to log and classify the measured
208-
values.
209-
Please make sure you close the Serial Monitor before running the classifier, otherwise it will block the
210-
serial communication.
211-
212-
You can find the usage information for the Python SGP43
213-
classifier [here](examples/exampleSGP43Classifier/python_sgp43_classifier/README.md)
190+
For details on using the **SEK-SGP4x** evaluation board for machine learning-based smell detection, please read
191+
application note **GAS_AN_SGP43** in combination with the documentation of the deidcated example [here](./examples/exampleSGP43Classifier/README.md).
214192

215193
## Contributing
216194

‎examples/exampleSGP43Classifier/README.md‎

Lines changed: 112 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -1,18 +1,120 @@
1-
# SGP43 Classifier Example
1+
# ML-Based Classifier Example
22

3-
This example converts a log output from the Arduino measurement into an EDF file which can be read by Sensirion's
4-
DataViewer. DataViewer is integrated
5-
into [ControlCenter](https://sensirion.com/products/sensor-evaluation/control-center).
3+
This guide is about the avanced usage example of the **SEK-SGP4x** where it can be used for machine learning-based smell detection.
4+
Please refer to the associated application note **GAS_AN_SGP43**.
65

7-
## Usage
6+
## Get started
7+
This example is using 2 different scripts:
8+
- An arduino sketch to run on your microcontroller
9+
- A python script to run on your computer
810

9-
1. Compile the Arduino script and upload it to the microcontroller.
10-
2. Check on which port the Arduino is connected to.
11-
3. Follow the instructions in the following [README](./python_sgp43_classifier/README.md) on how to collect
12-
measurements and run the classification script.
11+
The Arduino sketch executes the temperature ramps and return the resulting measurement using serial to the computer.
12+
From there, the python script can simply log the measurements to a file or run the example model prediction.
1313

14-
## Add New Temperature Profile
14+
15+
### Wiring
16+
Connect the SGP43 sensor to your Arduino board using the guide in the [library instructions](../../README.md#connect-the-sensor)
17+
18+
### Arduino script
19+
0. Install the Arduino IDE using the instructions from the [official website](https://www.arduino.cc/en/software/)
20+
21+
1. Install the library and its dependencies. First, open the library manager located on left toolbar. Search for the `Sensirion I2C SGP43` library in the `Filter your search...` field and install it by clicking the `install` button.
22+
When asked about dependencies installation, click `Install all`.
23+
In case the library is not available through the library manager see the [manual installation](#manual-installation-of-the-library) section below
24+
25+
2. Open the `exampleSGP43Classifier` sample project within the Arduino IDE:
26+
27+
`File` ➔ `Examples` ➔ `Sensirion I2C SGP43` ➔ `exampleSGP43Classifier`
28+
29+
3. In the top bar of the Arduino IDE, select the board matching the model you are using and the correct port.
30+
31+
4. Click the `Upload` button in the Arduino IDE or `Sketch` ➔ `Upload`
32+
33+
5. When the upload process has finished, open the `Serial Monitor` via the `Tools` menu to observe the measurement values. Note that the baud rate in the used tool has to be set to `115200 baud`.
34+
35+
If you see measurement values printed to the serial monitor, then this section is complete.
36+
You are ready to collect the incoming data with the provided python script (see next section).
37+
38+
### Python script
39+
You can now use the python script (located in the `python_sgp43_classifier` folder) to log and classify the measured values.
40+
41+
This script converts the serial output from the Arduino measurement into an EDF file which can be read by Sensirion's DataViewer. DataViewer is included when installing [ControlCenter](https://sensirion.com/products/sensor-evaluation/control-center).
42+
43+
In this step by step guide, we will use the provided model that can detect the present of banana or coffee beans scent.
44+
45+
> [!IMPORTANT]
46+
> Please make sure you close the Serial Monitor before running the classifier, otherwise it will block the serial communication.
47+
48+
49+
50+
#### Requirements
51+
> [!TIP]
52+
> To run the python scripts, you need Python 3.11 or higher.
53+
54+
55+
To install the dependencies you can either use `uv` (recommended) or `pip`.
56+
57+
Using `uv` you can simply run while being located in the `python_sgp43_classifier` folder:
58+
```
59+
uv sync
60+
```
61+
62+
Using `pip` you can run while being located in the `python_sgp43_classifier` folder:
63+
```
64+
pip install -r requirements.txt
65+
```
66+
67+
68+
#### Log measurements to a .edf file
69+
To log the measurements to a file (e.g. for later processing) use the command `measure`.
70+
71+
```
72+
python main.py measure --port <port>
73+
```
74+
where `<port>` should be replaced by the port where the board is connected.
75+
76+
77+
A new EDF file will be created as soon as a new loop is detected.
78+
Each time a new loop is started, the previous one is
79+
written directly to the file.
80+
81+
> [!TIP]
82+
> Make sure the board is plugged in before running the script.
83+
84+
### Live predictions using example model
85+
To get live predictions from the provided model we can use the command `measure-and-predict`.
86+
87+
```
88+
python main.py measure-and-predict --port <port>
89+
```
90+
where `<port>` should be replaced by the port where the board is connected.
91+
92+
The predicted category is printed to the console together with the output values of all three predictors.
93+
If the script cannot confidently determine a category, it outputs ???. This typically occurs immediately after powering
94+
up the sensor (during the initial blackout period) or when no category can be selected with a sufficient margin.
95+
The latter case also occurs during transitions between categories (for example, when moving the sensor from ambient air
96+
into a jar filled with coffee beans).
97+
98+
A predictor value close to +1 indicates a strong match with the trained category, whereas a value close to -1 indicates
99+
no match. Therefore, if one of the three predictors shows a clearly positive value while the other two show negative
100+
values, it can be reliably assumed that the category associated with the positive predictor has been detected.
101+
102+
> [!TIP]
103+
> Make sure the board is plugged in before running the script.
104+
105+
106+
## Advanced topics
107+
108+
### Add New Temperature Profile
15109

16110
1. Copy the `default_tprofile.h` and rename it.
17111
2. Edit the array.
18112
3. In exampleSGP43Classifer.ino, change `#include "default_tprofile.h"` to include your newly created profile.
113+
114+
### Manual installation of the library
115+
To manually install the library (without using the library manager) you can start by downloading the [latest release from github](https://github.com/Sensirion/arduino-i2c-sgp43/releases) as a `.zip` archive.
116+
117+
Once the downloaded, it can be added in Arduino IDE using:
118+
`Sketch` ➔ `Include Library` ➔ `Include .ZIP library...`
119+
120+
[!TIP] The manual installation will not prompt for dependency libraries. It is up to you to make sure all [dependencies](../../README.md#dependencies) are installed

‎examples/exampleSGP43Classifier/python_sgp43_classifier/README.md‎

Lines changed: 44 additions & 53 deletions
Original file line numberDiff line numberDiff line change
@@ -1,27 +1,56 @@
11
# SGP43 Classifier
22

3-
This script converts the log output from the Arduino into an EDF file and predicts if air, banana or
4-
coffee beans were measured.
3+
This script allows you to convert the serial output from the Arduino into an EDF file which can be read using Sensirion's free DataViewer software.
4+
DataViewer is included when installing [ControlCenter](https://sensirion.com/products/sensor-evaluation/control-center).
55

6-
## Requirements
7-
To run the python scripts, you need Python 3.11 or higher.
6+
This script also allows you to apply the provided model to the live output. The provided model can detect the present of banana or coffee beans scent.
87

9-
## Install dependencies
8+
## Get started
9+
To get started please refer to the [README.md in the parent folder](../README.md). You will find a complete guide that takes you through the complete process from the wiring to the prediction model
1010

11-
### Using uv
12-
`uv sync`
11+
## Advanced usage
12+
### `measure`
13+
This command can be used to log measured data to a file for later processing.
1314

14-
### Using pip
15-
Install the dependencies with this command:
16-
`pip install -r requirements.txt`
1715

16+
> [!IMPORTANT]
17+
> Plug in the microcontroller before running the measurement script.
18+
You need to provide the port where the microcontroller is attached.
19+
20+
21+
Start the script with this command:
22+
23+
`python main.py measure --port <port>`
24+
25+
Arguments:
26+
27+
- `--port`: Port where the microcontroller is attached. [**required**, e.g. USB1 or COM1]
28+
- `--log-path`: Path to the folder where the output file will be generated. [**optional**, default: current folder]
29+
- `--baud`: VCP transmission speed (baud-rate). [**optional**, default: 115200]
30+
31+
A new EDF file will be created when it first detects a new loop. Each time a new loop is started, the previous loop is
32+
written directly to the EDF file.
1833

19-
## Measurement and Prediction script
34+
### `predict`
2035

21-
The measurement and prediction script can be used to measure a substance and output the predicted category live.
36+
The predict command can be used to predict the measured substance based on the EDF file created by the measurement script.
2237

23-
Measurement and prediction can also be performed separately by using the respective script described in the sections
24-
below.
38+
The script needs a classifier model which is located in the `sgp43_classifier` folder (e.g. the example model `air_banana_coffee.clf`).
39+
40+
Start the script with this command:
41+
42+
`python main.py predict --p <path>`
43+
44+
Arguments:
45+
- `-p, --measurement-path PATH`: Path to the measurement EDF file. [**required**]
46+
- `-o, --output-path PATH`: Path to write the predicted output EDF file. [**optional**, default: current path]
47+
- `-c, --classifier-path PATH`: Path to the pickled classifier. [**optional**, default: air_banana_coffee.clf]
48+
49+
A new EDF file with the predicted category will be created.
50+
51+
52+
### `measure-and-predict`
53+
The measurement and prediction command can be used to measure a substance and output the predicted category live.
2554

2655
Plug in the microcontroller before running the script.
2756
You need to provide the port where the microcontroller is attached.
@@ -48,42 +77,4 @@ into a jar filled with coffee beans).
4877

4978
A predictor value close to +1 indicates a strong match with the trained category, whereas a value close to -1 indicates
5079
no match. Therefore, if one of the three predictors shows a clearly positive value while the other two show negative
51-
values, it can be reliably assumed that the category associated with the positive predictor has been detected.
52-
53-
## Measurement script
54-
55-
The measurement script can be used to log measured data to a file for later processing.
56-
57-
Plug in the microcontroller before running the measurement script.
58-
You need to provide the port where the microcontroller is attached.
59-
60-
Start the script with this command:
61-
62-
`python main.py measure --port <port>`
63-
64-
Arguments:
65-
66-
- `--port`: Port where the microcontroller is attached. [**required**, e.g. USB1 or COM1]
67-
- `--log-path`: Path to the folder where the output file will be generated. [**optional**, default: current folder]
68-
- `--baud`: VCP transmission speed (baud-rate). [**optional**, default: 115200]
69-
70-
A new EDF file will be created when it first detects a new loop. Each time a new loop is started, the previous loop is
71-
added directly to the EDF file.
72-
73-
## Prediction script
74-
75-
The prediction script can be used to predict the measured substance based on the EDF file created by the measurement
76-
script.
77-
78-
The script needs a classifier model which is located in the `sgp43_classifier` folder and names `air_banana_coffee.clf`.
79-
80-
Start the script with this command:
81-
82-
`python main.py predict --p <path>`
83-
84-
Arguments:
85-
- `-p, --measurement-path PATH`: Path to the measurement EDF file. [**required**]
86-
- `-o, --output-path PATH`: Path to write the predicted output EDF file. [**optional**, default: current path]
87-
- `-c, --classifier-path PATH`: Path to the pickled classifier. [**optional**, default: air_banana_coffee.clf]
88-
89-
A new EDF file with the predicted category will be created.
80+
values, it can be reliably assumed that the category associated with the positive predictor has been detected.

0 commit comments

Comments
 (0)