Merge pull request #25 from leonardocavagnis/doc-readme-api

Adding Documentation

Author: leonardocavagnis

README.md

@@ -0,0 +1,13 @@
+# 🧩 Arduino Modulino® Library
+
+The Arduino Modulino® Library simplifies the integration and management of Modulino® modules on Arduino boards. 
+
+A Modulino® is a compact, modular electronic device that connects easily to Arduino via the Qwiic connector and communicates using the I2C (`Wire`) protocol. These modules include sensors, actuators, and more.
+
+📖 For more information about this library please read the documentation [here](./docs/).
+
+## Hardware Compatibility
+This library is compatible with all Arduino boards that feature an I2C interface (`Wire`).
+
+## Support and Contributions
+If you find this library helpful, consider supporting us through [donations](https://www.arduino.cc/en/donate/), [sponsorship](https://github.com/sponsors/arduino) or check out our [store](https://store.arduino.cc/).

docs/api.md

@@ -0,0 +1,177 @@
+# Arduino Modulino Library API
+
+## Summary
+
+ Members                                    | Descriptions
+--------------------------------------------|------------------------------------------
+| `class` [`ModulinoClass`](#modulinoclass) | The base class for all Modulino components, providing essential functionality and structure for all subsequent Modulino modules.                                  |
+| `class` [`ModulinoButtons`](#modulinobuttons) | Handles the functionality of Modulino Buttons, enabling detection of presses and handling input events.                                                |
+| `class` [`ModulinoBuzzer`](#modulinobuttons) |Handles the functionality of Modulino Buzzer, enabling the sound generation for feedback or alerts.                                                    |
+| `class` [`ModulinoPixels`](#modulinopixels) | Handles the functionality of Modulino Pixels, managing LEDs strip color, status and brightness.                                          |
+| `class` [`ModulinoKnob`](#modulinoknob) | Handles the functionality of Modulino Knob, interfacing with the rotary knob position.                                                     |
+| `class` [`ModulinoMovement`](#modulinomovement) | Handles the functionality of Modulino Movement,interfacing with the IMU sensor to get acceleration readings. |
+| `class` [`ModulinoThermo`](#modulinothermo) | Handles the functionality of Modulino Thermo, managing temperature sensors to provide real-time temperature and humidity readings.                                |
+| `class` [`ModulinoDistance`](#modulinodistance) | Handles the functionality of Modulino Distance, enabling distance measurement using ToF (Time-of-Flight) sensors for precise range detection. |
+
+### ModulinoClass
+
+The `ModulinoClass` is the main class that handles the initialization of the I2C communication bus.
+
+#### Methods
+
+- **`void begin(HardwareI2C& wire = Wire)`**  
+  Initializes the I2C communication. The default I2C bus is `Wire`, but you can specify another one (e.g., `Wire1`).
+
+---
+
+### ModulinoButtons
+
+Represents a Modulino Buttons module.
+
+#### Methods
+
+- **`PinStatus isPressed(int index)`**  
+  Returns the press status (HIGH/LOW) of the button at the specified index (_0-A, 1-B, 2-C_).
+
+- **`bool update()`**  
+  Updates the button status. Returns `true` if the status has changed, `false` otherwise.
+
+- **`void setLeds(bool a, bool b, bool c)`**  
+  Sets the LED states. Each argument corresponds to one LED's state (on/off).
+
+---
+
+### ModulinoBuzzer
+
+Represents a Modulino Buzzer module.
+
+#### Methods
+
+- **`void tone(size_t freq, size_t len_ms)`**  
+  Plays a tone at the specified frequency (`freq`) and duration (`len_ms`).
+
+- **`void noTone()`**  
+  Stops any tone currently playing.
+
+---
+
+### ModulinoPixels
+
+Represents a Modulino Pixels module.
+
+#### Methods
+
+- **`void set(int idx, ModulinoColor rgb, uint8_t brightness = 25)`**  
+  Sets the color of the LED at the specified index.
+
+- **`void set(int idx, uint8_t r, uint8_t g, uint8_t b, uint8_t brightness = 5)`**  
+  Sets the color of the LED at the specified index using RGB values.
+
+- **`void clear(int idx)`**  
+  Clears the LED at the specified index (turns it off).
+
+- **`void clear()`**  
+  Clears all LEDs (turns them all off).
+
+- **`void show()`**  
+  Updates the LEDs to display the current color data.
+
+---
+
+### ModulinoKnob
+
+Represents a Modulino Knob module.
+
+#### Methods
+
+- **`int16_t get()`**  
+  Gets the current value of the knob.
+
+- **`bool isPressed()`**  
+  Returns `true` if the button on the knob is pressed, `false` otherwise.
+
+- **`void set(int16_t value)`**  
+  Sets the knob value.
+
+---
+
+### ModulinoMovement
+
+Represents a Modulino Movement module.
+
+#### Methods
+
+- **`int update()`**  
+  Updates the sensor data and reads the acceleration values.
+
+- **`int available()`**  
+  Returns `true` if acceleration data is available.
+
+- **`float getX()`**  
+  Returns the X-axis acceleration.
+
+- **`float getY()`**  
+  Returns the Y-axis acceleration.
+
+- **`float getZ()`**  
+  Returns the Z-axis acceleration.
+
+---
+
+### ModulinoThermo
+
+Represents a Modulino Thermo module.
+
+#### Methods
+
+- **`float getHumidity()`**  
+  Returns the humidity reading.
+
+- **`float getTemperature()`**  
+  Returns the temperature reading.
+
+---
+
+### ModulinoDistance
+
+Represents a Modulino Distance module.
+
+#### Methods
+
+- **`available()`**  
+  Checks if new distance data is available from the sensor. If data is ready, it reads the data and updates the distance value.  
+  `true` if distance data is available, `false` if distance data is not available.
+
+- **`float get()`**  
+  Returns the distance measured by the sensor in millimeters.  
+  The measured distance in millimeters if available, `NAN` if the distance reading is invalid.
+
+## Constants
+
+- **`ModulinoColor RED`**  
+  Represents the color red for Modulino Pixels modules.
+
+- **`ModulinoColor BLUE`**  
+  Represents the color blue for Modulino Pixels modules.
+
+- **`ModulinoColor GREEN`**  
+  Represents the color green for Modulino Pixels modules.
+
+- **`ModulinoColor VIOLET`**  
+  Represents the color violet for Modulino Pixels modules.
+
+- **`ModulinoColor WHITE`**  
+  Represents the color white for Modulino Pixels modules.
+
+### ModulinoColor
+
+Represents a color for Modulino Pixels modules.
+
+#### Constructor
+
+- **`ModulinoColor(uint8_t r, uint8_t g, uint8_t b)`**  
+  Creates a color with the specified red (`r`), green (`g`), and blue (`b`) components.
+
+## License
+
+This library is released under the [MPL-2.0 license](../LICENSE).

docs/images/modulino-buttons.jpeg

@@ -0,0 +1,181 @@
+# Arduino Modulino® Library
+
+The **Modulino** library is designed to simplify integration with various Modulino. It supports a variety of modules, such as motion sensors, buttons, buzzers, LED displays, and more, all through an I2C (`Wire`) interface.
+
+## Hardware Compatibility
+
+The library is compatible with Arduino boards that support I2C (`Wire`) communication.
+
+Each Modulino has a fixed I2C address assigned by default. If you wish to change the I2C address, you can refer to the [Utilities](#utilities) section.
+
+## Main Features
+
+The **Modulino** library supports the following hardware modules:
+
+- **Buttons (`ModulinoButtons`)**: Read the state of buttons and control the associated LEDs.
+- **Buzzer (`ModulinoBuzzer`)**: Activate and deactivate the buzzer and set its frequency.
+- **LEDs (`ModulinoPixels`)**: Control RGB LEDs with customizable display modes.
+- **Knob (`ModulinoKnob`)**: Read the value of a rotary encoder.
+- **Motion (`ModulinoMovement`)**: Interface with the LSM6DSOX IMU sensor to get acceleration values.
+- **Temperature & Humidity (`ModulinoThermo`)**: Get temperature and humidity readings from the HS300x sensor.
+- **Distance (`ModulinoDistance`)**: Measures distance using a Time-of-Flight (ToF) sensor (VL53L0x).
+
+## Library Initialization
+
+To initialize the **Modulino** library, include the header file and call the `begin()` method. This will set up the I2C communication and prepare the library for use with the modules.
+
+```cpp
+#include <Modulino.h>
+Modulino.begin();  // Initialize the Modulino library
+```
+
+## Supported Modules
+
+You can initialize a Modulino board easily. The basic setup requires just a call to the `begin()` method for each module. For example:
+
+```cpp
+ModulinoType modulino_name;
+modulino_name.begin();  // Initialize the ModulinoType module
+```
+
+### ModulinoButtons
+Manages the state of three buttons and controls their associated LED states. You can read the state of each button and send commands to turn the LEDs on/off.
+
+![Modulino Buttons](./images/modulino-buttons.jpg)
+
+```cpp
+ModulinoButtons buttons;
+buttons.begin();
+buttons.setLeds(true, false, true);  // Turn on LED 1 and LED 3
+```
+
+### ModulinoBuzzer
+Allows you to emit sounds through the buzzer. You can set the frequency and duration of the sound.
+
+![Modulino Buzzer](./images/modulino-buzzer.jpg)
+
+```cpp
+ModulinoBuzzer buzzer;
+buzzer.begin();
+buzzer.tone(440, 1000);  // 440Hz frequency for 1000ms
+```
+
+### ModulinoPixels
+Controls an array of 8 RGB LEDs, allowing you to set the colors and brightness. You can also clear individual LEDs or the entire array.
+
+![Modulino Pixels](./images/modulino-pixels.jpg)
+
+```cpp
+ModulinoPixels leds;
+leds.set(0, ModulinoColor(255, 0, 0));  // Set the first LED (Position: 0) to red
+leds.show();  // Display the LEDs
+```
+
+### ModulinoKnob
+Manages a rotary encoder, allowing you to read the potentiometer value and check if the knob is pressed.
+
+![Modulino Knob](./images/modulino-knob.jpg)
+
+```cpp
+ModulinoKnob knob;
+knob.begin();
+int16_t value = knob.get();  // Get the value of the encoder
+```
+
+###  ModulinoMovement
+Interfaces with the LSM6DSOX IMU sensor to get acceleration readings.
+
+![Modulino Movement](./images/modulino-movement.jpg)
+
+```cpp
+ModulinoMovement movement;
+movement.begin();
+float x = movement.getX();
+```
+
+### ModulinoThermo
+Reads temperature and humidity data from the HS300x sensor.
+
+![Modulino Thermo](./images/modulino-thermo.jpg)
+
+```cpp
+ModulinoThermo thermo;
+thermo.begin();
+float temperature = thermo.getTemperature();
+float humidity = thermo.getHumidity();
+```
+
+### ModulinoDistance
+Measures distance using a ToF (Time-of-Flight) sensor.
+
+![Modulino Distance](./images/modulino-distance.jpg)
+
+```cpp
+ModulinoDistance distance;
+distance.begin();
+float distanceValue = distance.get();
+```
+
+## Example Usage
+
+Here’s an example of how to use some Modulino in a program:
+
+```cpp
+// This sketch demonstrates how to use the Modulino library to control buttons, LEDs, and a buzzer.
+// It listens for a button press (Button A), turns on the LED 0, and plays a sound through the buzzer when pressed.
+
+#include <Modulino.h>
+
+ModulinoButtons buttons;  // Declare a Buttons Modulino
+ModulinoPixels leds;      // Declare a Pixels Modulino
+ModulinoBuzzer buzzer;    // Declare a Buzzer Modulino
+
+int frequency = 440;      // Set frequency to 440Hz
+int duration = 1000;      // Set duration to 1000ms
+
+void setup() {
+  Serial.begin(9600);
+
+  Modulino.begin();        // Initialize the Modulino library
+
+  buttons.begin();         // Initialize the Buttons module
+  leds.begin();            // Initialize the Pixels module
+  buzzer.begin();          // Initialize the Buzzer module
+}
+
+void loop() {
+  if (buttons.update()) {  // Update the button states
+    if (buttons.isPressed(0)) {  // Check if Button A (button 0) is pressed
+      Serial.println("Button A pressed!");
+      leds.set(0, RED);  // Turn on LED 0 to red
+      leds.show();
+
+      buzzer.tone(frequency, duration);  // Play buzzer sound with the specified frequency and duration
+      delay(duration);
+    } else {
+      leds.clear(0); // Turn off LED 0
+      leds.show();
+    }
+  }
+}
+```
+
+## Examples
+
+The examples folder is organized by Modulino type. Each module has its own folder with example sketches that demonstrate both basic and advanced usage (where applicable).
+
+You can explore the examples [here](../examples).
+
+### Utilities
+
+In the [Utilities](../examples/Utilities) folder, you will find programs designed to help you manage and manipulate the Modulino:
+
+- [AddressChanger](../examples/Utilities/AddressChanger/): This program allows you to change the I2C address of a Modulino module. It’s helpful when you need to reassign addresses to avoid conflicts or organize your I2C network.
+
+## API
+
+The API documentation can be found [here](./api.md).
+
+## License
+
+This library is released under the [MPL-2.0 license](../LICENSE).

docs/images/modulino-buzzer.jpg

@@ -1,3 +1,11 @@
+/*
+ * Modulino Buttons - Basic
+ *
+ * This example code is in the public domain. 
+ * Copyright (c) 2025 Arduino
+ * SPDX-License-Identifier: MPL-2.0
+ */
+
 #include <Modulino.h>
 
 ModulinoButtons buttons;