Skip to content

Commit 38a0039

Browse files
RobTillaartRobTillaart
committed
0.1.0 TLC5917
1 parent 5e4b3dd commit 38a0039

File tree

18 files changed

+1046
-0
lines changed

18 files changed

+1046
-0
lines changed

‎libraries/TLC5917/.arduino-ci.yml‎

Lines changed: 28 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,28 @@
1+
platforms:
2+
rpipico:
3+
board: rp2040:rp2040:rpipico
4+
package: rp2040:rp2040
5+
gcc:
6+
features:
7+
defines:
8+
- ARDUINO_ARCH_RP2040
9+
warnings:
10+
flags:
11+
12+
packages:
13+
rp2040:rp2040:
14+
url: https://github.com/earlephilhower/arduino-pico/releases/download/global/package_rp2040_index.json
15+
16+
compile:
17+
# Choosing to run compilation tests on 2 different Arduino platforms
18+
platforms:
19+
- uno
20+
# - due
21+
# - zero
22+
# - leonardo
23+
- m4
24+
- esp32
25+
# - esp8266
26+
# - mega2560
27+
- rpipico
28+

‎libraries/TLC5917/.github/FUNDING.yml‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,4 @@
1+
# These are supported funding model platforms
2+
3+
github: RobTillaart
4+
custom: "https://www.paypal.me/robtillaart"

‎libraries/TLC5917/.github/workflows/arduino-lint.yml‎

Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,16 @@
1+
2+
name: Arduino-lint
3+
4+
on: [push, pull_request]
5+
jobs:
6+
lint:
7+
runs-on: ubuntu-latest
8+
timeout-minutes: 5
9+
steps:
10+
- uses: actions/checkout@v4
11+
- uses: arduino/arduino-lint-action@v1
12+
with:
13+
library-manager: update
14+
compliance: strict
15+
verbose: false
16+

‎libraries/TLC5917/.github/workflows/arduino_test_runner.yml‎

Lines changed: 19 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,19 @@
1+
---
2+
name: Arduino CI
3+
4+
on: [push, pull_request]
5+
6+
jobs:
7+
runTest:
8+
runs-on: ubuntu-latest
9+
timeout-minutes: 20
10+
11+
steps:
12+
- uses: actions/checkout@v4
13+
- uses: ruby/setup-ruby@v1
14+
with:
15+
ruby-version: 2.6
16+
- run: |
17+
sudo sysctl vm.mmap_rnd_bits=28
18+
gem install arduino_ci
19+
arduino_ci.rb

‎libraries/TLC5917/.github/workflows/jsoncheck.yml‎

Lines changed: 19 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,19 @@
1+
name: JSON check
2+
3+
on:
4+
push:
5+
paths:
6+
- '**.json'
7+
pull_request:
8+
9+
jobs:
10+
test:
11+
runs-on: ubuntu-latest
12+
timeout-minutes: 5
13+
steps:
14+
- uses: actions/checkout@v4
15+
- name: json-syntax-check
16+
uses: limitusus/json-syntax-check@v2
17+
with:
18+
pattern: "\\.json$"
19+

‎libraries/TLC5917/CHANGELOG.md‎

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,12 @@
1+
# Change Log TLC5917
2+
3+
All notable changes to this project will be documented in this file.
4+
5+
The format is based on [Keep a Changelog](http://keepachangelog.com/)
6+
and this project adheres to [Semantic Versioning](http://semver.org/).
7+
8+
9+
## [0.1.0] - 2024-03-17
10+
- initial version
11+
12+

‎libraries/TLC5917/LICENSE‎

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
MIT License
2+
3+
Copyright (c) 2024-2024 Rob Tillaart
4+
5+
Permission is hereby granted, free of charge, to any person obtaining a copy
6+
of this software and associated documentation files (the "Software"), to deal
7+
in the Software without restriction, including without limitation the rights
8+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9+
copies of the Software, and to permit persons to whom the Software is
10+
furnished to do so, subject to the following conditions:
11+
12+
The above copyright notice and this permission notice shall be included in all
13+
copies or substantial portions of the Software.
14+
15+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21+
SOFTWARE.

‎libraries/TLC5917/README.md‎

Lines changed: 182 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,182 @@
1+
2+
[![Arduino CI](https://github.com/RobTillaart/TLC5917/workflows/Arduino%20CI/badge.svg)](https://github.com/marketplace/actions/arduino_ci)
3+
[![Arduino-lint](https://github.com/RobTillaart/TLC5917/actions/workflows/arduino-lint.yml/badge.svg)](https://github.com/RobTillaart/TLC5917/actions/workflows/arduino-lint.yml)
4+
[![JSON check](https://github.com/RobTillaart/TLC5917/actions/workflows/jsoncheck.yml/badge.svg)](https://github.com/RobTillaart/TLC5917/actions/workflows/jsoncheck.yml)
5+
[![GitHub issues](https://img.shields.io/github/issues/RobTillaart/TLC5917.svg)](https://github.com/RobTillaart/TLC5917/issues)
6+
7+
[![License: MIT](https://img.shields.io/badge/license-MIT-green.svg)](https://github.com/RobTillaart/TLC5917/blob/master/LICENSE)
8+
[![GitHub release](https://img.shields.io/github/release/RobTillaart/TLC5917.svg?maxAge=3600)](https://github.com/RobTillaart/TLC5917/releases)
9+
[![PlatformIO Registry](https://badges.registry.platformio.org/packages/robtillaart/library/TLC5917.svg)](https://registry.platformio.org/libraries/robtillaart/TLC5917)
10+
11+
12+
# TLC5917
13+
14+
TLC5917 is an Arduino library for TLC5917 8-Channel Constant-Current LED Sink Drivers.
15+
16+
17+
## Description
18+
19+
**Experimental**
20+
21+
This library allows control over the 8 channels of a TLC5917 device.
22+
23+
24+
TODO: Elaborate.
25+
26+
The TLC5916 is a derived class that is functional identical to the TLC5917 (for now).
27+
When implementation proceeds this might change.
28+
29+
The library is **experimental** and needs testing with Hardware.
30+
Please share your experiences.
31+
32+
33+
(Changes of the interface are definitely possible).
34+
35+
36+
#### Daisy chaining
37+
38+
This library supports daisy chaining.
39+
A constructor takes the number of devices as parameter and
40+
an internal buffer is allocated (8 elements per device).
41+
This internal buffer is clocked into the devices with **write()**.
42+
43+
44+
#### Related
45+
46+
- https://www.adafruit.com/product/1429
47+
- https://github.com/RobTillaart/TLC5917
48+
- https://github.com/RobTillaart/TLC5947
49+
- https://github.com/RobTillaart/PCA9634 (I2C)
50+
- https://github.com/RobTillaart/PCA9635 (I2C)
51+
- https://github.com/RobTillaart/PCA9685 (I2C)
52+
53+
54+
## Interface
55+
56+
```cpp
57+
#include TLC5917.h
58+
```
59+
60+
#### Constructor
61+
62+
- **TLC5917(uint8_t clock, uint8_t data, uint8_t latch, uint8_t blank)** constructor.
63+
Single device constructor.
64+
Defines the pins used for uploading / writing the PWM data to the module.
65+
The blank pin is explained in more detail below.
66+
- **TLC5917(int deviceCount, uint8_t clock, uint8_t data, uint8_t latch, uint8_t blank)** constructor.
67+
To be used for multiple devices, typical 2 or more.
68+
Defines the pins used for uploading / writing the PWM data to the module.
69+
The blank pin is explained in more detail below.
70+
- **~TLC5917()** destructor
71+
72+
#### Base
73+
74+
- **bool begin()** set the pinModes of the pins and their initial values.
75+
The TLC is disabled by default, as the device has random values in its grey-scale register.
76+
One must call **enable()** explicitly.
77+
- **int getChannels()** return the amount of channels == 8 x number of devices.
78+
- **bool setChannel(uint8_t channel, bool on)** set a channel on or off in the buffer.
79+
- **bool setChannel(uint8_t \* array)** copy a preset of channel settings in one call.
80+
- **bool setAll(bool on)** set all channels on or off.
81+
- **bool getChannel(uint8_t channel)** get current state of a channel in the cached buffer.
82+
- **void write()** writes the whole buffer (deviceCount x 8 values) to the device(s).
83+
- **void write(int n)** writes a part of the buffer (only **n** values) to the device.
84+
Typical used to speed up if less than max number e.g. only 17 channels are used
85+
and needs to be updated.
86+
**experimental, might have side effects**
87+
88+
89+
**write()** must be called after setting all values one wants to change.
90+
Doing that per channel is far less efficient if one wants to update multiple
91+
channels as fast as possible.
92+
See also **TLC5917_performance.ino** for an indication of time.
93+
94+
95+
#### Blank line TODO CHECK
96+
97+
The blank pin (OE line) is used to set all channels on or off.
98+
This allows to "preload" the registers with values and enable them all at once
99+
with very precise timing.
100+
101+
Default a TLC device is disabled (by begin), so one should enable it "manually".
102+
(P13 datasheet)
103+
104+
- **void enable()** all channels reflect last PWM values written.
105+
- **void disable()** all channels are off / 0.
106+
- **bool isEnabled()** returns status of blank line.
107+
108+
The library only supports one **enable() / blank line**. If you want
109+
a separate **enable()** per device you might need to connect the devices
110+
"in parallel" instead of "in series" (daisy chained).
111+
The blank parameter in the constructor should be set to -1 (out of range value).
112+
113+
114+
#### Configure gain
115+
116+
See datasheet page 23 for details.
117+
118+
- **void setCurrentAdjustMode()**
119+
- **void setNormalMode()**
120+
- **void writeConfiguration(uint8_t config)** See page 23 datasheet
121+
122+
| bit | 0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 |
123+
|:---------:|:---:|:---:|:---:|:---:|:---:|:---:|:---:|:---:|
124+
| meaning | CM | HC | CC0 | CC1 | CC2 | CC3 | CC4 | CC5 |
125+
| default | 1 | 1 | 1 | 1 | 1 | 1 | 1 | 1 |
126+
127+
CM limits the output current range.
128+
- High Current Multiplier (CM = 1): 10 mA to 120 mA.
129+
- Low Current Multiplier (CM = 0): 3 mA to 40 mA.
130+
131+
VG (voltage gain) = (1 + HC) × (1 + D/64) / 4
132+
where D = CC0 × 32 + CC1 × 16 + CC2 × 8 + CC3 × 4 + CC4 × 2 + CC5
133+
134+
CG (current gain) = VG x pow(3, CM - 1)
135+
136+
```
137+
Default
138+
CG = VG x 3;
139+
VG = 2 x ( 1 + 63/64) / 4 = 127/128
140+
```
141+
142+
TODO test with hardware to understand this in detail.
143+
Actual current depends on Rext (see datasheet).
144+
145+
146+
## Performance
147+
148+
See **TLC5917_performance.ino** for an indicative test.
149+
150+
151+
## Future
152+
153+
#### Must
154+
155+
- update documentation
156+
- buy hardware
157+
- test test test
158+
- get basic functionality running
159+
160+
#### Should
161+
162+
- get basic functionality running
163+
- investigate daisy chaining. (hardware needed).
164+
- max CLOCK speed when chained (50% DutyCycle)
165+
- what is clock in practice (e.g. an ESP32 240 MHz)
166+
167+
#### Could
168+
169+
- add examples
170+
171+
#### Wont
172+
173+
174+
## Support
175+
176+
If you appreciate my libraries, you can support the development and maintenance.
177+
Improve the quality of the libraries by providing issues and Pull Requests, or
178+
donate through PayPal or GitHub sponsors.
179+
180+
Thank you,
181+
182+

0 commit comments

Comments
 (0)