Skip to content

Commit a4c8045

Browse files
RobTillaartRobTillaart
authored
update build-CI, readme, badges, readability (#3)
* update build-CI, * readme, badges, * improve readability
1 parent 25f7766 commit a4c8045

File tree

14 files changed

+122
-55
lines changed

14 files changed

+122
-55
lines changed

‎.arduino-ci.yml‎

Lines changed: 5 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -2,6 +2,10 @@ compile:
22
# Choosing to run compilation tests on 2 different Arduino platforms
33
platforms:
44
- uno
5-
- leonardo
65
- due
76
- zero
7+
- leonardo
8+
- m4
9+
- esp32
10+
- esp8266
11+
- mega2560

‎.github/workflows/arduino_test_runner.yml‎

Lines changed: 7 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -4,10 +4,14 @@ name: Arduino CI
44
on: [push, pull_request]
55

66
jobs:
7-
arduino_ci:
7+
runTest:
88
runs-on: ubuntu-latest
99

1010
steps:
1111
- uses: actions/checkout@v2
12-
- uses: Arduino-CI/action@master
13-
# Arduino-CI/[email protected]
12+
- uses: ruby/setup-ruby@v1
13+
with:
14+
ruby-version: 2.6
15+
- run: |
16+
gem install arduino_ci
17+
arduino_ci.rb

‎README.md‎

Lines changed: 39 additions & 15 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,7 @@
11

22
[![Arduino CI](https://github.com/RobTillaart/rotaryDecoder/workflows/Arduino%20CI/badge.svg)](https://github.com/marketplace/actions/arduino_ci)
3+
[![Arduino-lint](https://github.com/RobTillaart/rotaryDecoder/actions/workflows/arduino-lint.yml/badge.svg)](https://github.com/RobTillaart/rotaryDecoder/actions/workflows/arduino-lint.yml)
4+
[![JSON check](https://github.com/RobTillaart/rotaryDecoder/actions/workflows/jsoncheck.yml/badge.svg)](https://github.com/RobTillaart/rotaryDecoder/actions/workflows/jsoncheck.yml)
35
[![License: MIT](https://img.shields.io/badge/license-MIT-green.svg)](https://github.com/RobTillaart/rotaryDecoder/blob/master/LICENSE)
46
[![GitHub release](https://img.shields.io/github/release/RobTillaart/rotaryDecoder.svg?maxAge=3600)](https://github.com/RobTillaart/rotaryDecoder/releases)
57

@@ -11,48 +13,62 @@ Arduino library for a PCF8574 based rotary decoder - supports 4 RE.
1113

1214
## Description
1315

14-
Experimental - not tested yet
16+
This experimental library uses a PCF8574 to read the pulses of a rotary encoder.
17+
As a PCF8574 has 8 lines up to 4 decoders can be read over I2C.
18+
The PCF interrupt line can be used to detect changes in the position of the encoders.
19+
20+
If less than 4 rotary encoders are connected one should use the lower bit lines as the
21+
library assumes these are used. Furthermore it is advised to connect the free PCF8574
22+
pins to GND so you will not get unintended interrupts.
23+
1524

1625
## Interface
1726

1827
- **rotaryDecoder(const int8_t address, TwoWire \*wire = Wire);**
19-
- **bool begin(uint8_t sda, uint8_t scl, uint8_t cnt = 4)** ESP32 ea initializes the class.
20-
sets I2C pins.
21-
cnt is the number of rotary encoders connected.
22-
returns true if the PCF8574 is on the I2C bus.
23-
- **bool begin(uint8_t cnt = 4)** UNO ea. initializes the class.
24-
cnt is the number of rotary encoders connected.
25-
returns true if the PCF8574 is on the I2C bus.
28+
- **bool begin(uint8_t sda, uint8_t scl, uint8_t count = 4)** ESP32 ea initializes the class
29+
by setting the I2C sda and scl pins.
30+
count is the number of rotary encoders connected. (Max 4 per PCF8574)
31+
Returns true if the PCF8574 is on the I2C bus.
32+
- **bool begin(uint8_t count = 4)** UNO ea. initializes the class.
33+
count is the number of rotary encoders connected. (Max 4 per PCF8574)
34+
Returns true if the PCF8574 is on the I2C bus.
2635
- **bool isConnected()** returns true if the PCF8574 is on the I2C bus.
2736

37+
2838
## Core functions
2939

30-
- **void readInitialState()** read the inital state of the 4 rotary encoders. typically called in setup only, or after a sleep e.g. in combination with **setValue()**
40+
- **void readInitialState()** read the initial state of the 4 rotary encoders.
41+
Typically called in setup only, or after a sleep e.g. in combination with **setValue()**
3142
- **bool checkChange()** polling to see if one or more RE have changed, without updating the counters.
3243
- **void update()** update the internal counters of the RE. These will add +1 or -1 depending on direction.
33-
- **void updateSingle()** update the internal counters of the RE. This will add +1 +2 or +3 as it assumes that the rotary encoder only goes into a single direction.
44+
- **void updateSingle()** update the internal counters of the RE. This will add +1 +2 or +3
45+
as it assumes that the rotary encoder only goes into a single direction.
46+
3447

3548
## Counters
3649

3750
- **uint32_t getValue(uint8_r re)** returns the RE counter.
38-
- **void setValue(uint8_r re, uint32_t val = 0)** (re)set the internal counter to val, default 0
51+
- **void setValue(uint8_r re, uint32_t value = 0)** (re)set the internal counter to value, default 0
3952

4053

4154
## Debugging
4255

43-
- **int8_t getLastPosition(uint8_r re)**
56+
- **int8_t getLastPosition(uint8_r re)** returns last position.
4457

4558

4659
## Performance
4760

4861
As the decoder is based upon a PCF8574, a I2C device, the performance is affected by the
49-
clockspeed of the I2C bus. All four core functions have one call to **\_read()** which is the most expensive part.
62+
clock speed of the I2C bus. All four core functions have one call to **\_read8()** which
63+
is the most expensive part.
5064

5165
Early tests gave the following indicative times (Arduino UNO) for the **update()**
5266
function (with no updates it is ~8 us faster). Note that above 500KHz the gain becomes less
53-
while reliability of signal decreases. (500KHz is ~3x faster than 100 KHz)
67+
while reliability of signal decreases. (500KHz is about ~3x faster than 100 KHz)
68+
As 400 KHz is a standard I2C clock speed it is the preferred one.
69+
5470

55-
| I2C speed | time (us) | delta | %% |
71+
| I2C speed | time (us) | delta | %% |
5672
|:---------:|:---------:|:-----:|:-----:|
5773
| 100 KHz | 247 | | |
5874
| 200 KHz | 146 | 99 | 40% |
@@ -62,6 +78,7 @@ while reliability of signal decreases. (500KHz is ~3x faster than 100 KHz)
6278
| 600 KHz | 79 | 5 | 6% |
6379
| 700 KHz | 73 | 6 | 8% |
6480

81+
6582
At @400KHz it can update 4 rotary encoders in ~100us.
6683
At a 50% update percentage this implies a max of about
6784
5000 **update()** calls per second in theory
@@ -75,3 +92,10 @@ assuming 4 pulses == 360
7592

7693
See examples..
7794

95+
96+
## Future
97+
98+
- test with a high speed drill like a Dremel-tool.
99+
- update documentation
100+
- picture how to connect e.g 2 RE's which pins to used
101+

‎examples/rotaryDecoder_demo_interrupt/rotaryDecoder_demo_interrupt.ino‎

Lines changed: 4 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -3,7 +3,7 @@
33
// AUTHOR: Rob Tillaart
44
// DATE: 2021-05-08
55
//
6-
// PUPROSE: demo
6+
// PUPROSE: demo interrupt controlled rotary decoder
77

88
// connect up to 4 rotary encoders to 1 PCF8574.
99
//
@@ -15,6 +15,7 @@
1515
//
1616
// SDA A4
1717
// SCL A5
18+
//
1819
// INT 2
1920
//
2021

@@ -26,8 +27,10 @@ rotaryDecoder decoder(0x20);
2627

2728
volatile bool flag = false;
2829

30+
2931
void moved()
3032
{
33+
// one should not read the PPCF8574 in the interrupt routine.
3134
flag = true;
3235
}
3336

‎examples/rotaryDecoder_demo_polling/rotaryDecoder_demo_polling.ino‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -17,11 +17,13 @@
1717
// SCL A5
1818
//
1919

20+
2021
#include "Wire.h"
2122
#include "rotaryDecoder.h"
2223

2324
rotaryDecoder decoder(0x20);
2425

26+
2527
void setup()
2628
{
2729
Serial.begin(115200);
@@ -36,6 +38,7 @@ void setup()
3638
}
3739

3840

41+
3942
void loop()
4043
{
4144
if (decoder.checkChange())
@@ -54,3 +57,4 @@ void loop()
5457

5558

5659
// -- END OF FILE --
60+

‎examples/rotaryDecoder_demo_simple/rotaryDecoder_demo_simple.ino‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -17,11 +17,13 @@
1717
// SCL A5
1818
//
1919

20+
2021
#include "Wire.h"
2122
#include "rotaryDecoder.h"
2223

2324
rotaryDecoder decoder(0x20);
2425

26+
2527
void setup()
2628
{
2729
Serial.begin(115200);
@@ -54,3 +56,4 @@ void loop()
5456

5557

5658
// -- END OF FILE --
59+

‎examples/rotaryDecoder_demo_single/rotaryDecoder_demo_single.ino‎

Lines changed: 5 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -3,9 +3,10 @@
33
// AUTHOR: Rob Tillaart
44
// DATE: 2021-05-08
55
//
6-
// PUPROSE: demo
6+
// PUPROSE: demo single direction rotary decoder.
77

88
// note this is used for e.g. RPM counters that are unidirectional.
9+
// all moves are interpreted as same direction.
910

1011
// connect up to 4 rotary encoders to 1 PCF8574.
1112
//
@@ -19,11 +20,13 @@
1920
// SCL A5
2021
//
2122

23+
2224
#include "Wire.h"
2325
#include "rotaryDecoder.h"
2426

2527
rotaryDecoder decoder(0x20);
2628

29+
2730
void setup()
2831
{
2932
Serial.begin(115200);
@@ -56,3 +59,4 @@ void loop()
5659

5760

5861
// -- END OF FILE --
62+

‎examples/rotaryDecoder_performance/rotaryDecoder_performance.ino‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -17,11 +17,13 @@
1717
// SCL A5
1818
//
1919

20+
2021
#include "Wire.h"
2122
#include "rotaryDecoder.h"
2223

2324
rotaryDecoder decoder(0x20);
2425

26+
2527
void setup()
2628
{
2729
Serial.begin(115200);

‎keywords.txt‎

Lines changed: 9 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
1-
# Syntax Coloring Map For rotaryDecoder
1+
# Syntax Colouring Map For rotaryDecoder
22

3-
# Datatypes (KEYWORD1)
3+
# Data types (KEYWORD1)
44
rotaryDecoder KEYWORD1
55

66
# Methods and Functions (KEYWORD2)
@@ -10,6 +10,13 @@ isConnected KEYWORD2
1010
readInitialState KEYWORD2
1111
checkChange KEYWORD2
1212
update KEYWORD2
13+
updateSingle KEYWORD2
14+
15+
getValue KEYWORD2
16+
setValue KEYWORD2
17+
18+
getLastPosition KEYWORD2
19+
1320

1421
# Constants (LITERAL1)
1522
ROTARY_DECODER_LIB_VERSION LITERAL1

‎library.json‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -15,7 +15,7 @@
1515
"type": "git",
1616
"url": "https://github.com/RobTillaart/rotaryDecoder.git"
1717
},
18-
"version": "0.1.0",
18+
"version": "0.1.1",
1919
"license": "MIT",
2020
"frameworks": "arduino",
2121
"platforms": "*"

0 commit comments

Comments
 (0)