denko 0.13.0

data/DEPS_IDE.md

@@ -0,0 +1,120 @@
+### Install Arduino Dependencies for Denko (IDE)
+
+### Installing Cores
+
+Some microcontroller platforms require board manager cores that do not come with the IDE. To install a core:
+  * Open the Preferences window of the IDE, and find "Additional boards manager URLS:". Click the button next to it.
+  * In the editor that opens, paste the given URL on a new line at the end (if it doesn't already exist).
+  * Confirm and exit Preferences. Wait for the IDE to finish downloading indexes from the new URL.
+  * Click on Tools > Board > Board Manager.
+  * Search for the platform you are installing by name, and click Install, optionally selecting a version.
+   
+### Installing Libraries
+
+All platforms will require libraries to be installed. To install a library do the following:
+  * Click on Tools > Manage Libraries.
+  * Search for the library you are installing by name, and click Install, optionally selecting a version.
+
+### Platforms:
+
+**Note:** Always install the latest version of a package unless its version number is specified
+
+**Install Everything:**
+  * Board Manager URLs:
+    ````
+    https://arduino.esp8266.com/stable/package_esp8266com_index.json
+    https://raw.githubusercontent.com/espressif/arduino-esp32/gh-pages/package_esp32_index.json
+    https://github.com/earlephilhower/arduino-pico/releases/download/global/package_rp2040_index.json
+    ````
+  * Boards:
+    ````
+    Arduino megaAVR Boards
+    Arduino SAM Boards (32-bits ARM Cortex-M3)
+    Arduino SAMD Boards (32-bits ARM Cortex-M0+)
+    ESP8266 Boards
+    ESP32 Boards    
+    ````    
+  * Libraries:
+    ````
+    Servo                      by Michael Margolis, Arduino
+    Ethernet                   by Various
+    WiFi                       by Arduino
+    IRremote         @ v4.0.0  by shirriff, z3to, ArminJo
+    IRremoteESP82666 @ v2.8.4  by David Conran, Sebastien Warin
+    ESP32Servo                 by Kevin Harrington, John K. Bennett
+    Adafruit NeoPixel          by Adafruit
+    ````
+
+**AVR-based Arduinos & Clones Only:**
+  * Boards:
+    ````
+    Arduino megaAVR Boards (only for Atmega4809 / Nano Every)
+    ````    
+  * Libraries:
+    ````
+    Servo                      by Michael Margolis, Arduino
+    Ethernet                   by Various
+    WiFi                       by Arduino
+    IRremote         @ v4.0.0  by shirriff, z3to, ArminJo
+    Adafruit NeoPixel          by Adafruit
+    ````
+    
+**ARM-based Arduinos & Clones Only:**
+  * Boards:
+    ````
+    Arduino SAM Boards (32-bits ARM Cortex-M3)
+    Arduino SAMD Boards (32-bits ARM Cortex-M0+)
+    ````    
+  * Libraries:
+    ````
+    Servo                      by Michael Margolis, Arduino
+    Ethernet                   by Various
+    WiFi                       by Arduino
+    IRremote         @ v4.0.0  by shirriff, z3to, ArminJo
+    Adafruit NeoPixel          by Adafruit
+    ````
+
+**ESP8266 Only:**
+  * Board Manager URLs:
+    ````
+    https://arduino.esp8266.com/stable/package_esp8266com_index.json
+    ````
+  * Boards:
+    ````
+    ESP8266 Boards
+    ````    
+  * Libraries:
+    ````
+    IRremoteESP82666 @ v2.8.4  by David Conran, Sebastien Warin
+    Adafruit NeoPixel          by Adafruit
+    ````
+
+**ESP32 Only:**
+  * Board Manager URLs:
+    ````
+    https://raw.githubusercontent.com/espressif/arduino-esp32/gh-pages/package_esp32_index.json
+    ````
+  * Boards (latest version unless specified):
+    ````
+    ESP32 Boards    
+    ````    
+  * Libraries (latest version unless specified):
+    ````
+    IRremoteESP82666 @ v2.8.4  by David Conran, Sebastien Warin
+    ESP32Servo                 by Kevin Harrington, John K. Bennett
+    Adafruit NeoPixel          by Adafruit
+    ````
+    
+**RP2040 Only:**
+  * Board Manager URLs:
+    ````
+    https://github.com/earlephilhower/arduino-pico/releases/download/global/package_rp2040_index.json
+    ````
+  * Boards:
+    ````
+    Raspberry Pi Pico/RP2040   
+    ````    
+  * Libraries:
+    ````
+    IRremote         @ v4.0.0  by shirriff, z3to, ArminJo
+    ````

data/Gemfile

@@ -0,0 +1,4 @@
+source 'https://rubygems.org'
+
+# Specify your gem's dependencies in denko.gemspec
+gemspec

data/HARDWARE.md

@@ -0,0 +1,195 @@
+# Microcontrollers
+
+: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)
+
+|    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  |
+| 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.
+
+### Arduino Accessories
+
+|    Chip               | Status          | Product          | Notes |
+| :--------             | :------:        | :--------------- |------ |
+| Wiznet W5100/5500     | :green_heart:   | Ethernet Shield  | Wired Ethernet for Uno/Mega pin-compatibles
+| 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)
+
+|    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
+| ESP32-S3       | :green_heart:   | LOLIN S3 V1.0.0      | Native USB
+| ESP32-C3       | :green_heart:   | LOLIN C3 Mini V2.1.0 | Native USB
+
+**Note:** For ESP32 chips using native USB, 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.
+
+### 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 |
+| :--------      | :------:        | :---------------      |------ |
+| RO2040         | :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.
+
+|    Chip        | Status          | Products              | Notes |
+| :--------      | :------:        | :---------------      |------ |
+| BCM2835        | :yellow_heart:  | Pi 1, Pi Zero (W)     |
+| BCM2836/7      | :question:      | Pi 2                  |
+| BCM2837A0/B0   | :yellow_heart:  | Pi 3                  |
+| BCM2711        | :question:      | Pi 4, Pi 400          |
+| BCM2710A1      | :question:      | Pi Zero 2W            |
+
+# Peripherals
+
+: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)
+
+**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
+
+| 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
+
+**Note:** Most Digital In and Out peripherals can be used seamlessley through Input and Output Registers respectively.
+
+### 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
+
+### Displays
+
+| Name                     | Status         | Interface                    | Component Class     | Notes |
+| :---------------         | :------:       | :--------                    | :---------------    |------ |
+| HD44780 LCD              | :green_heart:  | Digital Out, Output Register | `Display::HD44780`  | 
+| SSD1306 OLED             | :yellow_heart: | I2C                          | `Display::SSD1306`  | 1 font, some graphics
+
+### Addressable LEDs
+
+| 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`      |
+
+### I/O Expansion
+
+| Name             | Status         | Interface  | Component Class      | Notes |
+| :--------------- | :------:       | :--------  | :---------------     |------ |
+| 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
+| PCF8591 ADC/DAC  | :heart:        | I2C        | `AnalogIO::PCF8591`  | 4ch ADC + 1ch DAC, 8-bit resolution
+
+### 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
+| 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.
+| 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
+| ENS160           | :heart:        | I2C         | `Sensor::ENS160`   | CO2e/TVOC/AQI
+| AGS02MA          | :heart:        | I2C         | `Sensor::AGS02MA`  | TVOC
+
+### Light Sensors
+
+| Name             | Status         | Interface | Component Class   | Notes |
+| :--------------- | :------:       | :-------- | :---------------  |------ |
+| 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
+
+### Motion Sensors
+
+| Name             | Status         | Interface | Component Class    | Notes |
+| :--------------- | :------:       | :-------- | :---------------   |------ |
+| ADXL345          | :heart:        | I2C       | `Sensor::ADXL345`  | 3-axis Accelerometer
+| IT3205           | :heart:        | I2C       | `Sensor::IT3205`   | 3-axis Gyroscope
+| HMC5883L         | :heart:        | I2C       | `Sensor::HMC5883L` | 3-axis Compass
+
+### Real Time Clock
+
+| Name             | Status         | Interface | Component Class   | Notes |
+| :--------------- | :------:       | :-------- | :---------------  |------ |
+| DS1302           | :heart:        | I2C       | `RTC::DS1302`     |
+| DS3221           | :yellow_heart: | I2C       | `RTC::DS3231`     | Only set and get time implemented
+
+### Miscellaneous
+
+| Name             | Status         | Interface  | Component Class      | Notes |
+| :--------------- | :------:       | :--------  | :---------------     |------ |
+| MFRC522          | :heart:        | SPI/I2C    | `DigitalIO::MFRC522` | RFID tag reader / writer

data/LICENSE

@@ -0,0 +1,22 @@
+Copyright (c) 2012 Austin
+
+MIT License
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,152 @@
+# 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)
+### 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
+led.blink 0.5
+
+lcd.print "Hello World!"
+
+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.
+
+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.
+
+### Supported Hardware
+
+See a full list of supported mircocontroller platforms, interfaces, and peripherals [here](HARDWARE.md).
+
+## 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.
+
+#### 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
+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:
+  * [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:**
+```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 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.
+
+#### 5a) IDE Flashing
+
+* Connect the board to your computer with a USB cable.
+* Open the .ino file inside your sketch folder with the IDE.
+* Open the dropdown menu at the top of the IDE window, and select your board.
+* Press the Upload :arrow_right: button. This will compile the sketch, and flash it to the board.
+
+**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.
+
+#### 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
+arduino-cli board list
+````
+  
+* Using the Port and FQBN (Fully Qualified Board Name) shown, compile and upload the sketch:
+````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
+arduino-cli board listall
+````
+
+#### 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!
+
+## 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
+  
+  **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.
+
+#### Included Examples
+
+- The [examples](examples) folder contains at least one example per supported peripheral, demonstrating its interface, and a few that use multiple peripherals together.
+- Each example should incldue a wiring diagram alongside its code (still incomplete).
+
+####  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.
+
+## 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/Rakefile

@@ -0,0 +1,11 @@
+#!/usr/bin/env rake
+require "bundler/gem_tasks"
+require 'rake/testtask'
+
+task :default => [:test]
+Rake::TestTask.new do |t|
+  t.libs << "lib"
+  t.libs << "test"
+  t.warning = false
+  t.test_files = FileList['test/**/*_test.rb']
+end

data/bin/denko

@@ -0,0 +1,22 @@
+#!/usr/bin/env ruby
+# encoding: UTF-8
+
+# Find myself
+require "pathname"
+bin_file = Pathname.new(__FILE__).realpath
+
+# Find everything else
+src_dir = bin_file.to_s.chomp("/bin/denko") + "/src"
+lib_dir = bin_file.to_s.chomp("/bin/denko") + "/lib"
+cli_dir = bin_file.to_s.chomp("/bin/denko") + "/lib/denko_cli"
+working_dir = Dir.pwd
+
+# Make sure denko is in the load path
+$:.unshift lib_dir
+
+# Start the CLI
+require "denko_cli"
+DenkoCLI.start working_dir: working_dir,
+              src_dir: src_dir,
+              cli_dir: cli_dir,
+              args: ARGV

data/build

@@ -0,0 +1,27 @@
+#!/usr/bin/env ruby
+# encoding: UTF-8
+
+require "pathname"
+require "yaml"
+
+# Find myself.
+build_file = Pathname.new(__FILE__).realpath
+
+# Find the target details.
+target_file =  build_file.to_s.chomp("build") + "target.yml"
+target = YAML.load_file(target_file)
+
+# Generate sketch.
+bin_file = build_file.to_s.chomp("build") + "bin/denko"
+sketch_folder = `#{bin_file} sketch serial --target #{target["name"]}`
+
+# Compile it.
+compile_successful = system "arduino-cli compile -b #{target["fqbn"]} #{sketch_folder}"
+
+# Upload it.
+if compile_successful
+  system "arduino-cli upload -v -p #{target["port"]} -b #{target["fqbn"]} #{sketch_folder}"
+end
+
+# Delete it.
+system "rm -r #{sketch_folder}"

data/denko.gemspec

@@ -0,0 +1,47 @@
+# -*- encoding: utf-8 -*-
+require File.expand_path('../lib/denko/version', __FILE__)
+
+Gem::Specification.new do |gem|
+  gem.authors       = ["vickash, Austinbv"]
+  gem.email         = ["mail@vickash.com"]
+  gem.description   = %q{GPIO library for Ruby}
+  gem.summary       = %q{Use GPIO, I2C, SPI, UART and more on a connected microcontroller}
+  gem.homepage      = 'https://github.com/denko-rb/denko'
+  gem.files         = `git ls-files`.split($\)
+  gem.licenses      = ['MIT']
+
+  # Copy full submodule contents into the gem when building.
+  # Credit:
+  # https://gist.github.com/mattconnolly/5875987#file-gem-with-git-submodules-gemspec
+  #
+  # get an array of submodule dirs by executing 'pwd' inside each submodule
+  gem_dir = File.expand_path(File.dirname(__FILE__)) + "/"
+  `git submodule --quiet foreach pwd`.split($\).each do |submodule_path|
+    # Fix submodule paths on Windows.    
+    if RUBY_PLATFORM.match(/mswin|mingw/i)
+      submodule_path = `cygpath -m #{submodule_path}`.strip
+    end
+
+    Dir.chdir(submodule_path) do
+      submodule_relative_path = submodule_path.sub gem_dir, ""
+      # issue git ls-files in submodule's directory and
+      # prepend the submodule path to create absolute file paths
+      `git ls-files`.split($\).each do |filename|
+        gem.files << "#{submodule_relative_path}/#{filename}"
+      end
+    end
+  end
+
+  gem.test_files    = gem.files.grep(%r{^(test|spec|features)/})
+  gem.name          = "denko"
+  gem.require_paths = ["lib"]
+  gem.version       = Denko::VERSION
+  gem.executables   = ["denko"]
+
+  gem.add_dependency 'rubyserial',  '~> 0.6'
+  gem.add_dependency 'bcd',         '~> 1'
+
+  gem.add_development_dependency 'rake',      '~> 13'
+  gem.add_development_dependency 'minitest',  '~> 5'
+  gem.add_development_dependency 'simplecov', '~> 0.22'
+end

data/examples/advanced/rotary_encoder_mac_volume.rb

@@ -0,0 +1,48 @@
+#
+# Example using a rotary encoder to control audio output volume on a Mac.
+#
+require 'bundler/setup'
+require 'denko'
+
+board = Denko::Board.new(Denko::Connection::Serial.new)
+encoder = Denko::DigitalIO::RotaryEncoder.new  board: board,
+                                              pins:{ clock: 4, data: 5 },
+                                              divider: 1,                # (default) read approx every divider ms
+                                              steps_per_revolution: 30   # (default)
+
+# Set up a pseudo terminal with osascript (AppleScript) in interactive mode.
+# Calling a separate script each update is too slow.
+class AppleVolumeWrapper
+  require 'pty'
+  require 'expect'
+
+  def initialize
+    @in, @out, pid = PTY.spawn('osascript -i')
+    @in.expect(/>> /) # Terminal ready.
+  end
+
+  def get
+    @out.write("output volume of (get volume settings)\r\n")
+    @in.expect(/=> (\d+)\r\n/)[1].to_i
+  end
+
+  def set(value)
+    @out.write("set volume output volume #{value}\r\n")
+    @in.expect(/>> /)
+  end
+end
+
+volume = AppleVolumeWrapper.new
+puts "Current volume: #{volume.get}%"
+
+encoder.add_callback do |update|
+  # Increase by 2% for every step so it responds faster.
+  value = (volume.get + (update[:change] * 2))
+  value = 0 if value < 0
+  value = 100 if value > 100
+  volume.set(value)
+  current_volume = volume.get
+  puts "Current volume: #{current_volume}%"
+end
+
+sleep