diff --git a/README.md b/README.md new file mode 100644 index 0000000..45f68f1 --- /dev/null +++ b/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/). \ No newline at end of file diff --git a/docs/api.md b/docs/api.md new file mode 100644 index 0000000..5ced974 --- /dev/null +++ b/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). \ No newline at end of file diff --git a/docs/images/modulino-buttons.jpeg b/docs/images/modulino-buttons.jpeg new file mode 100644 index 0000000..229e68c Binary files /dev/null and b/docs/images/modulino-buttons.jpeg differ diff --git a/docs/images/modulino-buzzer.jpg b/docs/images/modulino-buzzer.jpg new file mode 100644 index 0000000..fb9a730 Binary files /dev/null and b/docs/images/modulino-buzzer.jpg differ diff --git a/docs/images/modulino-distance.jpg b/docs/images/modulino-distance.jpg new file mode 100644 index 0000000..806734a Binary files /dev/null and b/docs/images/modulino-distance.jpg differ diff --git a/docs/images/modulino-knob.jpg b/docs/images/modulino-knob.jpg new file mode 100644 index 0000000..6c68a16 Binary files /dev/null and b/docs/images/modulino-knob.jpg differ diff --git a/docs/images/modulino-movement.jpg b/docs/images/modulino-movement.jpg new file mode 100644 index 0000000..97d0d2d Binary files /dev/null and b/docs/images/modulino-movement.jpg differ diff --git a/docs/images/modulino-pixels.jpg b/docs/images/modulino-pixels.jpg new file mode 100644 index 0000000..8140a10 Binary files /dev/null and b/docs/images/modulino-pixels.jpg differ diff --git a/docs/images/modulino-thermo.jpg b/docs/images/modulino-thermo.jpg new file mode 100644 index 0000000..b5158d6 Binary files /dev/null and b/docs/images/modulino-thermo.jpg differ diff --git a/docs/readme.md b/docs/readme.md new file mode 100644 index 0000000..9c59418 --- /dev/null +++ b/docs/readme.md @@ -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.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 + +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). \ No newline at end of file diff --git a/examples/Modulino_Buttons/Basic/Basic.ino b/examples/Modulino_Buttons/Basic/Basic.ino index c40209b..5145f02 100644 --- a/examples/Modulino_Buttons/Basic/Basic.ino +++ b/examples/Modulino_Buttons/Basic/Basic.ino @@ -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 ModulinoButtons buttons; diff --git a/examples/Modulino_Buttons/Button2Integration/Button2Integration.ino b/examples/Modulino_Buttons/Button2Integration/Button2Integration.ino index 883bb6c..9f092c0 100644 --- a/examples/Modulino_Buttons/Button2Integration/Button2Integration.ino +++ b/examples/Modulino_Buttons/Button2Integration/Button2Integration.ino @@ -1,4 +1,11 @@ -// Integration with https://github.com/LennartHennigs/Button2 +/* + * Modulino Buttons - Button2 Integration + * Integration with https://github.com/LennartHennigs/Button2 + * + * This example code is in the public domain. + * Copyright (c) 2025 Arduino + * SPDX-License-Identifier: MPL-2.0 + */ #include "Modulino.h" #include "Button2.h" diff --git a/examples/Modulino_Buzzer/Basic/Basic.ino b/examples/Modulino_Buzzer/Basic/Basic.ino index b66e419..a254115 100644 --- a/examples/Modulino_Buzzer/Basic/Basic.ino +++ b/examples/Modulino_Buzzer/Basic/Basic.ino @@ -1,3 +1,11 @@ +/* + * Modulino Buzzer - Basic + * + * This example code is in the public domain. + * Copyright (c) 2025 Arduino + * SPDX-License-Identifier: MPL-2.0 + */ + #include ModulinoBuzzer buzzer; diff --git a/examples/Modulino_Buzzer/Simple_melody/Simple_melody.ino b/examples/Modulino_Buzzer/Simple_melody/Simple_melody.ino index 25c01cf..fbff626 100644 --- a/examples/Modulino_Buzzer/Simple_melody/Simple_melody.ino +++ b/examples/Modulino_Buzzer/Simple_melody/Simple_melody.ino @@ -1,3 +1,11 @@ +/* + * Modulino Buzzer - Simple melody + * + * This example code is in the public domain. + * Copyright (c) 2025 Arduino + * SPDX-License-Identifier: MPL-2.0 + */ + #include ModulinoBuzzer buzzer; diff --git a/examples/Modulino_Distance/Basic/Basic.ino b/examples/Modulino_Distance/Basic/Basic.ino index eed3bbf..a9622bd 100644 --- a/examples/Modulino_Distance/Basic/Basic.ino +++ b/examples/Modulino_Distance/Basic/Basic.ino @@ -1,3 +1,11 @@ +/* + * Modulino Distance - Basic + * + * This example code is in the public domain. + * Copyright (c) 2025 Arduino + * SPDX-License-Identifier: MPL-2.0 + */ + #include "Modulino.h" ModulinoDistance distance; diff --git a/examples/Modulino_Knob/Basic/Basic.ino b/examples/Modulino_Knob/Basic/Basic.ino index 879c940..1272a60 100644 --- a/examples/Modulino_Knob/Basic/Basic.ino +++ b/examples/Modulino_Knob/Basic/Basic.ino @@ -1,3 +1,11 @@ +/* + * Modulino Knob - Basic + * + * This example code is in the public domain. + * Copyright (c) 2025 Arduino + * SPDX-License-Identifier: MPL-2.0 + */ + #include ModulinoKnob knob; diff --git a/examples/Modulino_Knob/EncoderSetter/EncoderSetter.ino b/examples/Modulino_Knob/EncoderSetter/EncoderSetter.ino index f130a63..8d6299b 100644 --- a/examples/Modulino_Knob/EncoderSetter/EncoderSetter.ino +++ b/examples/Modulino_Knob/EncoderSetter/EncoderSetter.ino @@ -1,3 +1,11 @@ +/* + * Modulino Knob - Encoder Setter + * + * This example code is in the public domain. + * Copyright (c) 2025 Arduino + * SPDX-License-Identifier: MPL-2.0 + */ + #include "Modulino.h" ModulinoKnob encoder; diff --git a/examples/Modulino_Movement/Basic/Basic.ino b/examples/Modulino_Movement/Basic/Basic.ino index 956ae54..4b0c06e 100644 --- a/examples/Modulino_Movement/Basic/Basic.ino +++ b/examples/Modulino_Movement/Basic/Basic.ino @@ -1,3 +1,11 @@ +/* + * Modulino Movement - Basic + * + * This example code is in the public domain. + * Copyright (c) 2025 Arduino + * SPDX-License-Identifier: MPL-2.0 + */ + #include "Modulino.h" ModulinoMovement movement; diff --git a/examples/Modulino_Pixels/Basic/Basic.ino b/examples/Modulino_Pixels/Basic/Basic.ino index 88099a5..63b2fc6 100644 --- a/examples/Modulino_Pixels/Basic/Basic.ino +++ b/examples/Modulino_Pixels/Basic/Basic.ino @@ -1,3 +1,11 @@ +/* + * Modulino Pixels - Basic + * + * This example code is in the public domain. + * Copyright (c) 2025 Arduino + * SPDX-License-Identifier: MPL-2.0 + */ + #include ModulinoPixels leds; diff --git a/examples/Modulino_Pixels/Simple_Animation/Simple_Animation.ino b/examples/Modulino_Pixels/Simple_Animation/Simple_Animation.ino index addec14..39d7ede 100644 --- a/examples/Modulino_Pixels/Simple_Animation/Simple_Animation.ino +++ b/examples/Modulino_Pixels/Simple_Animation/Simple_Animation.ino @@ -1,3 +1,11 @@ +/* + * Modulino Pixels - Simple Animation + * + * This example code is in the public domain. + * Copyright (c) 2025 Arduino + * SPDX-License-Identifier: MPL-2.0 + */ + #include ModulinoPixels leds; diff --git a/examples/Modulino_Thermo/Basic/Basic.ino b/examples/Modulino_Thermo/Basic/Basic.ino index 74894c2..e98afd5 100644 --- a/examples/Modulino_Thermo/Basic/Basic.ino +++ b/examples/Modulino_Thermo/Basic/Basic.ino @@ -1,3 +1,11 @@ +/* + * Modulino Thermo - Basic + * + * This example code is in the public domain. + * Copyright (c) 2025 Arduino + * SPDX-License-Identifier: MPL-2.0 + */ + #include // Create object instance diff --git a/examples/Modulino_Thermo/TemperatureHumidityMatrix/TemperatureHumidityMatrix.ino b/examples/Modulino_Thermo/TemperatureHumidityMatrix/TemperatureHumidityMatrix.ino index 20335f3..eab6001 100644 --- a/examples/Modulino_Thermo/TemperatureHumidityMatrix/TemperatureHumidityMatrix.ino +++ b/examples/Modulino_Thermo/TemperatureHumidityMatrix/TemperatureHumidityMatrix.ino @@ -1,3 +1,11 @@ +/* + * Modulino Thermo - Temperature Humidity Matrix + * + * This example code is in the public domain. + * Copyright (c) 2025 Arduino + * SPDX-License-Identifier: MPL-2.0 + */ + #include "Modulino.h" #include "ArduinoGraphics.h" #include "Arduino_LED_Matrix.h" diff --git a/examples/Utilities/AddressChanger/AddressChanger.ino b/examples/Utilities/AddressChanger/AddressChanger.ino index 3081be1..abe4181 100644 --- a/examples/Utilities/AddressChanger/AddressChanger.ino +++ b/examples/Utilities/AddressChanger/AddressChanger.ino @@ -1,3 +1,11 @@ +/* + * Modulino - Address Changer + * + * This example code is in the public domain. + * Copyright (c) 2025 Arduino + * SPDX-License-Identifier: MPL-2.0 + */ + #include "Wire.h" // Setting new_address to 0 means that the module will get back its original address diff --git a/examples/Utilities/FirmwareUpdater/FirmwareUpdater.ino b/examples/Utilities/FirmwareUpdater/FirmwareUpdater.ino index 0cabe5d..3d6068a 100644 --- a/examples/Utilities/FirmwareUpdater/FirmwareUpdater.ino +++ b/examples/Utilities/FirmwareUpdater/FirmwareUpdater.ino @@ -1,3 +1,11 @@ +/* + * Modulino - Firmware Updater + * + * This example code is in the public domain. + * Copyright (c) 2025 Arduino + * SPDX-License-Identifier: MPL-2.0 + */ + #if defined(ARDUINO_UNOWIFIR4) #include "ArduinoGraphics.h" #include "Arduino_LED_Matrix.h" diff --git a/examples/Utilities/Modulino_PlugNPlay/Modulino_PlugNPlay.ino b/examples/Utilities/Modulino_PlugNPlay/Modulino_PlugNPlay.ino index bf9ba8d..60368a3 100644 --- a/examples/Utilities/Modulino_PlugNPlay/Modulino_PlugNPlay.ino +++ b/examples/Utilities/Modulino_PlugNPlay/Modulino_PlugNPlay.ino @@ -1,3 +1,11 @@ +/* + * Modulino - Plug and Play + * + * This example code is in the public domain. + * Copyright (c) 2025 Arduino + * SPDX-License-Identifier: MPL-2.0 + */ + #include "Modulino.h" ModulinoButtons buttons; diff --git a/src/Modulino.cpp b/src/Modulino.cpp index 8a2b7e0..9c3ef2c 100644 --- a/src/Modulino.cpp +++ b/src/Modulino.cpp @@ -1,4 +1,4 @@ -// Copyright (c) 2024 Arduino SA +// Copyright (c) 2025 Arduino SA // SPDX-License-Identifier: MPL-2.0 #include "Modulino.h" diff --git a/src/Modulino.h b/src/Modulino.h index 128c46d..aa259da 100644 --- a/src/Modulino.h +++ b/src/Modulino.h @@ -1,9 +1,9 @@ +// Copyright (c) 2025 Arduino SA +// SPDX-License-Identifier: MPL-2.0 + #ifndef ARDUINO_LIBRARIES_MODULINO_H #define ARDUINO_LIBRARIES_MODULINO_H -// Copyright (c) 2024 Arduino SA -// SPDX-License-Identifier: MPL-2.0 - #include "Wire.h" #include // from stm32duino #include // from stm32duino