denko 0.13.0 → 0.13.2

data/HARDWARE.md

@@ -2,22 +2,32 @@
 
 :green_heart: Full support :yellow_heart: Partial support :heart: Planned. No support yet :question: Works in theory. Untested in real hardware.
 
-### Microchip/Atmel Chips in Arduino Products (and Compatibles)
-[![AVR Build Status](https://github.com/denko-rb/denko/actions/workflows/build_avr.yml/badge.svg)](https://github.com/denko-rb/denko/actions/workflows/build_avr.yml) [![MegaAVR Build Status](https://github.com/denko-rb/denko/actions/workflows/build_megaavr.yml/badge.svg)](https://github.com/denko-rb/denko/actions/workflows/build_megaavr.yml) [![SAM3X Build Satus](https://github.com/denko-rb/denko/actions/workflows/build_sam3x.yml/badge.svg)](https://github.com/denko-rb/denko/actions/workflows/build_sam3x.yml) [![SAMD Build Satus](https://github.com/denko-rb/denko/actions/workflows/build_samd.yml/badge.svg)](https://github.com/denko-rb/denko/actions/workflows/build_samd.yml)
+### AVR/MegaAVR Based in Arduino Products (and Clones)
+[![AVR Build Status](https://github.com/denko-rb/denko/actions/workflows/build_avr.yml/badge.svg)](https://github.com/denko-rb/denko/actions/workflows/build_avr.yml)
+[![MegaAVR Build Status](https://github.com/denko-rb/denko/actions/workflows/build_megaavr.yml/badge.svg)](https://github.com/denko-rb/denko/actions/workflows/build_megaavr.yml)
 
 |    Chip        | Status          | Products         | Notes |
 | :--------      | :------:        | :--------------- |------ |
 | ATmega168      | :green_heart:   | Duemilanove, Diecimila, Pro | Features omitted to save memory. `denko targets` for more info.
-| ATmega328      | :green_heart:   | Uno, Nano, Fio, Pro  |
+| 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     | :question:      | Nano Every, Uno WiFi Rev2 | No hardware to test, but should work
-| ATSAM3X8E      | :yellow_heart:  | Due | Native USB port. Tone, and IR Out don't work.
-| ATSAMD21       | :green_heart:   | Zero, M0, M0 Pro | Native USB port. I2C seems stuck on 100 kHz.
 
 **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_sam3x.yml/badge.svg)](https://github.com/denko-rb/denko/actions/workflows/build_sam3x.yml)
+[![SAMD Build Satus](https://github.com/denko-rb/denko/actions/workflows/build_samd.yml/badge.svg)](https://github.com/denko-rb/denko/actions/workflows/build_samd.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      | :yellow_heart:  | Due | Native USB port. Tone, and IR Out don't work.
+| ATSAMD21       | :green_heart:   | Zero, M0, M0 Pro | Native USB port
+| RA4M1          | :yellow_heart:  | Uno R4 Minima, Uno R4 WiFi | IR Out and WS2812 unsupported. UART & Wi-Fi untested
+
 ### Arduino Accessories
 
 |    Chip               | Status          | Product          | Notes |
@@ -26,8 +36,9 @@
 | HDG204 + AT32UC3      | :question:      | WiFi Shield      | WiFi for Uno. No hardware to test, but compiles
 | ATWINC1500            | :question:      | WiFi Shield 101  | Same as above, high memory use, Mega only
 
-### Espressif Chips with Built-In WiFi
-[![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)
+### Espressif Chips with Built-In Wi-Fi
+[![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)
 
 |    Chip        | Status          | Board Tested         | Notes |
 | :--------      | :------:        | :---------------     |------ |
@@ -45,12 +56,12 @@
 
 |    Chip        | Status          | Board Tested          | Notes |
 | :--------      | :------:        | :---------------      |------ |
-| RO2040         | :green_heart:   | Raspberry Pi Pico (W) | WiFi only on W version. No WS1812 LED support.
+| RP2040         | :green_heart:   | Raspberry Pi Pico (W) | WiFi only on W version. No WS1812 LED support.
 
 # Single Board Computers
 
 ### Raspberry Pi Single Board Computers
-**Note:** See the [denko-piboard](https://github.com/denko-rb/denko-piboard) extension to this gem. It uses the peripheral classes from this gem, but swaps out `Board` for `PiBoard`, which uses the Raspberry Pi's built-in GPIPO interface. This is still a work-in-progress.
+**Note:** See the [denko-piboard](https://github.com/denko-rb/denko-piboard) extension to this gem. It uses the peripheral classes from this gem, but swaps out `Board` for `PiBoard`, which uses the Raspberry Pi's built-in GPIO interface. This is still a work-in-progress.
 
 |    Chip        | Status          | Products              | Notes |
 | :--------      | :------:        | :---------------      |------ |
@@ -64,114 +75,124 @@
 
 :green_heart: Full support :yellow_heart: Partial support :heart: Planned. No support yet
 
-### Basic GPIO Interface
-
-| Name                  | Status          | Component Class      | Notes |
-| :---------------      | :------:        | :------              | :---- |
-| Digital Out           | :green_heart:   | `DigitalIO::Output`  | -     |
-| Digital In            | :green_heart:   | `DigitalIO::Input`   | 1ms - 128ms (4ms default) listen, poll, or read
-| PWM Out               | :green_heart:   | `PulseIO::PWMOutput` |
-| Analog Out (DAC)      | :green_heart:   | `AnalogIO::Output`   | On SAM3X, SAMD21 and some ESP32
-| Analog In (ADC)       | :green_heart:   | `AnalogIO::Input`    | 1ms - 128ms (16ms default) listen, poll, or read
-| Tone Out (Square Wave)| :green_heart:   | `PulseIO::Buzzer`    | Doesn't work on Due (SAM3X)
+### 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 PWM         | :green_heart:   | H     | See Motor table          | Uses PWM
+| Tone Out (Square Wave)| :green_heart:   | H     | `PulseIO::Buzzer`        | Except SAM3X. Uses PWM
+| I2C                   | :green_heart:   | H     | `I2C::Bus`               | Predetermined pins from IDE
+| I2C Bit Bang          | :heart:         | S     | `I2C::BitBang`           | Any pins
+| SPI                   | :green_heart:   | H     | `SPI::Bus`               | Predetermined pins from IDE
+| SPI Bit Bang          | :green_heart:   | S     | `SPI::BitBang`           | Any pins
+| UART                  | :green_heart:   | H     | `UART::Hardware`         | Except Atmega328, ATmega168, RA4M1
+| UART Bit Bang         | :green_heart:   | S     | `UART::BitBang`          | Only ATmega328, ATmega168
+| Maxim OneWire         | :green_heart:   | S     | `OneWire::Bus`           | No overdrive
+| Infrared Emitter      | :green_heart:   | S     | `PulseIO::IRTransmitter` | Except RA4M1
+| Infrared Receiver     | :heart:         | S     | `PulseIO::IRReceiver`    | Doable with existing library
+| WS2812                | :green_heart:   | S     | See LED table            | Except RP2040
+| ESP32-PCNT            | :heart:         | H     | -                        | Only ESP32. Pulse counter (for encoders)
+| 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.
 
-### Advanced Interfaces
-
-| Name             | Status         | SW/HW     | Component Class          | Notes |
-| :--------------- | :------:       | :-------- | :---------------         |------ |
-| I2C              | :green_heart:  | Hardware  | `I2C::Bus`               | Hardware I2C on predefined pins
-| SPI              | :green_heart:  | Hardware  | `SPI::Bus`               | Hardware SPI on prefedined pins
-| SPI Bit Bang     | :green_heart:  | Software  | `SPI::BitBang`           | Bit Bang SPI on any pins
-| UART             | :green_heart:  | Hardware  | `UART::Hardware`         | R/W support for UART1..3 when available
-| UART Bit Bang    | :green_heart:  | Software  | `UART::BitBang`          | R/W support for a single UART. Only ATmega chips
-| Maxim OneWire    | :green_heart:  | Software  | `OneWire::Bus`           | No overdrive support
-| Infrared Emitter | :green_heart:  | Software  | `PulseIO::IRTransmitter` | Library on Board
-| Infrared Receiver| :heart:        | Software  | `PulseIO::IRReceiver`    | Doable with existing library
-
-### Generic Peripherals
+### Basic Input/Output
 
 | Name             | Status         | Interface    | Component Class            | Notes |
 | :--------------- | :------:       | :--------    | :---------------           |------ |
-| Board EEPROM     | :green_heart:  | Built-In     | `EEPROM::BuiltIn`          | Not all boards have EEPROM
-| Led              | :green_heart:  | Digi/Ana Out | `LED::Base`                |
-| RGBLed           | :green_heart:  | Digi/Ana Out | `LED::RGB`                 |
-| Relay            | :green_heart:  | Digital Out  | `DigitalIO::Relay`         |
-| 7 Segment Display| :yellow_heart: | Digital Out  | `LED::SevenSegment`        | No decimal point
 | Button           | :green_heart:  | Digital In   | `DigitalIO::Button`        |
 | Rotary Encoder   | :green_heart:  | Digital In   | `DigitalIO::RotaryEncoder` | Listens every 1ms
-| PIR Sensor       | :yellow_heart: | Digital In   | `DigitalIO::Input`         | Needs class. HC-SR501 
-| Analog Sensor    | :green_heart:  | Analog In    | `AnalogIO::Sensor`         |
 | Potentiometer    | :green_heart:  | Analog In    | `AnalogIO::Potentiometer`  | Smoothing on by default
-| Piezo Buzzer     | :green_heart:  | Tone Out     | `PulseIO::Buzzer`          | Frequency > 30Hz
-| Input Register   | :green_heart:  | SPI          | `SPI::InputRegister`       | Tested on CD4021B
-| Output Register  | :green_heart:  | SPI          | `SPI::OutputRegister`      | Tested on 74HC595
+| Relay            | :green_heart:  | Digital Out  | `DigitalIO::Relay`         |
 
-**Note:** Most Digital In and Out peripherals can be used seamlessley through Input and Output Registers respectively.
+### LEDs
 
-### Motors / Motor Drivers
-
-| Name                 | Status         | Interface      | Component Class    | Notes |
-| :---------------     | :------:       | :--------      | :---------------   |------ |
-| Servo                | :green_heart:  | PWM + Library  | `Motor::Servo`     | Maximum of 6 on ATmega168, 16 on ESP32 and 12 otherwise
-| L298N                | :green_heart:  | Digi + PWM Out | `Motor::L298`      | H-Bridge DC motor driver
-| A3967                | :green_heart:  | Digital Out    | `Motor::Stepper`   | 1ch microstepper (EasyDriver)
-| PCA9685              | :heart:        | I2C            | `PulseIO::PCA9685` | 16ch 12-bit PWM for servo or 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
+| TM1637             | :heart:            | BitBang SPI       | `LED::TM1637`         | 4x 7 Segment + Colon
+| Neopixel / WS2812B | :yellow_heart:     | Adafruit Library  | `LED::WS2812`         | Not working on RP2040
+| Dotstar / APA102   | :green_heart:      | SPI               | `LED::APA102`         |
 
 ### Displays
 
 | Name                     | Status         | Interface                    | Component Class     | Notes |
 | :---------------         | :------:       | :--------                    | :---------------    |------ |
-| HD44780 LCD              | :green_heart:  | Digital Out, Output Register | `Display::HD44780`  | 
+| HD44780 LCD              | :green_heart:  | Digital Out, Output Register | `Display::HD44780`  |
 | SSD1306 OLED             | :yellow_heart: | I2C                          | `Display::SSD1306`  | 1 font, some graphics
 
-### Addressable LEDs
+### Sound
 
-| Name               | Status             | Interface         | Component Class    | Notes |
-| :---------------   | :------:           | :--------         | :---------------   |------ |
-| Neopixel / WS2812B | :yellow_heart:     | Adafruit Library  | `LED::WS2812`      | Not working on RP2040 |
-| Dotstar / APA102   | :green_heart:      | SPI               | `LED::APA102`      |
+| Name             | Status         | Interface    | Component Class            | Notes |
+| :--------------- | :------:       | :--------    | :---------------           |------ |
+| Piezo Buzzer     | :green_heart:  | Tone Out     | `PulseIO::Buzzer`          | Frequency > 30Hz
+
+### Motors / 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.
+| L298N                | :green_heart:  | Digi + PWM Out | `Motor::L298`      | H-Bridge DC motor driver
+| A3967                | :green_heart:  | Digital Out    | `Motor::Stepper`   | 1ch microstepper (EasyDriver)
+| PCA9685              | :heart:        | I2C            | `PulseIO::PCA9685` | 16ch 12-bit PWM for servo or LED
 
 ### 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 | :heart:        | I2C        | `DigitalIO::PCF8574` | 8ch bi-directional digital I/O
-| ADS1115 ADC      | :heart:        | I2C        | `AnalogIO::ADS1115`  | 15-bit +/- 4ch ADC
-| ADS1118 ADC      | :green_heart:  | SPI        | `AnalogIO::ADS1118`  | 15-bit +/- 4ch ADC, and temperature
+| ADS1100 ADC      | :heart:        | I2C        | `AnalogIO::ADS1100`  | 15-bit +/- 1ch ADC
+| ADS1115 ADC      | :green_heart:  | I2C        | `AnalogIO::ADS1115`  | 15-bit +/- 4ch ADC. Comparator not implemented.
+| ADS1118 ADC      | :green_heart:  | SPI        | `AnalogIO::ADS1118`  | 15-bit +/- 4ch ADC + temperature
 | PCF8591 ADC/DAC  | :heart:        | I2C        | `AnalogIO::PCF8591`  | 4ch ADC + 1ch DAC, 8-bit resolution
+| MCP4725 DAC      | :heart:        | I2C        | `AnalogIO::MCP4275`  | 1ch 12-bit DAC
 
 ### Environmental Sensors
 
 | Name             | Status         | Interface   | Component Class    | Notes |
 | :--------------- | :------:       | :--------   | :---------------   |------ |
-| DHT 11/21/22     | :green_heart:  | Digi In/Out | `Sensor::DHT`      | Temp/RH
 | DS18B20          | :green_heart:  | OneWire     | `Sensor::DS18B20`  | Temp
+| DHT 11/21/22     | :green_heart:  | Digi In/Out | `Sensor::DHT`      | Temp/RH
+| SHT30            | :heart:        | I2C         | `Sensor::SHT30`    | Temp/RH
+| QMP6988          | :heart:        | I2C         | `Sensor::QMP6988`  | Pressure
 | BME280           | :green_heart:  | I2C         | `Sensor::BME280`   | Temp/RH/Press
 | BMP280           | :green_heart:  | I2C         | `Sensor::BMP280`   | Temp/Press
-| HTU21D           | :green_heart:  | I2C         | `Sensor::HTU21D`   | Temp/RH. Locks I2C bus during read. No user register read.
-| HTU31D           | :yellow_heart: | I2C         | `Sensor::HTU31D`   | Temp/RH. No diagnostic read yet.
+| HTU21D           | :green_heart:  | I2C         | `Sensor::HTU21D`   | Temp/RH. User register read not implemented.
+| HTU31D           | :green_heart:  | I2C         | `Sensor::HTU31D`   | Temp/RH. Diagnostic read not implemented.
 | AHT10/15         | :green_heart:  | I2C         | `Sensor::AHT10`    | Temp/RH. Always uses calibrated mode.
-| AHT20/21/25      | :green_heart:  | I2C         | `Sensor::AHT20`    | Temp/RH. Always uses calibrated mode and CRC.
-| MAX31850         | :heart:        | OneWire     | `Sensor::MAX31850` | Thermocouple Amplifier
+| AHT20/21/25      | :green_heart:  | I2C         | `Sensor::AHT20`    | Temp/RH. Always uses calibrated mode + CRC.
 | ENS160           | :heart:        | I2C         | `Sensor::ENS160`   | CO2e/TVOC/AQI
 | AGS02MA          | :heart:        | I2C         | `Sensor::AGS02MA`  | TVOC
+| MAX31850         | :heart:        | OneWire     | `Sensor::MAX31850` | Thermocouple Amplifier
 
 ### Light Sensors
 
-| Name             | Status         | Interface | Component Class   | Notes |
-| :--------------- | :------:       | :-------- | :---------------  |------ |
-| APDS9960         | :heart:        | I2C       | `Sensor::APDS9960`| Proximity, RGB, Gesture
+| Name             | Status         | Interface    | Component Class    | Notes |
+| :--------------- | :------:       | :--------    | :---------------   |------ |
+| BH1750           | :heart:        | Digital In   | `Sensor::BH1750`   | Ambient Light
+| HC-SR501         | :yellow_heart: | Digital In   | `DigitalIO::Input` | PIR. Needs class: `Sensor::HC-SR501`
+| AS312            | :heart:        | I2C          | `Sensor::AS312`    | PIR
+| APDS9960         | :heart:        | I2C          | `Sensor::APDS9960` | Proximity, RGB, Gesture
 
 ### Distance Sensors
 
-| Name             | Status         | Interface | Component Class    | Notes |
-| :--------------- | :------:       | :-------- | :---------------   |------ |
-| HC-SR04          | :heart:        | Direct    | `Sensor::HCSR04`   | Ultrasonic, 20-4000mm
-| VL53L0X          | :heart:        | I2C       | `Sensor::VL53L0X`  | Laser, 30 - 1000mm
-| GP2Y0E03         | :heart:        | I2C       | `Sensor::GP2Y0E03` | Infrared, 40 - 500mm
+| Name             | Status         | Interface    | Component Class    | Notes |
+| :--------------- | :------:       | :--------    | :---------------   |------ |
+| HC-SR04          | :heart:        | Digi In/Out  | `Sensor::HCSR04`   | Ultrasonic, 20-4000mm
+| RCWL-9620        | :heart:        | I2C          | `Sensor::RCWL9260` | Ultrasonic, 20-4500mm
+| VL53L0X          | :heart:        | I2C          | `Sensor::VL53L0X`  | Laser, 30 - 1000mm
+| GP2Y0E03         | :heart:        | I2C          | `Sensor::GP2Y0E03` | Infrared, 40 - 500mm
 
 ### Motion Sensors
 
@@ -180,16 +201,18 @@ Polling and reading follow a call and response pattern.
 | ADXL345          | :heart:        | I2C       | `Sensor::ADXL345`  | 3-axis Accelerometer
 | IT3205           | :heart:        | I2C       | `Sensor::IT3205`   | 3-axis Gyroscope
 | HMC5883L         | :heart:        | I2C       | `Sensor::HMC5883L` | 3-axis Compass
+| MPU6886          | :heart:        | I2C       | `Sensor::MPU6886`  | 3-axis Gyro + Accel
 
-### Real Time Clock
+### Real Time Clocks
 
 | Name             | Status         | Interface | Component Class   | Notes |
 | :--------------- | :------:       | :-------- | :---------------  |------ |
 | DS1302           | :heart:        | I2C       | `RTC::DS1302`     |
-| DS3221           | :yellow_heart: | I2C       | `RTC::DS3231`     | Only set and get time implemented
+| DS3231           | :green_heart:  | I2C       | `RTC::DS3231`     | Alarms not implemented
 
 ### Miscellaneous
 
 | Name             | Status         | Interface  | Component Class      | Notes |
 | :--------------- | :------:       | :--------  | :---------------     |------ |
+| Board EEPROM     | :green_heart:  | Built-In   | `EEPROM::BuiltIn`    | Arduino ARM boards have no EEPROM
 | MFRC522          | :heart:        | SPI/I2C    | `DigitalIO::MFRC522` | RFID tag reader / writer

data/README.md

@@ -1,8 +1,8 @@
-# Denko 0.13.0 [![Test Status](https://github.com/denko-rb/denko/actions/workflows/ruby.yml/badge.svg)](https://github.com/denko-rb/denko/actions/workflows/ruby.yml)
+# Denko 0.13.1 [![Test Status](https://github.com/denko-rb/denko/actions/workflows/ruby.yml/badge.svg)](https://github.com/denko-rb/denko/actions/workflows/ruby.yml)
 ### Ruby Meets Microcontrollers
 Denko gives you a high-level Ruby interface to low-level hardware, without writing microcontroller code. Use LEDs, buttons, sensors and more, just as easily as any Ruby object:
 
-````ruby
+```ruby
 led.blink 0.5
 
 lcd.print "Hello World!"
@@ -12,66 +12,62 @@ reading = sensor.read
 button.down do
   puts "Button pressed!"
 end
-````
-
-Denko doesn't run Ruby on the microcontroller (see the [mruby-dino](#mruby) project). It runs a C++ firmware that exposes as much low-level I/O as possible, so we can use it in Ruby. It becomes a peripheral for your computer.
+```
 
-High-level abstraction in Ruby makes hardware classes easy to implement, with intuitive interfaces. They multitask a single core microcontroller, with thread-safe state, and callbacks for inputs, but no "task" priority. If you need more I/O, integration is seamless. Connect another board and instantiate it in Ruby.
+Denko doesn't run Ruby on the microcontroller (see [mruby-denko](#mruby-denko)). It runs custom Arduino firmware to expose its I/O interfaces over a socket. You run Ruby on your computer and talk to it. The microcontroller, and anything connected to it, map directly to Ruby objects. You get to think about your hardware and appplication logic, not everything in between.
 
-Each peripheral connected to your microcontroller(s) maps to a Ruby object you can use directly. You get to think about your hardware and appplication logic, not everything in between.
+High-level abstraction in Ruby makes hardware classes easy to implement, with intuitive interfaces. They multitask a single core microcontroller, with thread-safe state, and callbacks for inputs. If you need more I/O, integration is seamless; connect another board and instantiate it in Ruby.
 
 ### Supported Hardware
 
-See a full list of supported mircocontroller platforms, interfaces, and peripherals [here](HARDWARE.md).
+Full list of supported mircocontroller platforms, interfaces, and peripherals is located [here](HARDWARE.md).
+
+##### denko-piboard
+There's an add-on  in development, [denko-piboard](https://github.com/denko-rb/denko-piboard), which supports the Raspberry Pi's built in GPIO pins, as `Denko::PiBoard`, class-compatible with `Denko::Board`. Connect peripherals directly to the Pi, with no microcontroller between, then use the peripheral classes from this gem.
+
+##### mruby-denko
+A solo Raspberry Pi (or other small SBC + microcontroller) is a great standalone setup if your project needs the compute power anyway, but what if you don't? Why not run Ruby on the microcontroller itself? 
+
+That's the goal of [mruby-denko](https://github.com/denko-rb/mruby-denko): write mruby on the ESP32, using peripheral classes as close to this gem as possible. Still early in development, so limited features, but already usable.
 
 ## Getting Started
 
-**Note:** If using Ruby in WSL on Windows, you can follow the Mac/Linux instructions, but it is not recommended. Serial (COM port) forwarding isn't currently working on WSL2, which would make it impossible to communicate with the microcontroller. There are workarounds, and you might get it working by switching to WSL1, but the [RubyInstaller for Windows](https://rubyinstaller.org/) and Arduino IDE are recommended instead.
+**Note:** If using Windows, you can follow the Mac/Linux instructions in WSL, but it is not recommended. Serial (COM port) forwarding isn't working on WSL2, which means you can't communicate with the board. There are workarounds, and it might work on WSL1, but the [RubyInstaller for Windows](https://rubyinstaller.org/) and Arduino IDE are recommended instead. A Linux virtual machine with USB passthrough works too.
 
 #### 1. Install the Gem
 ```shell
 gem install denko
 ```
 
-Before using the microcontroller in Ruby, we need to flash it with the denko firmware (or "sketch" in Arduino lingo). This is needed **once** for each board, but future denko versions may need reflashing to add functionality.
-
 #### 2. Install the Arduino IDE OR CLI
 
 Get the Arduino IDE [here](http://arduino.cc/en/Main/Software) for a graphical interface (recommended for Windows), or use the command line interface from [here](https://github.com/arduino/arduino-cli/releases), or Homebrew.
 
 **CLI Installation with Homebrew on Mac or Linux:**
-````shell
+```shell
 brew update
 brew install arduino-cli
-````
+```
 
 #### 3. Install Arduino Dependencies
-Denko uses Arduino cores, which add support for microcontrollers, and a few libraries. Install only the ones for your microcontroller, or install everything. There are no conflcits. Instructions for supported microcontrollers:
+Denko uses Arduino cores, which support different microcontrollers, and a few libraries. Install only the ones for your microcontroller, or install everything. There are no conflcits. Instructions:
   * [Install Dependencies in IDE](DEPS_IDE.md) 
   * [Install Dependencies in CLI](DEPS_CLI.md) 
 
 #### 4. Generate the Arduino Sketch
 The `denko` command is included with the gem. It will make the Arduino sketch folder for you, and configure it.
 
-**For ATmega boards, Serial over USB:** (Arduino Uno, Nano, Mega, Leonardo, Micro)
-```shell
-denko sketch serial
-````
-
-**For ESP8266, Serial over USB:**
+**Example for ESP32 target on both serial and Wi-Fi:**
 ```shell
-denko sketch serial --target esp8266
-````
-
-**For ESP8266 or ESP32 over WiFi (2.4Ghz and DHCP Only):**
-```shell
-denko sketch wifi --target esp8266 --ssid YOUR_SSID --password YOUR_PASSWORD
+denko sketch serial --target esp32
 denko sketch wifi --target esp32 --ssid YOUR_SSID --password YOUR_PASSWORD
-````
 
-**Note:** [This example](examples/connection/tcp.rb) shows how to connect to a board with a TCP socket, but the WiFi & Ethernet sketches fall back to the serial interface when no TCP client is connected.
+# For more options
+denko targets
+```
+**Note:** Boards flashed with a Wi-Fi or Ethernet sketch will [listen for a TCP connection](examples/connection/tcp.rb), but fall back to Serial when there is none active.
 
-#### 5a) IDE Flashing
+#### 5a. IDE Flashing
 
 * Connect the board to your computer with a USB cable.
 * Open the .ino file inside your sketch folder with the IDE.
@@ -81,46 +77,47 @@ denko sketch wifi --target esp32 --ssid YOUR_SSID --password YOUR_PASSWORD
 **Troubleshooting:**
 * If your serial port is in the list, but the board is wrong, select the serial port anyway, then you will be asked to manually select a board.
 * If your board doesn't show up at all, make sure it is connected properly. Try disconnecting and reconnecting, use a different USB port or cable, or press the reset button after plugging it in.
+* Some boards may be in a state where you have to hold their "boot" button while cycling power (reconnect or reset) for them to enter firmware update mode. Eg. Raspberry Pi Pico, ESP32-S2/S3.
 
-#### 5b) CLI Flashing
+#### 5b. CLI Flashing
 
 * The path output by `denko sketch` earlier is your sketch folder. Keep it handy.
 * Connect the board to your computer with a USB cable.
 * Check if the CLI recognizes it:
 
-````shell
+```shell
 arduino-cli board list
-````
+```
   
 * Using the Port and FQBN (Fully Qualified Board Name) shown, compile and upload the sketch:
-````shell
+```shell
 arduino-cli compile -b YOUR_FQBN YOUR_SKETCH_FOLDER
 arduino-cli upload -v -p YOUR_PORT -b YOUR_FQBN YOUR_SKETCH_FOLDER
-````
+```
 
 **Troubleshooting:**
 * Follow the same steps as the IDE method above. List all FQBNs using:
-````shell
+```shell
 arduino-cli board listall
-````
+```
 
-#### 6)  Test It
+#### 6. Test It
 
-Most boards have a regular LED on-board. Test it with the [blink](examples/led/builtin_blink.rb) example. If you have an on-board WS2812 LED, use the [WS2812 blink](examples/led/ws2812_builtin_blink.rb) example instead. If it starts blinking, you're ready for Ruby!
+Most boards have a regular LED on-board. Test it with the [blink](examples/led/builtin_blink.rb) example. If you have an on-board WS2812 LED (Neopixel), use the [WS2812 blink](examples/led/ws2812_builtin_blink.rb) example instead. If it starts blinking, you're ready for Ruby!
 
 ## Examples and Tutorials
 
 #### 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 button or momentary switch
-  * 1 potentiometer (any value)
-  * 1 external RGB LED (4 legs common cathode, not a Neopixel or individually addressable)
-  * 1 external LED (any color, or use one color from the RGB LED)
-  * Current limiting resistors for LEDs
-  * Breadboard
-  * Jumper wires
+  - 1 compatible microcontroller (see [supported hardware](HARDWARE.md))
+  - 1 button or momentary switch
+  - 1 potentiometer (any value)
+  - 1 external RGB LED (4 legs common cathode, not a Neopixel or individually addressable)
+  - 1 external LED (any color, or use one color from the RGB LED)
+  - Current limiting resistors for LEDs
+  - Breadboard
+  - Jumper wires
   
   **Tip:** Kits are a cost-effective way to get started. They will almost certainly include these parts, plus more, getting you well beyond the tutorial.
 
@@ -131,22 +128,14 @@ Most boards have a regular LED on-board. Test it with the [blink](examples/led/b
 
 ####  More Examples
 
-- Try [Getting Started with Arduino and Denko](http://tutorials.jumpstartlab.com/projects/arduino/introducing_arduino.html) from [Jumpstart Lab](http://jumpstartlab.com) (_ignore old install instructions_).
-- An example [rails app](https://github.com/denko-rb/denko_rails_example)  using Denko and Pusher.
-- For a Sinatra example, look at the [site](https://github.com/denko-rb/denko_cannon) used to shoot the cannon at RubyConf2012.
+**Note:** This gem was renamed from `dino` to `denko`. Some of these examples use the old name.
+
+- Try [Getting Started with Arduino and Dino](http://tutorials.jumpstartlab.com/projects/arduino/introducing_arduino.html) from [Jumpstart Lab](http://jumpstartlab.com) (_ignore old install instructions_).
+- An example [rails app](https://github.com/austinbv/dino_rails_example) using Dino and Pusher.
+- For a Sinatra example, look at the [site](https://github.com/austinbv/dino_cannon) used to shoot the cannon at RubyConf2012.
 
 ## Explanatory Talks
 
 - "Arduino the Ruby Way" at RubyConf 2012
   - [Video by ConFreaks](https://www.youtube.com/watch?v=oUIor6GK-qA)
   - [Slides on SpeakerDeck](https://speakerdeck.com/austinbv/arduino-the-ruby-way)
-  
-## mruby Port
-
-A single-board computer plus microcontroller can be a great standalone solution, especially if your project needs the computer anyway. For example, a Raspberry Pi Zero and Arduino Nano combo, running CRuby, Denko and other software.
-
-But what if you want to be _really_ small? Building on the [mruby-esp32](https://github.com/mruby-esp32/mruby-esp32) project, Denko is being ported to run directly on the ESP32 here: [mruby-dino-template](https://github.com/denko-rb/mruby-dino-template).
-
-## denko-piboard
-
-There's an add-on for this gem, [denko-piboard](https://github.com/denko-rb/denko-piboard), in early development, which adds support for the Raspberry Pi's built in GPIO interface as a class-compatible "board". This allows you to connect peripherals directly to the Pi, without a microcontroller, and use the denko peripherals classes as-is.

data/benchmarks/i2c_ssd1306_refresh.rb

@@ -0,0 +1,74 @@
+#
+# Repeatedly writes filled and empty frames to the OLED
+# Calculates frames per second. Higher is better.
+#
+# RESULTS:
+# July 6 2023 | i7 8700k CPU | CRuby 3.2.1 | 100 frames | 1 Mhz I2C frequency | Average of 3 runs
+#
+#   Arduino Uno R3      :  5.3 fps (ATmega16u2 UART bridge @ 115200, no I2C level shifter)
+#   Arduino Uno R3      :  7.1 fps (ATmega16u2 UART bridge @ 230400, no I2C level shifter)
+#   Arduino Leonardo    : 12.9 fps (native USB, no I2C level shifter)
+#   Arduino Due         : 43.0 fps (native USB)
+#   Arduino Due         :  7.9 fps (programming USB @ 115200)
+#   Arduino Zero        : 28.6 fps (native USB)
+#   Arduino Zero        :  9.4 fps (programming USB @ 115200)
+#   Arduino Zero        : 13.6 fps (programming USB @ 230400)
+#   ESP8266 (Node MCU)  :  9.9 fps (Silicon Labs UART bridge @ 115200)
+#   ESP8266 (Node MCU)  : 19.7 fps (Silicon Labs UART bridge @ 230400)
+#   ESP32 V1            :  9.8 fps (Silicon Labs UART bridge @ 115200)
+#   ESP32 V1            : 19.4 fps (Silicon Labs UART bridge @ 230400)
+#   ESP32-S3            : 58.8 fps (native USB)
+#   Raspberry Pi Pico W : 36.4 fps (native USB)
+#
+# July 15 2023 | i7 8700k CPU | CRuby 3.2.1 | 100 frames | 1 Mhz I2C frequency | Average of 3 runs
+#
+#   Arduino Uno R4      :  7.5 fps (native USB @ 115200, 32-byte I2C limit, no I2C level shifter)
+#   Arduino Uno R4      :  7.8 fps (native USB @ 230400, 32-byte I2C limit, no I2C level shifter)
+#
+require 'bundler/setup'
+require 'denko'
+
+# Settings
+# Must match speed in the sketch for UART briges. Doesn't matter for native USB.
+BAUD_RATE = 115_200
+FRAME_COUNT = 100
+# Request 1 Mhz I2C frequency. Wire libraries will fall back to fastest available speed.
+I2C_FREQUENCY = 1_000_000
+# Use :SDA0 for RP2040
+I2C_PIN = :SDA
+
+# Setup
+board = Denko::Board.new(Denko::Connection::Serial.new(baud: BAUD_RATE))
+bus = Denko::I2C::Bus.new(board: board, pin: I2C_PIN)
+oled = Denko::Display::SSD1306.new(bus: bus, rotate: true, i2c_frequency: I2C_FREQUENCY)
+canvas = oled.canvas
+
+# Intro
+canvas.print "SSD1306 Benchmark"
+oled.draw
+sleep 1
+
+# Run
+start = Time.now
+(FRAME_COUNT / 2).times do
+  canvas.fill
+  oled.draw
+  canvas.clear
+  oled.draw
+end
+board.finish_write
+finish = Time.now
+
+# Calculate results
+fps = FRAME_COUNT / (finish - start)
+
+# Print to terminal
+puts "SSD1306 benchmark result: #{fps.round(2)} fps"
+puts
+
+# Print to screen
+canvas.clear
+canvas.text_cursor = [0,0]
+canvas.print "#{fps.round(2)} fps"
+oled.draw
+board.finish_write

data/examples/analog_io/ads1115.rb

@@ -0,0 +1,57 @@
+#
+# Example using an ADS1115 ADC over the I2C bus.
+#
+require 'bundler/setup'
+require 'denko'
+
+board = Denko::Board.new(Denko::Connection::Serial.new)
+bus = Denko::I2C::Bus.new(board: board, pin: :SDA)
+ads = Denko::AnalogIO::ADS1115.new(bus: bus)
+
+# Helper method so readings look nice.
+def print_reading(name, raw, voltage)
+  print "#{Time.now.strftime '%Y-%m-%d %H:%M:%S'} - "
+  print "#{name.rjust(18, " ")} | "
+  print "Raw: #{raw.to_s.rjust(6, " ")} | "
+  print "Voltage: "
+  print ("%.10f" % voltage).rjust(13, " ")
+  puts " V"
+end
+
+#
+# Use the ADS1115 directly by writing values to its config registers.
+# ADS1115#read automatically waits for conversion time and gets the 16-bit reading.
+# See datasheet for register bitmaps.
+#
+# Note: This is the only way to use continuous mode. Subcomponents always use one-shot.
+#
+ads.read([0b11000001, 0b10001011]) do |reading|
+  voltage = reading * 0.0001875
+  print_reading("Direct", reading, voltage)
+end
+
+#
+# Or use its BoardProxy interface, adding subcomponents as if it were a Board.
+# The key adc: can substitute for board: when intializing AnalogIO::Input.
+# Gain and sample rate bitmasks can be found in the datasheet.
+#
+# Input on pin 0, with pin 1 as differential negative input, and 6.144 V full range.
+diff_input = Denko::AnalogIO::Input.new(adc: ads, pin: 0, negative_pin: 1, gain: 0b000)
+
+# Input on pin 2 with no negative input (single ended), and 1.024V full range.
+# Ths one uses a 8 SPS rate, essentially 16x oversampling compared to the default 128.
+single_input = Denko::AnalogIO::Input.new(adc: ads, pin: 2, gain: 0b011, sample_rate: 0b000)
+
+# Poll the differential input every second.
+diff_input.poll(1) do |reading|
+  voltage = reading * diff_input.volts_per_bit
+  print_reading("Differential A1-A0", reading, voltage)
+end
+
+# Poll the single ended input every 2 seconds.
+single_input.poll(2) do |reading|
+  voltage = reading * single_input.volts_per_bit
+  print_reading("Single A2-GN", reading, voltage)
+end
+
+sleep