Merge pull request #3 from Sensirion/sfa3x_1.1.0_20250318_1001

Generate SFA3x driver from SFA3x model version 1.1.0

Author: sdmueller

.github/workflows/arduino_quality_check.yml

@@ -1,10 +1,8 @@
 name: Quality check
 
 on:
-  pull_request:
-    branches:
-      - master
   push:
+  pull_request:
     branches:
       - master
 
@@ -13,4 +11,5 @@ jobs:
     uses: sensirion/.github/.github/workflows/driver.arduino.check.yml@main
     with:
       expect-arduino-examples: true
+      # change to "update" once you published the driver on Arduino library registry
       lint-lib-manager-check: update

CHANGELOG.md

@@ -1,19 +1,27 @@
-# Changelog
-
-All notable changes to this project will be documented in this file.
+# CHANGELOG
 
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
-## [unreleased]
+## [Unreleased] 
+
+## [1.0.0] - 2025-3-18
+
+### Added
+
+- All commands according to data sheet. This introduces breaking changes!
 
-### Fixed
-- Link to SFA3x Eval Kit overview page
+### Breaking changes
 
+- Class `SensirionI2CSfa3x` has been renamed to `SensirionI2cSfa3x` (note the casing of `I2c`!)
+- `begin()` now requires you to also pass the I2C address
+- `readMeasuredValues()` now already applies appropriate scaling to the values
+    - Use `readMeasuredValuesAsIntegers()` if you want the values without scaling applied (same as in old version)
 
-## [0.1.0] - 2021-02-05
+## [0.1.0] - 2021-2-5
 
-Initial release
+- Initial Release
 
-[Unreleased]: https://github.com/sensirion/arduino-i2c-sfa3x/compare/0.1.0...HEAD
-[0.1.0]: https://github.com/Sensirion/arduino-i2c-sfa3x/releases/tag/0.1.0
+[Unreleased]: https://github.com/Sensirion/arduino-i2c-sfa3x/compare/1.0.0...HEAD
+[1.0.0]: https://github.com/Sensirion/arduino-i2c-sfa3x/compare/0.1.0...1.0.0
+[0.1.0]: https://github.com/Sensirion/arduino-i2c-sfa3x/releases/tag/0.1.0

LICENSE

@@ -1,6 +1,6 @@
 BSD 3-Clause License
 
-Copyright (c) 2021, Sensirion AG
+Copyright (c) 2025, Sensirion AG
 All rights reserved.
 
 Redistribution and use in source and binary forms, with or without

README.md

@@ -1,66 +1,185 @@
-# Sensirion I2C SFA3X Arduino Library
+# Sensirion I²C SFA3X Arduino Library
 
-This is the Sensirion SFA3X library for Arduino using the
-modules I2C interface.
+This is the Sensirion SFA3X library for Arduino allowing you to
+communicate with a SFA3X sensor over I²C.
 
-[<center><img src="images/SFA3x.png" width="500px"></center>](https://www.sensirion.com/my-sfa-ek)
+<img src="images/sfa3x.png" width="300px">
 
-Click [here](https://www.sensirion.com/my-sfa-ek) to learn more about the SFA30
-sensor and the SFA30 Evaluation Kit Board.
+Click [here](https://sensirion.com/products/catalog/SEK-SFA30) to learn more about the Sensirion SFA3X sensor.
 
 
-# Installation
 
-To install, download the latest release as .zip file and add it to your
-[Arduino IDE](http://www.arduino.cc/en/main/software) via
+The default I²C address of [SFA3X](https://sensirion.com/products/catalog/SFA30) is **0x5D**.
 
-	Sketch => Include Library => Add .ZIP Library...
 
-Don't forget to **install the dependencies** listed below the same way via `Add
-.ZIP Library`
 
-Note: Installation via the Arduino Library Manager is coming soon.
+## Installation of the library
 
-# Dependencies
+This library can be installed using the Arduino Library manager:
+Start the [Arduino IDE](http://www.arduino.cc/en/main/software) and open
+the Library Manager via
 
+`Sketch` ➔ `Include Library` ➔ `Manage Libraries...`
+
+Search for the `Sensirion I2C SFA3X` library in the `Filter
+your search...` field and install it by clicking the `install` button.
+
+If you cannot find it in the library manager, download the latest release as .zip file
+and add it to your [Arduino IDE](http://www.arduino.cc/en/main/software) via
+
+`Sketch` ➔ `Include Library` ➔ `Add .ZIP Library...`
+
+Don't forget to **install the dependencies** listed below the same way via library
+manager or `Add .ZIP Library`
+
+#### Dependencies
 * [Sensirion Core](https://github.com/Sensirion/arduino-core)
 
+## Connect the sensor
+
+Use the following pin description to connect your SFA3X to the standard I²C bus of your Arduino board:
+
+<img src="images/sfa3x-pinout.png" width="300px">
+
+| *Pin* | *Cable Color* | *Name* | *Description*  | *Comments* |
+|-------|---------------|:------:|----------------|------------|
+| 1 | red | VDD | Supply Voltage | 3.15V to 5.5V
+| 2 | black | GND | Ground |
+| 3 | green | SDA | I2C: Serial data input / output |
+| 4 | yellow | SCL | I2C: Serial clock input |
+| 5 | blue | SEL | Interface select | Pull to GND to select I2C (leaving it floating selects UART)
+
+
+
+
+The recommended voltage is 3.3V.
+
+### Board specific wiring
+You will find pinout schematics for recommended board models below:
+
+
+
+<details><summary>Arduino Uno</summary>
+<p>
+
+| *SFA3X* | *SFA3X Pin* | *Cable Color* | *Board Pin* |
+| :---: | --- | --- | --- |
+| VDD | 1 | red | 3.3V |
+| GND | 2 | black | GND |
+| SDA | 3 | green | D18/SDA |
+| SCL | 4 | yellow | D19/SCL |
+| SEL | 5 | blue | GND |
+
+
+
+<img src="images/Arduino-Uno-Rev3-i2c-pinout-3.3V-SEL.png" width="600px">
+</p>
+</details>
+
+
+
+
+<details><summary>Arduino Nano</summary>
+<p>
+
+| *SFA3X* | *SFA3X Pin* | *Cable Color* | *Board Pin* |
+| :---: | --- | --- | --- |
+| VDD | 1 | red | 3.3V |
+| GND | 2 | black | GND |
+| SDA | 3 | green | A4 |
+| SCL | 4 | yellow | A5 |
+| SEL | 5 | blue | GND |
+
+
+
+<img src="images/Arduino-Nano-i2c-pinout-3.3V-SEL.png" width="600px">
+</p>
+</details>
 
-# Quick Start
 
-1. Connect the SFA3X Sensor to your Arduino board's standard
-   I2C bus. Check the pinout of your Arduino board to find the correct pins.
-   The pinout of the SFA3X Sensor board can be found in the
-   data sheet.
 
-	* **VDD** of the SEK-SFA3X to the **3.3V** of your Arduino board (5V is also possible)
-	* **GND** of the SEK-SFA3X to the **GND** of your Arduino board
-	* **SCL** of the SEK-SFA3X to the **SCL** of your Arduino board
-	* **SDA** of the SEK-SFA3X to the **SDA** of your Arduino board
-	* **SEL** of the SEK-SFA3X to another **GND** of your Arduino board
 
-2. Open the `exampleUsage` sample project within the Arduino IDE
+<details><summary>Arduino Micro</summary>
+<p>
 
-		File => Examples => Sensirion I2C Sfa3x => exampleUsage
+| *SFA3X* | *SFA3X Pin* | *Cable Color* | *Board Pin* |
+| :---: | --- | --- | --- |
+| VDD | 1 | red | 3.3V |
+| GND | 2 | black | GND |
+| SDA | 3 | green | D2/SDA |
+| SCL | 4 | yellow | ~D3/SCL |
+| SEL | 5 | blue | GND |
 
-3. Click the `Upload` button in the Arduino IDE or
 
-		Sketch => Upload
+
+<img src="images/Arduino-Micro-i2c-pinout-3.3V-SEL.png" width="600px">
+</p>
+</details>
+
+
+
+
+<details><summary>Arduino Mega 2560</summary>
+<p>
+
+| *SFA3X* | *SFA3X Pin* | *Cable Color* | *Board Pin* |
+| :---: | --- | --- | --- |
+| VDD | 1 | red | 3.3V |
+| GND | 2 | black | GND |
+| SDA | 3 | green | D20/SDA |
+| SCL | 4 | yellow | D21/SCL |
+| SEL | 5 | blue | GND |
+
+
+
+<img src="images/Arduino-Mega-2560-Rev3-i2c-pinout-3.3V-SEL.png" width="600px">
+</p>
+</details>
+
+
+
+
+<details><summary>ESP32 DevKitC</summary>
+<p>
+
+| *SFA3X* | *SFA3X Pin* | *Cable Color* | *Board Pin* |
+| :---: | --- | --- | --- |
+| VDD | 1 | red | 3V3 |
+| GND | 2 | black | GND |
+| SDA | 3 | green | GPIO 21 |
+| SCL | 4 | yellow | GPIO 22 |
+| SEL | 5 | blue | GND |
+
+
+
+<img src="images/esp32-devkitc-i2c-pinout-3.3V-SEL.png" width="600px">
+</p>
+</details>
+
+
+
+## Quick Start
+
+1. Install the libraries and dependencies according to [Installation of the library](#installation-of-the-library)
+
+2. Connect the SFA3X sensor to your Arduino as explained in [Connect the sensor](#connect-the-sensor)
+
+3. Open the `exampleUsage` sample project within the Arduino IDE:
+
+   `File` ➔ `Examples` ➔ `Sensirion I2C SFA3X` ➔ `exampleUsage`
+
+
+
+5. Click the `Upload` button in the Arduino IDE or `Sketch` ➔ `Upload`
 
 4. When the upload process has finished, open the `Serial Monitor` or `Serial
    Plotter` via the `Tools` menu to observe the measurement values. Note that
-   the `Baud Rate` in the corresponding window has to be set to `115200 baud`.
+   the `Baud Rate` in the used tool has to be set to `115200 baud`.
 
-# Contributing
+## Contributing
 
 **Contributions are welcome!**
 
-We develop and test this driver using our company internal tools (version
-control, continuous integration, code review etc.) and automatically
-synchronize the master branch with GitHub. But this doesn't mean that we don't
-respond to issues or don't accept pull requests on GitHub. In fact, you're very
-welcome to open issues or create pull requests :)
-
 This Sensirion library uses
 [`clang-format`](https://releases.llvm.org/download.html) to standardize the
 formatting of all our `.cpp` and `.h` files. Make sure your contributions are
@@ -74,7 +193,8 @@ clang-format -i src/*.cpp src/*.h
 
 Note that differences from this formatting will result in a failed build until
 they are fixed.
+:
 
-# License
+## License
 
-See [LICENSE](LICENSE).
+See [LICENSE](LICENSE).