denko

Program real-life electronics in Ruby. LEDs, buttons, sensors (and more) work just like any Ruby object:

led.blink 0.5

lcd.text "Hello World!"

reading = sensor.read

button.down { puts "Button pressed!" }
button.listen

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":

• Flash a supported microcontroller 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

• Install 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

• Download mruby and/or mirb binaries from the 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 drivers are implemented only in this gem, and the source files are used by all stacks
• That makes the examples folder 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

• Peripherals
• Microcontrollers
• Single Board Computers
• Milk-V Duo Boards

Note: On Windows you can follow the Mac/Linux instructions in WSL, but it isn't 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 and Arduino IDE are recommended instead. A Linux virtual machine with USB passthrough works too.

gem install denko

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

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
• Install Dependencies in CLI

The denko command is included with the gem. It will make the Arduino sketch folder for you, and configure it.

Example for ESP32 target on both serial and Wi-Fi:

denko sketch serial --target esp32
denko sketch wifi --target esp32 --ssid YOUR_SSID --password YOUR_PASSWORD

# For more options
denko targets

Note: Boards flashed with a Wi-Fi or Ethernet sketch will listen for a TCP connection, but fall back to Serial when there is none active.

• 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 ➡️ 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 can 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 can get into 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.

• 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:

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:

arduino-cli board listall

Most boards have a regular LED on-board. Test 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!

• 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
  • 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 good way to get started. They include even more, and get you well beyond the tutorial.

• The examples folder contains at least one example per peripheral, demonstrating its interface.
• Each example should incldue a wiring diagram alongside its code (still incomplete).