Denko 0.13.0 Test Status

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:

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 mruby-denko for that). It runs 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

Full list of supported mircocontroller platforms, interfaces, and peripherals is located here.

denko-piboard

There's an add-on for this gem in development, 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 same 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. Write mruby on the ESP32, using peripheral classes as close to this gem as possible. Still early in development, and limited features, but already working.

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 and Arduino IDE are recommended instead.

1. Install the Gem

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 versions may need reflashing to add functionality.

2. Install the Arduino IDE OR CLI

Get the Arduino IDE here for a graphical interface (recommended for Windows), or use the command line interface from here, or Homebrew.

CLI Installation with Homebrew on Mac or Linux:

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:

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)

denko sketch serial

For ESP8266, Serial over USB:

denko sketch serial --target esp8266

For ESP8266 or ESP32 over WiFi (2.4Ghz and DHCP Only):

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 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:
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 example. If you have an on-board WS2812 LED (Neopixel), use the WS2812 blink example instead. If it starts blinking, you're ready for Ruby!

Examples and Tutorials

Tutorial

  • Here 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)
    • 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 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

Explanatory Talks