mirror of
https://github.com/RobTillaart/Arduino.git
synced 2024-10-03 18:09:02 -04:00
165 lines
5.4 KiB
Markdown
165 lines
5.4 KiB
Markdown
|
|
[](https://github.com/marketplace/actions/arduino_ci)
|
|
[](https://github.com/RobTillaart/M5ROTATE8/actions/workflows/arduino-lint.yml)
|
|
[](https://github.com/RobTillaart/M5ROTATE8/actions/workflows/jsoncheck.yml)
|
|
[](https://github.com/RobTillaart/M5ROTATE8/issues)
|
|
|
|
[](https://github.com/RobTillaart/M5ROTATE8/blob/master/LICENSE)
|
|
[](https://github.com/RobTillaart/M5ROTATE8/releases)
|
|
[](https://registry.platformio.org/libraries/robtillaart/M5ROTATE8)
|
|
|
|
|
|
# M5ROTATE8
|
|
|
|
Arduino library for M5 8ROTATE 8x rotary encoders.
|
|
|
|
|
|
## Description
|
|
|
|
**Experimental**
|
|
|
|
M5ROTATE8 is an Arduino class to read the 8 rotary encoders of the
|
|
M5 8ENCODER module.
|
|
It also provides means to write RGB values to the 8 LED's in the same module.
|
|
|
|
The rotary encoders can be read as an absolute counter (since start or reset) or as an relative counter (since last time read).
|
|
The value can be both positive and negative depending on the direction of turns.
|
|
The absolute counters can be given an initial value.
|
|
The counters can be reset per channel.
|
|
The library can also read the key pressed status of every rotary encoder.
|
|
|
|
The library can read the state of the mini switch.
|
|
|
|
The library can set the RGB value of the 9 LEDS.
|
|
The RotaryEncoder module has no brightness, like the 8ANGLe unit does.
|
|
|
|
First tests with hardware have been done.
|
|
**Warning:** One strange observation, the RE makes steps of size 2 and occasionally step size 1.
|
|
This needs further investigation, so use with care.
|
|
|
|
Missing in the device is an interrupt signal e.g. on change.
|
|
One has to poll all channels for changes which is not efficient.
|
|
A single byte register that showed change since last read would allow to monitor
|
|
all 8 rotary encoders in one call.
|
|
|
|
Feedback is welcome!
|
|
|
|
|
|
#### I2C
|
|
|
|
The address range is in theory from 0..127, however the I2C specification
|
|
states it should be between 8 and 119 as some addresses are reserved.
|
|
The default address is **0x41** or **65**.
|
|
|
|
| clock | works | notes |
|
|
|:-------:|:-------:|:-------:|
|
|
| 100 KHz | yes |
|
|
| 200 KHz | yes |
|
|
| 400 KHz | yes | max speed advised.
|
|
| 600 KHz | no |
|
|
|
|
See log file performance sketch.
|
|
|
|
|
|
#### Accuracy
|
|
|
|
The overall behaviour looks not too bad, there are 30 steps per rotation.
|
|
The rotary encoders show a step size of 2 and sometimes a step size of 1.
|
|
So normally one rotation gives +60 or -60.
|
|
The step size needs investigation as I would expect step size 1, always.
|
|
|
|
|
|
#### Related
|
|
|
|
- https://github.com/RobTillaart/M5ANGLE8
|
|
- https://github.com/RobTillaart/M5ROTATE8
|
|
|
|
## Interface
|
|
|
|
```cpp
|
|
#include "M5ROTATE8.h"
|
|
```
|
|
|
|
#### Constructor part
|
|
|
|
- **M5ROTATE8(uint8_t address = M5ROTATE8_DEFAULT_ADDRESS, TwoWire \*wire = &Wire)** constructor.
|
|
Default address = 0x41, default Wire.
|
|
- **bool begin(int sda, int scl)** ESP32 et al.
|
|
- **bool begin()** initialize I2C, checks if connected.
|
|
- **bool isConnected()** checks if address is on the I2C bus.
|
|
- **bool setAddress(uint8_t address = M5ROTATE8_DEFAULT_ADDRESS)** set a new address for the device.
|
|
Default address = 0x41.
|
|
- **uint8_t getAddress()** convenience function.
|
|
- **uint8_t getVersion()** get firmware version from device.
|
|
|
|
|
|
#### Rotary encoder part
|
|
|
|
- **int32_t getAbsCounter(uint8_t channel)**
|
|
Read a absolute position of the rotary encoder since reset or start.
|
|
- **void setAbsCounter(uint8_t channel, int32_t value);
|
|
- **int32_t getRelCounter(uint8_t channel)**
|
|
Read a relative position of the rotary encoder since reset.
|
|
Note: this counter will reset after each read.
|
|
- **bool getKeyPressed(uint8_t channel)** get key status of the rotary encoder.
|
|
True is pressed.
|
|
- **bool resetCounter(uint8_t channel)** reset a rotary encoder.
|
|
- **void resetAll()** reset all counters to 0.
|
|
|
|
|
|
#### Input switch part
|
|
|
|
- **uint8_t inputSwitch()** read status of the switch.
|
|
|
|
|
|
#### LED part
|
|
|
|
- **bool writeRGB(uint8_t channel, uint8_t R, uint8_t G, uint8_t B)** Set the RGB value of a specific LED.
|
|
channel = 0..8
|
|
- **bool setAll(uint8_t R, uint8_t G, uint8_t B)** set all LEDs.
|
|
- **bool allOff()** switches all LEDs off.
|
|
|
|
|
|
## Future
|
|
|
|
#### Must
|
|
|
|
- improve documentation
|
|
- keep in sync with **M5ANGLE8** where possible.
|
|
- investigate step size 2 / 1.
|
|
- An easy patch: divide by 2 resulting in step size 1 or 0
|
|
|
|
|
|
#### Should
|
|
|
|
- error handling
|
|
- optimize low level calls
|
|
- merge into two functions => read/write array + length.
|
|
- resetAll() could be "one call"
|
|
- **bool readRGB(channel, &R, &G, &B)**
|
|
- or **uint32_t readRGB(uint8_t channel)**
|
|
- improve on return values of functions.
|
|
- improve performance
|
|
- investigate address changes
|
|
|
|
|
|
#### Could
|
|
|
|
- add examples
|
|
- digital lock
|
|
- add unit tests
|
|
|
|
|
|
#### Wont (unless)
|
|
|
|
|
|
## Support
|
|
|
|
If you appreciate my libraries, you can support the development and maintenance.
|
|
Improve the quality of the libraries by providing issues and Pull Requests, or
|
|
donate through PayPal or GitHub sponsors.
|
|
|
|
Thank you,
|
|
|
|
|