Reference for the Ruby API available on Harucom.

Contents

Harucom API

Harucom comes with libraries for screen drawing, keyboard input, Japanese input, and the peripherals on the board.

DVI Module

A low-level API for controlling DVI output and drawing on screen. It has two display modes: text mode (106 columns x 37 rows) and graphics mode (640x480 / 320x240).

DVI.set_mode(DVI::GRAPHICS_MODE)
DVI::Graphics.fill_circle(160, 120, 50, 0xE0)
DVI::Graphics.commit

For complex screen drawing, the P5 Drawing Library provides a convenient wrapper.

P5 Drawing Library

A drawing library that provides a Processing-like interface. It wraps DVI::Graphics and offers an easy-to-use API for fill and stroke colors, coordinate transforms, blend modes, and more.

require "p5"
p5 = P5.new
p5.fill(p5.color(255, 0, 0))
p5.circle(160, 120, 50)
p5.commit

Keyboard

An API for handling input from a USB keyboard. You can get key input through the global variable $keyboard.

key = $keyboard.read_char
case key
when Keyboard::CTRL_Q then break
when Keyboard::ENTER  then puts "Enter"
end

InputMethod (Japanese Input)

An API for using Japanese input from your own program. Pass keys through the global variable $ime and take the committed text back out.

text += $ime.take_committed if $ime.process(key) == :commit

Board (Board Peripherals)

The peripherals on the Harucom Board live under the Board module. Load the one you need with require.

Board::PWMAudio (Audio)

Playing sound through PWM audio, and building sounds with Synth. An 8-channel mixer plays waveforms and WAV or QOA samples.

require "board/pwm_audio"
audio = Board::PWMAudio.new
audio.beep(0, Board::PWMAudio::A4, 200)

Board::Pad (Button Input)

Reading the eight buttons on the board.

require "board/pad"
pad = Board::Pad.new(Board::PAD0_PIN)
puts "up" if pad.read.up?

Board::DMX (DMX Module Control)

Sending DMX512 to control stage lighting.

require "board/dmx"
dmx = Board::DMX.new
dmx.start
dmx[6] = 255

PicoRuby Libraries

Harucom runs on PicoRuby.

These libraries are built in. Where there is a link, the PicoRuby or mruby reference behind it has the details.

Filesystem

Class Description
File (PicoRuby) File reading and writing
File::Stat File size and timestamps
Dir (PicoRuby) Directory operations
VFS Mounting filesystems
Littlefs The flash filesystem 
File.open("/data.txt", "r") { |f| f.read(256) }
File.open("/data.txt", "w") { |f| f.write("hello") }
Dir.mkdir("/mydir")

For where files belong, see File I/O.

Data Formats

Class Description
JSON JSON reading and writing
YAML YAML reading and writing
Marshal Ruby object serialization
Base64 Base64 encoding and decoding
Base16 Hex string conversion

Hardware

Class Description
GPIO GPIO pin control
ADC Reading analog input
UART Serial communication New in 2.0
PWM PWM output New in 2.0
Watchdog Watchdog timer

For what each pin is wired to, see Harucom Board.

System

Class Description
Machine Uptime, sleep, reboot, and the board’s unique ID
Time Time retrieval and manipulation
Task Creating and controlling tasks
Sandbox Running Ruby code in a task of its own
PicoRubyVM Inspecting memory use
RNG Random numbers
ENV Environment variables (holding the settings)
Logger Logging
Editor Text buffers, and display widths that count full-width characters

Built-in Classes

Class Description
String Strings
Array Arrays
Hash Hashes
Integer Integers
Float Floating-point numbers
Rational Exact fractions New in 2.0
Math Trigonometry, square roots, logarithms
Range Ranges
Symbol Symbols
Enumerable map, select, and the rest of the iteration methods
Comparable Ordering
Proc Blocks and lambdas
ObjectSpace Walking the live objects
Regexp Regular expressions
Data Building classes that hold values

Kernel

The Kernel module holds the common methods, and they can be called without naming a class. The ones inherited from mruby — tap, then and the like — are in the mruby reference.

puts(*args)

puts "hello"

Writes to $stdout and ends with a newline. On Harucom that is the screen.

print(*args)

Writes to $stdout. It does not add a newline.

p(*args)

Writes inspect of each argument, one per line. It returns the argument when given one and the array when given several, so it can sit in the middle of an expression.

gets

Reads a line from $stdin, or returns nil when there is nothing to read.

getc

Reads a character from $stdin, or returns nil when there is nothing to read.

sleep(sec)

sleep 1      # one second
sleep 0.5    # half a second

Waits the given number of seconds, fractions included. Other tasks keep running while it waits, so playback does not stop.

Called with no argument, the task stays stopped until something wakes it. A negative number raises ArgumentError.

sleep_ms(ms)

sleep_ms 100

Waits the given number of milliseconds. Like sleep, other tasks keep running.

usleep(usec)

Waits the given number of microseconds.

require(name)

require "p5"

Loads a library, searching $LOAD_PATH (["/lib"] by default), so a script in /lib can be loaded by name alone. It returns false and does nothing when the library is already loaded.

load(path)

Unlike require, loads the file again even if it is already loaded. Useful when trying out edits to a library.

exit(status = 0)

Ends the program. It raises SystemExit, so calling it inside an app returns to IRB.