denko 0.14.0 → 0.15.0

data/MICROCONTROLLERS.md

@@ -0,0 +1,103 @@
+# Supported Microcontrollers
+
+:green_heart: Full support :yellow_heart: Partial support :heart: Planned. No support yet :question: Works in theory. Untested in real hardware.
+
+## Espressif Chips with Wi-Fi (Except H2)
+[![ESP8266 Build Status](https://github.com/denko-rb/denko/actions/workflows/build_esp8266.yml/badge.svg)](https://github.com/denko-rb/denko/actions/workflows/build_esp8266.yml)
+[![ESP32 Build Status](https://github.com/denko-rb/denko/actions/workflows/build_esp32.yml/badge.svg)](https://github.com/denko-rb/denko/actions/workflows/build_esp32.yml)
+[![ESP32-C3 Build Status](https://github.com/denko-rb/denko/actions/workflows/build_esp32c3.yml/badge.svg)](https://github.com/denko-rb/denko/actions/workflows/build_esp32c3.yml)
+[![ESP32-C6 Build Status](https://github.com/denko-rb/denko/actions/workflows/build_esp32c6.yml/badge.svg)](https://github.com/denko-rb/denko/actions/workflows/build_esp32c6.yml)
+[![ESP32-H2 Build Status](https://github.com/denko-rb/denko/actions/workflows/build_esp32h2.yml/badge.svg)](https://github.com/denko-rb/denko/actions/workflows/build_esp32h2.yml)
+[![ESP32-S2 Build Status](https://github.com/denko-rb/denko/actions/workflows/build_esp32s2.yml/badge.svg)](https://github.com/denko-rb/denko/actions/workflows/build_esp32s2.yml)
+[![ESP32-S3 Build Status](https://github.com/denko-rb/denko/actions/workflows/build_esp32s3.yml/badge.svg)](https://github.com/denko-rb/denko/actions/workflows/build_esp32s3.yml)
+
+|    Chip        | Status          | Board Tested         | Notes |
+| :--------      | :------:        | :---------------     |------ |
+| ESP8266        | :green_heart:   | NodeMCU              |
+| ESP8285        | :question:      | DOIT ESP-Mx DevKit   | Should be identical to 8266. Not tested in hardware.
+| ESP32          | :green_heart:   | DOIT ESP32 DevKit V1 |
+| ESP32-S2       | :green_heart:   | LOLIN S2 Pico        | Native USB-CDC (broken in core 3.0+)
+| ESP32-S3       | :green_heart:   | LOLIN S3 V1.0.0      | Native USB-CDC (broken in core 3.0+)
+| ESP32-C3       | :green_heart:   | LOLIN C3 Mini V2.1.0 | Native USB-CDC (broken in core 3.0+)
+| ESP32-H2       | :green_heart:   | ESP32-H2-MINI-1      | No Wi-Fi. Native USB-CDC (broken in core 3.0+)
+| ESP32-C6       | :green_heart:   | ESP32-C6-WROOM-1     | Native USB-CDC (broken in core 3.0+)
+
+**Note:** For ESP32 chips using native USB-CDC, make sure `USB CDC On Boot` is `Enabled` in the IDE's `Tools` menu. Flashing from the CLI doesn't automatically enable this, so the IDE is recommended for now.
+
+**Note:** Since Arduino ESP32 Core version 3.0+, USB-CDC is very unreliable when sending lots of data both directions (something denko can do). It's a known issue in the core. Use a regular UART until it's fixed.
+
+## AVR/MegaAVR Based Arduino Products (and Clones)
+[![AVR Build Status](https://github.com/denko-rb/denko/actions/workflows/build_atmega_avr.yml/badge.svg)](https://github.com/denko-rb/denko/actions/workflows/build_atmega_avr.yml)
+[![MegaAVR Build Status](https://github.com/denko-rb/denko/actions/workflows/build_atmega_megaavr.yml/badge.svg)](https://github.com/denko-rb/denko/actions/workflows/build_atmega_megaavr.yml)
+
+|    Chip        | Status          | Products         | Notes |
+| :--------      | :------:        | :--------------- |------ |
+| ATmega168      | :green_heart:   | Duemilanove, Diecimila, Pro | Omits features. `denko targets` for info.
+| ATmega328      | :green_heart:   | Uno R3, Uno WiFi, Nano, Fio, Pro  |
+| ATmega32u4     | :green_heart:   | Leonardo, Micro, Leonardo ETH, Esplora, LilyPad USB |
+| ATmega1280     | :green_heart:   | Mega |
+| ATmega2560     | :green_heart:   | Mega2560, Arduino Mega ADK |
+| ATmega4809     | :green_heart:   | Nano Every, Uno WiFi Rev2 |
+
+**Note:** Only USB boards listed. Any board with a supported chip should work, once you can flash it and connect to serial.
+
+## ARM Based Arduino Products (and Clones)
+[![SAM3X Build Satus](https://github.com/denko-rb/denko/actions/workflows/build_atsam3x.yml/badge.svg)](https://github.com/denko-rb/denko/actions/workflows/build_atsam3x.yml)
+[![SAMD Build Satus](https://github.com/denko-rb/denko/actions/workflows/build_atsamd21.yml/badge.svg)](https://github.com/denko-rb/denko/actions/workflows/build_atsamd21.yml)
+[![RA4M1 Build Satus](https://github.com/denko-rb/denko/actions/workflows/build_ra4m1.yml/badge.svg)](https://github.com/denko-rb/denko/actions/workflows/build_ra4m1.yml)
+
+|    Chip        | Status          | Products         | Notes |
+| :--------      | :------:        | :--------------- |------ |
+| ATSAM3X8E      | :green_heart:   | Due | Native USB. Tone and infrared not supported
+| ATSAMD21       | :green_heart:   | Zero, M0 Series, Nano 33 IOT, MKR WiFi 1010 | Native USB
+| RA4M1          | :green_heart:   | Uno R4 Minima, Uno R4 WiFi | Infrared not supported
+
+## Arduino Networking
+
+|    Chip               | Status          | Products         | Notes |
+| :--------             | :------:        | :--------------- |------ |
+| Wiznet W5100/5500     | :green_heart:   | Ethernet Shield  | Wired Ethernet shield
+| HDG204 + AT32UC3      | :question:      | WiFi Shield      | Compiles. No test hardware
+| ATWINC1500            | :green_heart:   | MKR1000, WiFi Shield 101 | #define WIFI_101 for shield
+| u-blox NINA-W102      | :question:      | Uno WiFi Rev 2, MKR WiFi 1010, Nano 33 IOT | Compiles. No test hardware
+
+## Raspberry Pi Microcontrollers
+[![RP2040 Build Status](https://github.com/denko-rb/denko/actions/workflows/build_rp2040.yml/badge.svg)](https://github.com/denko-rb/denko/actions/workflows/build_rp2040.yml)
+
+|    Chip        | Status          | Board Tested            | Notes |
+| :--------      | :------:        | :---------------        |------ |
+| RP2040         | :green_heart:   | Raspberry Pi Pico (W)   |
+| RP2350         | :heart:         | Raspberry Pi Pico 2 (W) |
+
+## AVR Chips from [MightyCore](https://github.com/MCUdude/MightyCore)
+
+|    Chip        | Status          | Products         | Notes |
+| :--------      | :------:        | :--------------- |------ |
+| ATmega1284     | :heart:         | Used in many 8-bit 3D printer boards. |
+
+## Implemented Interfaces
+
+| Name                  | Status          | HW/SW | Component Class          | Notes |
+| :---------------      | :------:        | :---  | :--------------          | :---- |
+| Digital In            | :green_heart:   | H     | `DigitalIO::Input`       | 1ms - 128ms (4ms default) listen, poll, or read
+| Analog In (ADC)       | :green_heart:   | H     | `AnalogIO::Input`        | 1ms - 128ms (16ms default) listen, poll, or read
+| Digital Out           | :green_heart:   | H     | `DigitalIO::Output`      |
+| Analog Out (DAC)      | :green_heart:   | H     | `AnalogIO::Output`       | **Only** SAM3X, SAMD21, RA4M1, ESP32, ESP32-S2
+| PWM Out               | :green_heart:   | H     | `PulseIO::PWMOutput`     |
+| Servo/ESC Motor Drive | :green_heart:   | H     | See Motor Driver Table   | Depends on PWM
+| Tone Out (Sq. Wave)   | :green_heart:   | H     | `PulseIO::Buzzer`        | Except SAM3X. Uses PWM
+| I2C                   | :green_heart:   | H     | `I2C::Bus`               | Predetermined pins per board
+| I2C Bit-Bang          | :green_heart:   | S     | `I2C::BitBang`           | Any pins
+| SPI                   | :green_heart:   | H     | `SPI::Bus`               | Predetermined pins per board
+| SPI Bit-Bang          | :green_heart:   | S     | `SPI::BitBang`           | Any pins
+| UART                  | :green_heart:   | H     | `UART::Hardware`         | **Except** Atmega328, ATmega168
+| UART Bit-Bang         | :green_heart:   | S     | `UART::BitBang`          | **Only** ATmega328
+| Maxim OneWire         | :green_heart:   | S     | `OneWire::Bus`           | No overdrive
+| Infrared Output       | :green_heart:   | S     | `PulseIO::IROutput`      | **Except** SAM3X, RA4M1
+| Infrared Input        | :heart:         | S     | `PulseIO::IRInput`       | Doable with existing library
+| WS2812 RGB LEDs       | :green_heart:   | S     | `LED::WS2812`            |
+| ESP32-PCNT            | :heart:         | H     | -                        | **Only** ESP32. Pulse and encoder counter
+| ESP32-MCPWM           | :heart:         | H     | -                        | **Only** ESP32. Motor control PWM
+
+**Note:** When listening, the board checks the pin's value every **_2^n_** milliseconds (**_n_** from **_0_** to **_7_**), without further commands.
+Polling and reading follow a call and response pattern.

data/PERIPHERALS.md

@@ -0,0 +1,178 @@
+# Supported Peripherals
+
+:green_heart: Full support :yellow_heart: Partial support :heart: Planned. No support yet
+
+## Digital and Analog Input and Output
+
+| Name             | Status         | Interface    | Component Class            | Notes |
+| :--------------- | :------:       | :--------    | :---------------           |------ |
+| Button           | :green_heart:  | Digital In   | `DigitalIO::Button`        |
+| Relay            | :green_heart:  | Digital Out  | `DigitalIO::Relay`         |
+| Rotary Encoder   | :green_heart:  | Digital In   | `DigitalIO::RotaryEncoder` | Listens every 1ms
+| Potentiometer    | :green_heart:  | Analog In    | `AnalogIO::Potentiometer`  | Smoothing on by default
+| Joystick         | :green_heart:  | Analog In    | `AnalogIO::Joystick`       |
+
+## LED
+
+| Name               | Status             | Interface         | Component Class       | Notes |
+| :---------------   | :------:           | :--------         | :---------------      |------ |
+| LED                | :green_heart:      | Digi/Ana Out      | `LED::Base`           |
+| RGB LED            | :green_heart:      | Digi/Ana Out      | `LED::RGB`            |
+| 7 Segment Display  | :yellow_heart:     | Digital Out       | `LED::SevenSegment`   | No decimal point
+| 8x8 LED (MAX7219)  | :heart:            | SPI               | `LED::MAX7219`        |
+| TM1637             | :heart:            | SPI               | `LED::TM1637`         | 4x 7 Segment + Colon
+| TM1652             | :heart:            | SPI               | `LED::TM1652`         | 4x 7 Segment w/ decimal point + Colon
+| Neopixel / WS2812B | :green_heart:      | Adafruit Library  | `LED::WS2812`         |
+| Dotstar / APA102   | :green_heart:      | SPI               | `LED::APA102`         |
+
+## Display
+
+| Name                | Status         | Interface                    | Component Class     | Notes |
+| :---------------    | :------:       | :--------                    | :---------------    |------ |
+| HD44780 LCD         | :green_heart:  | Digital Out, Output Register | `Display::HD44780`  | Char LCD. Also works through PCF8574
+| Canvas              | :yellow_heart: | -                            | `Display::Canvas`   | Mono 2D graphics
+| SSD1306             | :green_heart:  | I2C or SPI                   | `Display::SSD1306`  | Mono OLED: 128x64, 128x32
+| SH1106              | :green_heart:  | I2C or SPI                   | `Display::SH1106`   | Mono OLED: 128x64
+| SH1107              | :green_heart:  | I2C or SPI                   | `Display::SH1107`   | Mono OLED: 128x128
+| PCD8544             | :green_heart:  | SPI                          | `Display::PCD8544`  | 84x48 Mono LCD (aka Nokia 5110)
+| ST7565              | :green_heart:  | SPI                          | `Display::ST7565`   | 128x64 Mono LCD
+| ST7302              | :green_heart:  | SPI                          | `Display::ST7302`   | 250x122 Mono Reflective LCD
+| LS027B7DH01         | :heart:        | SPI                          | `Display::SharpLCD` | 400x240 Mono Reflective LCD
+| SSD1680             | :green_heart:  | SPI                          | `Display::SSD1680`  | 296x128 Black/(Red)/White E-Paper (2.9")
+| SSD1681             | :green_heart:  | SPI                          | `Display::SSD1681`  | 200x200 Black/(Red)/White E-Paper (1.54")
+| IL0373              | :green_heart:  | SPI                          | `Display::IL0373`   | 212x104 Black/(Red)/White E-Paper (2.13")
+| ST7735S             | :heart:        | SPI                          | `Display::ST7735S`  | 160x128 RGB LCD
+| ST7789V             | :heart:        | SPI                          | `Display::ST7789V`  | 240x135 RGB LCD (TTGO)
+| ILI9341             | :heart:        | SPI                          | `Display::ILI9341`  | 240x320 RGB LCD
+| GC9107              | :heart:        | SPI                          | `Display::GC9107`   | 128x128 RGB LCD
+| GC9A01              | :heart:        | SPI                          | `Display::GCA9A01`  | 240x240 Round RGB LCD
+
+## Sound
+
+| Name             | Status         | Interface    | Component Class            | Notes |
+| :--------------- | :------:       | :--------    | :---------------           |------ |
+| Piezo Buzzer     | :green_heart:  | Tone Out     | `PulseIO::Buzzer`          | Frequency > 30Hz
+
+## Motors and Motor Drivers
+
+| Name                 | Status         | Interface      | Component Class    | Notes |
+| :---------------     | :------:       | :--------      | :---------------   |------ |
+| Generic Hobby Servo  | :green_heart:  | Servo/ESC PWM  | `Motor::Servo`     | Max depends on PWM channel count
+| Generic ESC          | :yellow_heart: | Servo/ESC PWM  | `Motor::Servo`     | Works. Needs its own class.
+| PCA9685              | :heart:        | I2C            | `PulseIO::PCA9685` | 16-ch, 12-bit PWM for servo or LED
+| L298N                | :green_heart:  | Digi + PWM Out | `Motor::L298`      | H-Bridge DC motor driver
+| DRV8833              | :heart:        | Digi + PWM Out | `Motor::DRV8833`   | H-Bridge DC motor driver
+| TB6612               | :heart:        | Digi + PWM Out | `Motor::TB6612`    | H-Bridge DC motor driver
+| AT8236               | :heart:        | Digi + PWM Out | `Motor::AT8236`    | H-Bridge DC motor driver
+| A3967                | :green_heart:  | Digital Out    | `Motor::A3967`     | 1-ch microstepper (EasyDriver)
+| A4988                | :yellow_heart: | DigitalOut     | `Motor::Stepper`   | 1-ch microstepper
+| TMC2209              | :heart:        | -              | -                  | 1-ch silent stepper driver
+
+## I/O Expansion
+
+| Name             | Status         | Interface  | Component Class      | Notes |
+| :--------------- | :------:       | :--------  | :---------------     |------ |
+| Input Register   | :green_heart:  | SPI        | `SPI::InputRegister` | Tested on CD4021B
+| Output Register  | :green_heart:  | SPI        | `SPI::OutputRegister`| Tested on 74HC595
+| PCF8574 Expander | :green_heart:  | I2C        | `DigitalIO::PCF8574` | 8-ch digital I/O. Commonly found on HD44780
+| ADS1100 ADC      | :green_heart:  | I2C        | `AnalogIO::ADS1100`  | 1-ch, 16-bit ADC. No continuous mode.
+| ADS1115 ADC      | :green_heart:  | I2C        | `AnalogIO::ADS1115`  | 4-ch, 16-bit ADC. Comparator not implemented.
+| ADS1118 ADC      | :green_heart:  | SPI        | `AnalogIO::ADS1118`  | 4-ch, 16-bit ADC + temperature
+| ADS1232 ADC      | :heart:        | SPI        | `AnalogIO::ADS1232`  | 2-ch, 24-bit ADC + temperature
+| PCF8591 ADC/DAC  | :heart:        | I2C        | `AnalogIO::PCF8591`  | 4-ch, 8-bit ADC + 1-ch 8-bit DAC
+| MCP4725 DAC      | :heart:        | I2C        | `AnalogIO::MCP4275`  | 1-ch, 12-bit DAC
+| PCA9548 I2C Mux  | :heart:        | I2C        | `I2C::PCA9548`       | 8-way I2C multiplexer
+
+## Environmental Sensors
+
+| Name             | Status         | Interface   | Component Class    | Type                     | Notes                  |
+| :--------------- | :------:       | :--------   | :---------------   |---------------           | ---------------------- |
+| MAX31850         | :heart:        | OneWire     | `Sensor::MAX31850` | Thermocouple             |
+| MAX6675          | :heart:        | SPI         | `Sensor::MAX6675`  | Thermocouple             |
+| DS18B20          | :green_heart:  | OneWire     | `Sensor::DS18B20`  | Temp                     |
+| DHT11/21/22      | :green_heart:  | Digi In/Out | `Sensor::DHT`      | Temp / RH                |
+| SHT30/31/35      | :green_heart:  | I2C         | `Sensor::SHT3X`    | Temp / RH                | M5Stack ENV III, one-shot only
+| SHT40/41         | :green_heart:  | I2C         | `Sensor::SHT4X`    | Temp / RH                |
+| QMP6988          | :green_heart:  | I2C         | `Sensor::QMP6988`  | Temp / Press             | M5Stack ENV III
+| BMP180           | :green_heart:  | I2C         | `Sensor::BMP180`   | Temp / Press             |
+| BMP280           | :green_heart:  | I2C         | `Sensor::BMP280`   | Temp / Press             |
+| BME280           | :green_heart:  | I2C         | `Sensor::BME280`   | Temp / Press / RH        |
+| BME680           | :heart:        | I2C         | `Sensor::BME680`   | Temp / Press / RH / TVOC |
+| HDC1080          | :green_heart:  | I2C         | `Sensor::HDC1080`  | Temp / RH                |
+| HTU21D           | :green_heart:  | I2C         | `Sensor::HTU21D`   | Temp / RH                | No user register read
+| HTU31D           | :green_heart:  | I2C         | `Sensor::HTU31D`   | Temp / RH                | No diagnostic read
+| AHT10/15         | :green_heart:  | I2C         | `Sensor::AHT1X`    | Temp / RH                |
+| AHT20/21/25      | :green_heart:  | I2C         | `Sensor::AHT2X`    | Temp / RH                |
+| AHT30            | :green_heart:  | I2C         | `Sensor::AHT3X`    | Temp / RH                |
+| ENS160           | :heart:        | I2C         | `Sensor::ENS160`   | eCO2 / TVOC / AQI        |
+| AGS02MA          | :heart:        | I2C         | `Sensor::AGS02MA`  | TVOC                     |
+| SCD40            | :heart:        | I2C         | `Sensor::SDC40`    | Temp / Press / CO2       |
+| CCS811           | :heart:        | I2C         | `Sensor::CCS811`   | eCO2                     |
+| MICS5524         | :heart:        | Analog In   | `Sensor::MICS5524` | CO/Alcohol/VOC           |
+
+## Light Sensors
+
+| Name             | Status         | Interface    | Component Class    | Notes |
+| :--------------- | :------:       | :--------    | :---------------   |------ |
+| BH1750           | :heart:        | Digital In   | `Sensor::BH1750`   | Ambient Light
+| TCS34725         | :heart:        | I2C          | `Sensor::TCS34725` | RGB
+| APDS9960         | :heart:        | I2C          | `Sensor::APDS9960` | Proximity, RGB, Gesture
+
+## PIR Motion Sensors
+| Name             | Status         | Interface    | Component Class      | Notes |
+| :--------------- | :------:       | :--------    | :---------------     |------ |
+| HC-SR501         | :green_heart:  | Digital In   | `Sensor::GenericPIR` |
+| HC-SR505         | :yellow_heart: | Digital In   | `Sensor::GenericPIR` |
+| AS312            | :green_heart:  | Digital In   | `Sensor::GenericPIR` |
+| AM312            | :yellow_heart: | Digital In   | `Sensor::GenericPIR` |
+
+## Distance Sensors
+
+| Name             | Status         | Interface    | Component Class    | Notes |
+| :--------------- | :------:       | :--------    | :---------------   |------ |
+| HC-SR04          | :green_heart:  | Digi In/Out  | `Sensor::HCSR04`   | Ultrasonic, 20-4000mm
+| RCWL-1601        | :green_heart:  | Digi In/Out  | `Sensor::HCSR04`   | Essentially a 3.3V version of HC-SR04
+| RCWL-9620        | :green_heart:  | I2C          | `Sensor::RCWL9260` | Ultrasonic, 20-4500mm
+| JSN-SR04T        | :green_heart:  | UART         | `Sensor::JSNSR04T` | Mode 2 ONLY. Use HC-SR04 driver for mode 0 or 4.
+| VL53L0X          | :yellow_heart: | I2C          | `Sensor::VL53L0X`  | Laser, 20 - 2000mm. Continuous mode only. No configuration.
+| GP2Y0E03         | :heart:        | I2C          | `Sensor::GP2Y0E03` | Infrared, 40 - 500mm
+
+## Inertial Measurement Units
+
+| Name             | Status         | Interface | Component Class    | Notes |
+| :--------------- | :------:       | :-------- | :---------------   |------ |
+| ADXL345          | :heart:        | I2C       | `Sensor::ADXL345`  | Accelerometer
+| IT3205           | :heart:        | I2C       | `Sensor::IT3205`   | Gyroscope
+| HMC5883L         | :heart:        | I2C       | `Sensor::HMC5883L` | Compass
+| MPU6050          | :heart:        | I2C       | `Sensor::MPU6050`  | Gyro + Accelerometer
+| MPU6886          | :heart:        | I2C       | `Sensor::MPU6886`  | Gyro + Accelerometer
+| BMI160           | :heart:        | I2C       | `Sensor::BMI160`   | Gyro + Accelerometer
+| LSM6DS3          | :heart:        | I2C       | `Sensor:LSM6DS3`   | Gyro + Accelerometer
+
+## Misc Sensors
+| Name             | Status         | Interface | Component Class    | Notes |
+| :--------------- | :------:       | :-------- | :---------------   |------ |
+| INA219           | :heart:        | I2C       | `Sensor::INA219`   | DC Current Sensor
+
+## Real Time Clocks
+
+| Name             | Status         | Interface | Component Class   | Notes |
+| :--------------- | :------:       | :-------- | :---------------  |------ |
+| DS1302           | :heart:        | I2C       | `RTC::DS1302`     |
+| DS1307           | :heart:        | I2C       | `RTC::DS1307`     |
+| DS3231           | :green_heart:  | I2C       | `RTC::DS3231`     | Alarms not implemented
+| PCF8563          | :heart:        | I2C       | `RTC::PCF8563`    |
+
+## GPS
+
+| Name             | Status         | Interface | Component Class   | Notes |
+| :--------------- | :------:       | :-------- | :---------------  |------ |
+| GT-U7            | :heart:        | UART      | -                 |
+
+## Miscellaneous
+
+| Name             | Status         | Interface  | Component Class      | Notes |
+| :--------------- | :------:       | :--------  | :---------------     |------ |
+| Board EEPROM     | :green_heart:  | Built-In   | `EEPROM::Board`      | Arduino ARM boards have no EEPROM
+| AT24C            | :green_heart:  | I2C        | `EEPROM::AT24C`      | I2C EEPROM (32, 64, 128 or 256 kib)
+| MFRC522          | :heart:        | SPI/I2C    | `DigitalIO::MFRC522` | RFID tag reader / writer

data/README.md

@@ -1,45 +1,52 @@
 # denko
 [![Test Status](https://github.com/denko-rb/denko/actions/workflows/ruby.yml/badge.svg)](https://github.com/denko-rb/denko/actions/workflows/ruby.yml)
 
-Program real-life electronics in pure Ruby. LEDs, buttons, sensors (and more) work just like any Ruby object:
+<img src="images/demo.gif" width="540" height="360" alt="Milk-V mruby GPIO demo">
+
+Program real-life electronics in Ruby. LEDs, buttons, sensors (and more) work just like any Ruby object:
 
 ```ruby
 led.blink 0.5
 
-lcd.print "Hello World!"
+lcd.text "Hello World!"
 
 reading = sensor.read
 
-button.down do
-  puts "Button pressed!"
-end
+button.down { puts "Button pressed!" }
+button.listen
 ```
 
 ## How It Works
 
-There are currently two ways to use denko. Both have the same user-friendly API, but the hardware can be very different. Here's a summary of each:
+<img src="images/layer_diagram.png" width="820" height="540" alt="Denko Layer Diagram">
+
+Denko aims to provide a Ruby API for you to directly control physical peripherals, while abstracting all the hardware and software complexity in between. There are currently 3 supported "stacks":
 
 ### Connected Microcontroller
-- Flash a microcontroller with the denko C firmware, so it can be "remote controlled"
-- Run a Ruby program on a "real" computer with the microcontroller connected
-- The microcontroller appears as an instance of `Denko::Board`
-- Calling methods on it will exchange messages that manipulate the real microcontroller
-- The microcontroller can only do the bare minimum to send and receive signals
-- Everything from peripheral drivers up happens in Ruby
+- Flash a [supported microcontroller](MICROCONTROLLERS.md) with the Denko firmware
+- Connect it to a PC running Ruby, over Serial, Ethernet, or Wi-Fi
+- The microcontroller does the "low-level" signal work, appearing as an instance of `Denko::Board` in Ruby
+- Ruby peripheral drivers, running on the PC, do the "high-level" work
 
 ### Single-Board-Computer
-- Ruby a Ruby program on the SBC
-- The SBC's own GPIO header appears as a `Denko::PiBoard` instance
-- Everything runs self-contained on the SBC
+- Install [denko-piboard](https://github.com/denko-rb/denko-piboard) on a Linux SBC
+- The included C extention makes the SBC's GPIO header available via a `Denko::PiBoard` instance
+- Use it in Ruby programs, self-contained on the SBC
+
+### mruby on Milk-V Duo
+- Download `mruby` and/or `mirb` binaries from the [mruby-denko-milkv-duo](https://github.com/denko-rb/mruby-denko-milkv-duo) repo onto your Milk-V Duo
+- Everything is included. Instances of `Denko::Board` in mruby  will use the Milk-V's GPIO
 
 **Notes:**
-- Peripheral classes are only in this gem, but are compatible with both types of board, and both gems.
-- That makes the [examples](examples) folder of this gem (mostly) relevant to both.
-- If using denko-piboard, ignore the hardware and installation sections here.
+- Peripheral drivers are implemented __only__ in this gem, and the source files are used by __all__ stacks
+- That makes the [examples folder](examples) in this gem relveant to all (ignoring hardware incompatibilities)
+- If using `denko-piboard` or `mruby-denko-milkv-duo`, ignore the hardware and installation sections here
 
 ## Supported Hardware
-
-[Microcontroller & Peripheral Support List](HARDWARE.md)
+- [Peripherals](PERIPHERALS.md)
+- [Microcontrollers](MICROCONTROLLERS.md)
+- [Single Board Computers](https://github.com/denko-rb/denko-piboard?tab=readme-ov-file#support)
+- [Milk-V Duo Boards](https://github.com/denko-rb/mruby-denko-milkv-duo?tab=readme-ov-file#supported-hardware)
 
 ## Installation
 
@@ -132,7 +139,7 @@ Most boards have a regular LED on-board. Test with the [blink](examples/led/buil
 #### Tutorial
 
 - [Here](tutorial) you will find a beginner-friendly tutorial, that goes through the basics, using commented examples and diagrams. Read the comments and try modifying the code. You will need the following:
-  - 1 compatible microcontroller (see [supported hardware](HARDWARE.md))
+  - 1 [compatible microcontroller](MICROCONTROLLERS.md)
   - 1 button or momentary switch
   - 1 potentiometer (any value)
   - 1 external RGB LED (4 legs common cathode, not a Neopixel or individually addressable)

data/denko.gemspec

@@ -7,9 +7,14 @@ Gem::Specification.new do |gem|
   gem.description   = %q{Electronics programming in Ruby}
   gem.summary       = %q{Use GPIO, PWM, I2C, SPI, and more, on a connected microcontroller, or single-board-computer}
   gem.homepage      = 'https://github.com/denko-rb/denko'
-  gem.files         = `git ls-files`.split($\)
   gem.licenses      = ['MIT']
 
+  # Exclude benchmarks, examples, images and tutorial to keep gem size down.
+  `git ls-files`.split($\).each do |filename|
+    next if filename.start_with?('benchmarks/', 'examples/', 'images/', 'tutorial/')
+    gem.files << "#{filename}"
+  end
+
   # Copy full submodule contents into the gem when building.
   # Credit:
   # https://gist.github.com/mattconnolly/5875987#file-gem-with-git-submodules-gemspec

data/lib/denko/analog_io/ads1118.rb

@@ -1,7 +1,7 @@
 module Denko
   module AnalogIO
     class ADS1118
-      include SPI::Peripheral::SinglePin
+      include SPI::Peripheral
       include Behaviors::Lifecycle
       include ADS111X
 
@@ -37,10 +37,10 @@ module Denko
       end
 
       def _temperature_read
-        # Wrap in mutex to not interfere with other reads.
-        mutex.synchronize do
-          _read([0b10000001, 0b10011011])
-        end
+        # Don't interfere with subcomponent reads.
+        mutex.lock
+        _read([0b10000001, 0b10011011])
+        mutex.unlock
       end
 
       def temperature_read(&block)

data/lib/denko/analog_io/ads111x.rb

@@ -71,29 +71,32 @@ module Denko
 
       def analog_read(pin, negative_pin=nil, gain=nil, sample_rate=nil)
         # Wrap in mutex so calls and callbacks are atomic.
-        mutex.synchronize do
-          # Default gain and sample rate.
-          gain        ||= 0b010
-          sample_rate ||= 0b100
+        mutex.lock
 
-          # Set these for callbacks.
-          self.active_pin   = pin
-          self.active_gain  = gain
+        # Default gain and sample rate.
+        gain        ||= 0b010
+        sample_rate ||= 0b100
 
-          # Set gain in upper config register.
-          raise ArgumentError "wrong gain: #{gain.inspect} given for ADS111X" unless PGA_RANGE.include?(gain)
-          config_register[0] = self.class::BASE_MSB | (gain << 1)
+        # Set these for callbacks.
+        self.active_pin   = pin
+        self.active_gain  = gain
 
-          # Set mux bits in upper config register.
-          mux_bits = pins_to_mux_bits(pin, negative_pin)
-          config_register[0] = config_register[0] | (mux_bits << 4)
+        # Set gain in upper config register.
+        raise ArgumentError "wrong gain: #{gain.inspect} given for ADS111X" unless PGA_RANGE.include?(gain)
+        config_register[0] = self.class::BASE_MSB | (gain << 1)
 
-          # Set sample rate in lower config_register.
-          raise ArgumentError "wrong sample_rate: #{sample_rate.inspect} given for ADS111X" unless SAMPLE_RATE_RANGE.include?(sample_rate)
-          config_register[1] = self.class::BASE_LSB | (sample_rate << 5)
+        # Set mux bits in upper config register.
+        mux_bits = pins_to_mux_bits(pin, negative_pin)
+        config_register[0] = config_register[0] | (mux_bits << 4)
 
-          read(config_register)
-        end
+        # Set sample rate in lower config_register.
+        raise ArgumentError "wrong sample_rate: #{sample_rate.inspect} given for ADS111X" unless SAMPLE_RATE_RANGE.include?(sample_rate)
+        config_register[1] = self.class::BASE_LSB | (sample_rate << 5)
+
+        result = read(config_register)
+        mutex.unlock
+
+        result
       end
 
       def pins_to_mux_bits(pin, negative_pin)
@@ -126,7 +129,8 @@ module Denko
       end
 
       def mutex
-        @mutex ||= Mutex.new
+        # mruby doesn't have Thread or Mutex, so only stub there.
+        @mutex ||= Denko.mruby? ? Denko::MutexStub.new : Mutex.new
       end
 
       def config_register

data/lib/denko/analog_io/joystick.rb

@@ -0,0 +1,87 @@
+module Denko
+  module AnalogIO
+    class Joystick
+      include Behaviors::MultiPin
+      include Behaviors::Lifecycle
+
+      def initialize_pins(options={})
+        proxy_pin(:x, AnalogIO::Input)
+        proxy_pin(:y, AnalogIO::Input)
+      end
+
+      after_initialize do
+        # Midpoint as float
+        @mid  = board.adc_high / 2.0
+
+        # Invert settings as +1 or -1 multipliers
+        @invert_x = params[:invert_x] ? -1 : 1
+        @invert_y = params[:invert_y] ? -1 : 1
+
+        # Swap axes if neeeded
+        @x_key = :x
+        @y_key = :y
+        swap_axes if params[:swap_axes]
+
+        # Deadzones as percentages
+        @deadzone = 0
+        @maxzone  = @mid
+        @deadzone = ((params[:deadzone] * @mid) / 100).round if params[:deadzone]
+        @maxzone  = ((params[:maxzone] * @mid) / 100).round if params[:maxzone]
+
+        # Per axis callbacks
+        x.on_data { |value| state[@x_key] = raw_to_percent(value, @invert_x) }
+        y.on_data { |value| state[@y_key] = raw_to_percent(value, @invert_y) }
+      end
+
+      def swap_axes
+        if @x_key == :x
+          @x_key = :y
+          @y_key = :x
+        else
+          @x_key = :x
+          @y_key = :y
+        end
+      end
+
+      def invert_x
+        @invert_x = @invert_x * -1
+      end
+
+      def invert_y
+        @invert_y = @invert_y * -1
+      end
+
+      def state
+        @state ||= { x: nil, y: nil }
+      end
+
+      def raw_to_percent(value, invert)
+        float = (value - @mid) * invert
+        abs   = float.abs
+        if abs < @deadzone
+          return 0
+        elsif abs > @maxzone
+          return (float > 0) ? 100 : -100
+        else
+          return ((float * 100) / @mid).round
+        end
+      end
+
+      def read
+        x.read
+        y.read
+        state
+      end
+
+      def listen(divider=16)
+        x.listen(divider)
+        y.listen(divider)
+      end
+
+      def stop
+        x.stop
+        y.stop
+      end
+    end
+  end
+end

data/lib/denko/analog_io/potentiometer.rb

@@ -1,12 +1,8 @@
 module Denko
   module AnalogIO
     class Potentiometer < Input
-      include Behaviors::Lifecycle
-
       after_initialize do
-        # Enable smoothing and start listening immediately at ~125 Hz.
-        self.smoothing = true
-        listen(8)
+        @divider ||= params[:divider] || 8
       end
     end
   end

data/lib/denko/analog_io.rb

@@ -1,12 +1,26 @@
+# Represent files to be autoloaded in CRuby as an Array.
+# This allows Mruby::Build to parse and preload them instead.
+ANALOG_IO_FILES = [
+  [:InputHelper,    "input_helper"],
+  [:Input,          "input"],
+  [:Output,         "output"],
+  [:Potentiometer,  "potentiometer"],
+  [:Joystick,       "joystick"],
+  [:ADS111X,        "ads111x"],
+  [:ADS1100,        "ads1100"],
+  [:ADS1115,        "ads1115"],
+  [:ADS1118,        "ads1118"],
+]
+
 module Denko
   module AnalogIO
-    autoload :InputHelper,    "#{__dir__}/analog_io/input_helper"
-    autoload :Input,          "#{__dir__}/analog_io/input"
-    autoload :Output,         "#{__dir__}/analog_io/output"
-    autoload :Potentiometer,  "#{__dir__}/analog_io/potentiometer"
-    autoload :ADS111X,        "#{__dir__}/analog_io/ads111x"
-    autoload :ADS1100,        "#{__dir__}/analog_io/ads1100"
-    autoload :ADS1115,        "#{__dir__}/analog_io/ads1115"
-    autoload :ADS1118,        "#{__dir__}/analog_io/ads1118"
+    ANALOG_IO_FILES.each do |file|
+      file_path = "#{__dir__}/analog_io/#{file[1]}"
+      if file[0]
+        autoload file[0], file_path
+      else
+        require file_path
+      end
+    end
   end
 end

data/lib/denko/behaviors/bus_controller.rb

@@ -5,7 +5,8 @@ module Denko
       include Subcomponents
 
       def mutex
-        @mutex ||= Mutex.new
+        # mruby doesn't have Thread or Mutex, so only stub there.
+        @mutex ||= Denko.mruby? ? Denko::MutexStub.new : Mutex.new
       end
     end
   end

data/lib/denko/behaviors/bus_peripheral.rb

@@ -7,7 +7,7 @@ module Denko
       alias  :bus :board
 
       before_initialize do
-        params[:board] ||= params[:bus]
+        params[:board] = params[:bus] if params[:bus]
       end
 
       def atomically(&block)