to bridge the gap between previous and current version
This commit is contained in:
parent
c8096349df
commit
8d78924d0d
21
LICENSE
Normal file
21
LICENSE
Normal file
@ -0,0 +1,21 @@
|
||||
MIT License
|
||||
|
||||
Copyright (c) 2025 FABLAB Bahrain
|
||||
|
||||
Permission is hereby granted, free of charge, to any person obtaining a copy
|
||||
of this software and associated documentation files (the "Software"), to deal
|
||||
in the Software without restriction, including without limitation the rights
|
||||
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
||||
copies of the Software, and to permit persons to whom the Software is
|
||||
furnished to do so, subject to the following conditions:
|
||||
|
||||
The above copyright notice and this permission notice shall be included in all
|
||||
copies or substantial portions of the Software.
|
||||
|
||||
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
||||
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
||||
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
||||
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
||||
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
||||
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
||||
SOFTWARE.
|
||||
160
documentation/README.md
Normal file
160
documentation/README.md
Normal file
@ -0,0 +1,160 @@
|
||||
## I2CMotor Arduino Library
|
||||
|
||||
**I2CMotor** is an all-in-one packed motor with I2C connection that offers a compact solution for precise motor control, allowing you to easily adjust both speed and direction via simple I2C commands. The ability to change the slave address means you can connect multiple motors to the same I2C bus and control them independently, making it highly scalable for robotics or automation projects. This product simplifies wiring, reduces microcontroller pin usage, and enables seamless integration and expansion in complex systems, all while providing reliable and configurable motor management in a single module. Additionally, when paired with an ESP32-C3-based controller, it can be used through Wi-Fi and Bluetooth connectivity, expanding control options beyond wired I2C communication for wireless operation and enhanced flexibility in IoT and robotics applications.
|
||||
|
||||
## Table of Contents
|
||||
|
||||
1. [Technical Drawings](#technical_drawings)
|
||||
2. [Features](#features)
|
||||
3. [Hardware Components Used](#hardware_components_list)
|
||||
4. [Installation](#installation)
|
||||
5. [Versatility](#versatility)
|
||||
6. [Usage](#usage)
|
||||
7. [API Overview](#api-overview)
|
||||
8. [Example Serial Commands](#example-serial-commands)
|
||||
9. [Notes](#notes)
|
||||
10. [Credits](#credits)
|
||||
11. [License](#license)
|
||||
12. [Project Image](#project-image)
|
||||
|
||||
---
|
||||
|
||||
### Technical Drawings
|
||||
|
||||
|
||||
|
||||
---
|
||||
|
||||
### Features
|
||||
|
||||
- **Vertical Load Handling:** Utilizes a high-quality thrust bearing to efficiently support vertical (axial) loads, ensuring reliable performance in demanding applications.
|
||||
- **Donut Shape:** Innovative donut-shaped design allows for pass-through of wires or shafts, simplifying cable management and enabling unique integration options.
|
||||
- **I2C Connectivity:** Supports I2C communication for easy and precise control of motor speed and direction using simple digital commands.
|
||||
- **Configurable Slave Address:** Allows the slave address to be changed, enabling multiple motors to operate independently on the same I2C bus.
|
||||
- **All-in-One Design:** Combines motor, controller, and interface in a single compact unit, reducing wiring complexity and saving space.
|
||||
- **Scalable and Versatile:** Ideal for robotics, automation, and projects requiring multiple motors or compact, integrated solutions.
|
||||
- **Easy Integration:** Streamlined installation process with minimal wiring and configuration needed, perfect for both prototyping and production environments.
|
||||
|
||||
---
|
||||
|
||||
### Hardware List
|
||||
|
||||
| Component | Purpose |
|
||||
|-----------------------|-----------------------------------------------------------------|
|
||||
| `ESP32C3 Super Mini` | Stamp size microcontroller with BLE and WiFi Connectivity |
|
||||
| `L298n` | Dual H-Bridge With Digital Control - For DC Motor Control |
|
||||
| `Standard DC Motor` | Standard Brushed DC Motor With Gear Box |
|
||||
| `Magnetic Encoder` | `Optional` - to leverage the use of a motor to work as a servo |
|
||||
|
||||
---
|
||||
|
||||
### Installation
|
||||
|
||||
1. Download or clone this repository.
|
||||
2. Copy the `I2CMotor`, `I2CMasterUtils`, and related library folders to your Arduino `libraries` directory.
|
||||
3. Restart the Arduino IDE.
|
||||
|
||||
#### File Overview
|
||||
|
||||
| File/Folder | Purpose |
|
||||
|---------------------|-------------------------------------------------------------|
|
||||
| `I2CMotor.h/.cpp` | Arduino class for controlling a DC motor via I2C |
|
||||
| `I2CMasterUtils.h/.cpp` | Utility functions for scanning I2C bus and changing addresses |
|
||||
| `I2CCommands.h` | I2C command definitions (e.g., address change command code) |
|
||||
| `Master.ino` | Example sketch for I2C master (controller) |
|
||||
| `Slave.ino` | Example sketch for I2C slave (motor driver) |
|
||||
| `keywords.txt` | Arduino IDE syntax highlighting |
|
||||
| `fablab_motor.jpg` | Project image |
|
||||
|
||||
---
|
||||
|
||||
### Versatility
|
||||
|
||||
The I2CMotor offers exceptional versatility, as it can function as a standalone device and can be adapted to be USB-controlled instead of relying solely on I2C communication. This flexibility allows users to easily integrate the motor into a wide range of projects and control environments. Furthermore, the motor’s firmware can be reprogrammed to support Wi-Fi and Bluetooth connectivity, enabling wireless control and making it ideal for modern applications in robotics, automation, and IoT. This adaptability ensures that the I2CMotor can meet diverse requirements and evolve with your project’s needs.
|
||||
|
||||
---
|
||||
|
||||
### Usage
|
||||
|
||||
#### 1. Include the Library
|
||||
|
||||
```cpp
|
||||
#include
|
||||
#include "I2CMotor.h"
|
||||
#include "I2CMasterUtils.h"
|
||||
```
|
||||
|
||||
#### 2. Master Example
|
||||
|
||||
- Upload `Master.ino` to your Arduino master device.
|
||||
- Use the serial monitor to:
|
||||
- Scan for devices: enter `s`
|
||||
- Change a device address: enter `ch ` (e.g., `ch 55 56`)
|
||||
- Set motor speed and direction: enter ` ` (e.g., `75 1` for 75% speed, forward)
|
||||
|
||||
#### 3. Slave Example
|
||||
|
||||
- Upload `Slave.ino` to your Arduino slave device.
|
||||
- The slave listens for I2C commands to set motor speed/direction or change its own I2C address (persistently via EEPROM).
|
||||
|
||||
---
|
||||
|
||||
### API Overview
|
||||
|
||||
**I2CMotor**
|
||||
|
||||
- `I2CMotor(uint8_t address = 0x55);`
|
||||
Create a motor object with a given I2C address.
|
||||
- `void begin();`
|
||||
Initialize I2C communication.
|
||||
- `void setSpeed(uint8_t speed, uint8_t direction);`
|
||||
Set motor speed (0–100) and direction (0 or 1).
|
||||
- `void stop();`
|
||||
Stop the motor.
|
||||
- `void setAddress(uint8_t newAddress);`
|
||||
Change the I2C address used by this object.
|
||||
|
||||
**I2CMasterUtils**
|
||||
|
||||
- `scanI2C(Stream &output = Serial);`
|
||||
Scan and print all I2C device addresses.
|
||||
- `changeSlaveAddress(uint8_t oldAddr, uint8_t newAddr, Stream &output = Serial);`
|
||||
Send command to change a device's I2C address.
|
||||
- `parseChangeAddressCommand(const String &input, uint8_t &oldAddr, uint8_t &newAddr);`
|
||||
Parse address change command from serial input.
|
||||
|
||||
---
|
||||
|
||||
### Example Serial Commands
|
||||
|
||||
- `s`
|
||||
Scan I2C bus for devices.
|
||||
- `ch 55 56`
|
||||
Change device address from `0x55` to `0x56`.
|
||||
- `75 1`
|
||||
Set motor speed to 75%, direction to forward (1).
|
||||
|
||||
---
|
||||
|
||||
### Notes
|
||||
|
||||
- The default I2C address is `0x55`. You can change it using the provided command.
|
||||
- The slave stores its address in EEPROM and will remember it after reset.
|
||||
- Modify pin definitions in `Slave.ino` as needed for your hardware.
|
||||
|
||||
---
|
||||
|
||||
### Credits
|
||||
|
||||
Developed by FABLAB Bahrain.
|
||||
|
||||
---
|
||||
|
||||
### License
|
||||
|
||||
This project is open-source; see the LICENSE file for details.
|
||||
|
||||
---
|
||||
|
||||
### Project Image
|
||||
|
||||
BIN
documentation/images/drawing.png
Normal file
BIN
documentation/images/drawing.png
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 76 KiB |
BIN
documentation/images/qr_fablab_motor.png
Normal file
BIN
documentation/images/qr_fablab_motor.png
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 94 KiB |
8
keywords.txt
Normal file
8
keywords.txt
Normal file
@ -0,0 +1,8 @@
|
||||
#######################################
|
||||
# Syntax Coloring Map for I2CMasterUtils
|
||||
#######################################
|
||||
|
||||
I2CMasterUtils KEYWORD1
|
||||
scanI2C KEYWORD2
|
||||
changeSlaveAddress KEYWORD2
|
||||
parseChangeAddressCommand KEYWORD2
|
||||
9
library.properties
Normal file
9
library.properties
Normal file
@ -0,0 +1,9 @@
|
||||
name=FABLAB Motor
|
||||
version=1.0.0
|
||||
author=Fatima Idrees <fatimaxidrees@gmail.com>
|
||||
maintainer=Fatima Idrees <fatimaxidrees@gmail.com>
|
||||
sentence=Control DC motors via I2C with scanning and configuration utilities.
|
||||
paragraph=I2CMasterUtils is a library developed by FABLAB Bahrain for controlling DC motors over the I2C protocol. It provides utilities for scanning the I2C bus, changing motor driver addresses, and parsing I2C command strings, making it easy to manage and configure I2C-connected DC motor controllers in your Arduino projects.
|
||||
category=Communication
|
||||
url=https://github.com/fablabbh/I2CMasterUtils
|
||||
architectures=*
|
||||
Loading…
x
Reference in New Issue
Block a user