2021-01-29 06:31:58 -05:00
|
|
|
|
|
|
|
[![Arduino CI](https://github.com/RobTillaart/AD520X/workflows/Arduino%20CI/badge.svg)](https://github.com/marketplace/actions/arduino_ci)
|
2021-10-16 14:58:54 -04:00
|
|
|
[![Arduino-lint](https://github.com/RobTillaart/AD520X/actions/workflows/arduino-lint.yml/badge.svg)](https://github.com/RobTillaart/AD520X/actions/workflows/arduino-lint.yml)
|
|
|
|
[![JSON check](https://github.com/RobTillaart/AD520X/actions/workflows/jsoncheck.yml/badge.svg)](https://github.com/RobTillaart/AD520X/actions/workflows/jsoncheck.yml)
|
2023-10-15 08:03:19 -04:00
|
|
|
[![GitHub issues](https://img.shields.io/github/issues/RobTillaart/AD520X.svg)](https://github.com/RobTillaart/AD520X/issues)
|
|
|
|
|
2021-01-29 06:31:58 -05:00
|
|
|
[![License: MIT](https://img.shields.io/badge/license-MIT-green.svg)](https://github.com/RobTillaart/AD520X/blob/master/LICENSE)
|
|
|
|
[![GitHub release](https://img.shields.io/github/release/RobTillaart/AD520X.svg?maxAge=3600)](https://github.com/RobTillaart/AD520X/releases)
|
2023-10-15 08:03:19 -04:00
|
|
|
[![PlatformIO Registry](https://badges.registry.platformio.org/packages/robtillaart/library/AD520X.svg)](https://registry.platformio.org/libraries/robtillaart/AD520X)
|
2021-01-29 06:31:58 -05:00
|
|
|
|
2021-10-16 14:58:54 -04:00
|
|
|
|
2021-01-29 06:31:58 -05:00
|
|
|
# AD520X
|
|
|
|
|
2021-12-10 08:12:54 -05:00
|
|
|
Arduino library for SPI AD5204 and AD5206 digital potentiometers.
|
2021-01-29 06:31:58 -05:00
|
|
|
|
2022-10-15 13:46:24 -04:00
|
|
|
Works with the AD840x series too (see PR #15)
|
2021-08-22 04:47:15 -04:00
|
|
|
|
2021-10-16 14:58:54 -04:00
|
|
|
|
2021-01-29 06:31:58 -05:00
|
|
|
## Description
|
|
|
|
|
2021-12-10 08:12:54 -05:00
|
|
|
The library is experimental as not all functionality is tested (enough).
|
2021-01-29 06:31:58 -05:00
|
|
|
|
2021-10-16 14:58:54 -04:00
|
|
|
The **AD5204** (4 channels) and **AD5206** (6 channels) are SPI based digital potentiometers.
|
2021-01-29 06:31:58 -05:00
|
|
|
This library consists of a base class **AD520X** that does the work.
|
|
|
|
|
2021-10-16 14:58:54 -04:00
|
|
|
The interface is straightforward, one can set a value per channels between 0..255.
|
2021-01-29 06:31:58 -05:00
|
|
|
|
2022-09-19 04:24:53 -04:00
|
|
|
| type | channels | 1 kΩ | 10 kΩ | 50 kΩ | 100 kΩ | works |
|
|
|
|
|:---------|:----------:|:-----:|:-----:|:-----:|:------:|:----------|
|
|
|
|
| AD5204 | 4 | | V | V | V | confirmed |
|
|
|
|
| AD5206 | 6 | | V | V | V | confirmed |
|
|
|
|
| AD8400 | 1 | V | V | V | V | confirmed |
|
|
|
|
| AD8402 | 2 | V | V | V | V |
|
2022-10-15 13:46:24 -04:00
|
|
|
| AD8403 | 4 | V | V | V | V | confirmed | see PR #15
|
2021-08-22 04:47:15 -04:00
|
|
|
|
2022-10-15 13:46:24 -04:00
|
|
|
The library is not yet confirmed to work for **AD8402** (2 channels).
|
|
|
|
This device has a very similar interface (datasheet comparison) so it should work. If you can confirm the AD8402 works, please let me know.
|
2021-01-29 06:31:58 -05:00
|
|
|
|
2023-11-26 11:07:23 -05:00
|
|
|
#### 0.4.0 breaking change
|
|
|
|
|
|
|
|
The version 0.4.0 has breaking changes in the interface.
|
|
|
|
The essence is removal of ESP32 specific code from the library.
|
|
|
|
This makes it possible to support the ESP32-S3 and other processors in the future.
|
|
|
|
Also it makes the library a bit simpler to maintain.
|
|
|
|
|
2021-08-22 04:47:15 -04:00
|
|
|
|
2023-10-15 08:03:19 -04:00
|
|
|
#### Related
|
|
|
|
|
|
|
|
- https://github.com/RobTillaart/AD520x
|
|
|
|
- https://github.com/RobTillaart/AD524X
|
|
|
|
- https://github.com/RobTillaart/AD5245
|
|
|
|
- https://github.com/RobTillaart/AD5144A
|
|
|
|
- https://github.com/RobTillaart/AD5245
|
|
|
|
- https://github.com/RobTillaart/AD5263
|
|
|
|
- https://github.com/RobTillaart/X9C10X
|
|
|
|
|
|
|
|
|
2021-01-29 06:31:58 -05:00
|
|
|
## Interface
|
|
|
|
|
2023-10-15 08:03:19 -04:00
|
|
|
```cpp
|
|
|
|
#include "AD520X.h"
|
|
|
|
```
|
2021-01-29 06:31:58 -05:00
|
|
|
|
|
|
|
### Constructors
|
|
|
|
|
2023-11-26 11:07:23 -05:00
|
|
|
- **AD520X(uint8_t select, uint8_t reset, uint8_t shutdown, SPIClassRP2040 \* mySPI = &SPI)** constructor HW SPI (RP2040 specific)
|
|
|
|
- **AD520X(uint8_t select, uint8_t reset, uint8_t shutdown, SPIClass \* mySPI = &SPI)** constructor HW SPI
|
|
|
|
- **AD520X(uint8_t select, uint8_t reset, uint8_t shutdown, uint8_t dataOut, uint8_t clock)** constructor SW SPI
|
2021-01-29 06:31:58 -05:00
|
|
|
Base class, not to be used directly.
|
2023-11-26 11:07:23 -05:00
|
|
|
- **AD5204(select, reset, shutdown, ...)** has 4 channels. As above.
|
|
|
|
- **AD5206(select, reset, shutdown, ...)** has 6 channels. As above.
|
|
|
|
- **AD8400(select, reset, shutdown, ...)** has 1 channel. As above.
|
|
|
|
- **AD8402(select, reset, shutdown, ...)** has 2 channels. As above.
|
|
|
|
- **AD8403(select, reset, shutdown, ...)** has 4 channels. As above.
|
2021-10-16 14:58:54 -04:00
|
|
|
|
2023-11-26 11:07:23 -05:00
|
|
|
Note:
|
|
|
|
- hardware SPI is 10+ times faster on an UNO than software SPI.
|
|
|
|
- software SPI on ESP32 is about equally fast than hardware SPI.
|
2021-01-29 06:31:58 -05:00
|
|
|
|
2021-08-22 04:47:15 -04:00
|
|
|
|
2021-01-29 06:31:58 -05:00
|
|
|
### Base
|
2021-08-22 04:47:15 -04:00
|
|
|
|
2021-10-16 14:58:54 -04:00
|
|
|
Since 0.2.0 the functions have more default parameters. Potentiometer is default pot 0
|
2021-12-10 08:12:54 -05:00
|
|
|
and value is default the **AD520X_MIDDLE_VALUE** of 128.
|
2021-10-16 14:58:54 -04:00
|
|
|
|
2021-08-22 04:47:15 -04:00
|
|
|
- **void begin(uint8_t value = 128)** value is the initial value of all potentiometer.
|
2022-09-19 04:24:53 -04:00
|
|
|
- **void reset(uint8_t value = 128)** resets the device and sets all potentiometers to value, default 128.
|
|
|
|
|
2023-10-15 08:03:19 -04:00
|
|
|
### Value
|
2022-09-19 04:24:53 -04:00
|
|
|
|
2021-10-16 14:58:54 -04:00
|
|
|
- **bool setValue(uint8_t pm = 0, uint8_t value = 128)** set a potentiometer to a value.
|
|
|
|
Default value is middle value.
|
|
|
|
Returns true if successful, false if not.
|
2022-09-19 04:24:53 -04:00
|
|
|
- **bool setValue(uint8_t pmA, uint8_t pmB, uint8_t value)** set two potentiometers to same value.
|
|
|
|
Note, no default value!
|
|
|
|
Returns true if successful, false if not.
|
2021-12-10 08:12:54 -05:00
|
|
|
- **void setAll(uint8_t value = 128)** set all potentiometers to the same value e.g. 0 or max or mid value.
|
2022-09-19 04:24:53 -04:00
|
|
|
Can typically be used for **mute**.
|
2021-10-16 14:58:54 -04:00
|
|
|
- **uint8_t getValue(uint8_t pm = 0)** returns the last set value of a specific potentiometer.
|
2023-01-10 14:37:57 -05:00
|
|
|
- **setGroupValue(mask, value)** bit mask to set 0..8 channels in one call.
|
2022-09-19 04:24:53 -04:00
|
|
|
|
|
|
|
|
2023-11-26 11:07:23 -05:00
|
|
|
The library has defined **#define AD520X_MIDDLE_VALUE 128**
|
|
|
|
|
|
|
|
|
2023-10-15 08:03:19 -04:00
|
|
|
### Percentage
|
2022-09-19 04:24:53 -04:00
|
|
|
|
2023-11-26 11:07:23 -05:00
|
|
|
- **bool setPercentage(uint8_t pm = 0, float percentage = 50)** similar to setValue, percentage from 0..100%, default potmeter 0 and 50%.
|
2021-10-16 14:58:54 -04:00
|
|
|
Returns true when successful, false if not.
|
2022-09-19 04:24:53 -04:00
|
|
|
- **bool setPercentage(uint8_t pmA, uint8_t pmB, float percentage)** similar to setValue, percentage from 0..100%.
|
|
|
|
Note, no default value.
|
|
|
|
Returns true when successful, false if not.
|
2021-10-16 14:58:54 -04:00
|
|
|
- **float getPercentage(uint8_t pm = 0)** return the value of potentiometer pm as percentage.
|
2023-01-10 14:37:57 -05:00
|
|
|
- **setGroupPercentage(mask, value)** bit mask to set 0..8 channels in one call.
|
2021-08-22 04:47:15 -04:00
|
|
|
|
2021-12-10 08:12:54 -05:00
|
|
|
|
2021-08-22 04:47:15 -04:00
|
|
|
### Hardware SPI
|
|
|
|
|
2021-10-16 14:58:54 -04:00
|
|
|
To be used only if one needs a specific speed for hardware SPI.
|
|
|
|
Has no effect on software SPI.
|
2021-08-22 04:47:15 -04:00
|
|
|
|
2021-10-16 14:58:54 -04:00
|
|
|
- **void setSPIspeed(uint32_t speed)** set SPI transfer rate.
|
|
|
|
- **uint32_t getSPIspeed()** returns SPI transfer rate.
|
2021-08-22 04:47:15 -04:00
|
|
|
|
|
|
|
|
2021-01-29 06:31:58 -05:00
|
|
|
### Misc
|
2021-08-22 04:47:15 -04:00
|
|
|
|
2021-10-16 14:58:54 -04:00
|
|
|
- **uint8_t pmCount()** returns the number of internal potentiometers.
|
2021-08-22 04:47:15 -04:00
|
|
|
- **void powerOn()** switches the module on.
|
|
|
|
- **void powerOff()** switches the module off.
|
|
|
|
- **bool isPowerOn()** returns true if on (default) or false if off.
|
|
|
|
|
2021-01-29 06:31:58 -05:00
|
|
|
|
2023-11-26 11:07:23 -05:00
|
|
|
### Debugging
|
2021-12-10 08:12:54 -05:00
|
|
|
|
2023-11-26 11:07:23 -05:00
|
|
|
- **bool usesHWSPI()** returns true / false depending on constructor.
|
2021-12-10 08:12:54 -05:00
|
|
|
|
|
|
|
|
2021-01-29 06:31:58 -05:00
|
|
|
## Future
|
|
|
|
|
2022-10-15 13:46:24 -04:00
|
|
|
|
2022-09-19 04:24:53 -04:00
|
|
|
#### Must
|
|
|
|
|
2023-10-15 08:03:19 -04:00
|
|
|
- improve documentation
|
2022-09-19 04:24:53 -04:00
|
|
|
|
|
|
|
#### Should
|
|
|
|
|
2023-01-10 14:37:57 -05:00
|
|
|
- extend unit tests
|
2023-11-26 11:07:23 -05:00
|
|
|
- extent examples
|
2022-09-19 04:24:53 -04:00
|
|
|
|
2022-10-15 13:46:24 -04:00
|
|
|
#### Could (only if requested.)
|
|
|
|
|
|
|
|
- **AD520X_MIDDLE_VALUE** 127 ? (0.4.0?)
|
2023-10-15 08:03:19 -04:00
|
|
|
- **setSWSPIdelay(uint8_t del = 0)** to tune software SPI?
|
2022-10-15 13:46:24 -04:00
|
|
|
- bit delay / not byte delay
|
|
|
|
- unit microseconds
|
2023-10-15 08:03:19 -04:00
|
|
|
- if (_del) delayMicroseconds(_del/2); // pre and post pulse.
|
2023-01-10 14:37:57 -05:00
|
|
|
- **void setInvert(uint8_t pm)** invert flag per potentiometer.
|
|
|
|
- 0..255 -> 255..0
|
|
|
|
- 1 uint8_t can hold 8 flags
|
|
|
|
- **will slow performance**
|
|
|
|
- how does this work with **stereo** functions.
|
|
|
|
- at what level should invert work.
|
|
|
|
- **bool getInvert(uint8_t pm)**
|
|
|
|
|
2022-09-19 04:24:53 -04:00
|
|
|
#### Wont
|
|
|
|
|
|
|
|
- **void setGamma(uint8_t pm, float gamma)**
|
|
|
|
- logarithmic effect? easier with setPercentage()
|
2023-10-15 08:03:19 -04:00
|
|
|
- see https://github.com/RobTillaart/GAMMA library.
|
2021-08-22 04:47:15 -04:00
|
|
|
- **void follow(pm_B, pm_A, float percentage = 100)**
|
2021-01-29 06:31:58 -05:00
|
|
|
- makes pm_B follow pm_A unless pm_B is addressed explicitly
|
2022-09-19 04:24:53 -04:00
|
|
|
- e.g. to be used for **stereo** channels.
|
2021-01-29 06:31:58 -05:00
|
|
|
- array cascade = 0xFF or pm_A.
|
|
|
|
- It will follow pm_A for certain percentage default 100.
|
|
|
|
|
2023-10-15 08:03:19 -04:00
|
|
|
|
|
|
|
## 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,
|
|
|
|
|