denko 0.13.0

data/examples/advanced/ssd1306_time_temp_rh.rb

@@ -0,0 +1,48 @@
+#
+# This example polls an HTU21D (temp/humidity sensor) in the background.
+# The main thread refreshes an SSD1306 OLED ~20 times per second,
+# showing the latest temperature and humidity values, and current time.
+# Both devices are conected to the same I2C bus.
+#
+require 'bundler/setup'
+require 'denko'
+
+board = Denko::Board.new(Denko::Connection::Serial.new)
+i2c = Denko::I2C::Bus.new(board: board, pin: :SDA)
+
+# Get temperature and humidity every second.
+htu21d = Denko::Sensor::HTU21D.new(bus: i2c)
+htu21d.temperature.poll(1)
+htu21d.humidity.poll(1)
+
+oled = Denko::Display::SSD1306.new(bus: i2c, rotate: true)
+canvas = oled.canvas
+last_refresh = Time.now
+
+loop do
+  elapsed = Time.now - last_refresh
+
+  # Aim for 20 fps.
+  if elapsed > 0.049
+    canvas.clear
+
+    canvas.text_cursor = [0,0]
+    canvas.print "Time:  #{Time.now.strftime("%H:%M:%S.%L")}"
+
+    if htu21d[:temperature]
+      canvas.text_cursor = [0,8]
+      canvas.print "Temp:     " + ('%.3f' % htu21d[:temperature]).rjust(7, " ") + " C"
+    end
+
+    if htu21d[:humidity]
+      canvas.text_cursor = [0,16]
+      canvas.print "Humidity: " + ('%.3f' % htu21d[:humidity]).rjust(7, " ") + " %"
+    end
+
+    # Only refresh the area in use.
+    oled.draw(0, 127, 0, 24)
+    last_refresh = Time.now
+  else
+    sleep 0.001
+  end
+end

data/examples/analog_io/ads1118.rb

@@ -0,0 +1,74 @@
+#
+# Example using an ADS1118 ADC over the SPI bus.
+#
+require 'bundler/setup'
+require 'denko'
+
+board = Denko::Board.new(Denko::Connection::Serial.new)
+
+# Connect the ADS1118 pins to the board's default SPI pins.
+bus = Denko::SPI::Bus.new(board: board)
+
+# Or use a 2-way bit-bang SPI bus on any pins.
+# SPI_BIT_BANG_PINS   = { clock: 13, input: 12, output: 11 }
+# bus = Denko::SPI::BitBang.new(board: board, pins: SPI_BIT_BANG_PINS)
+
+# Connect chip select/enable pin of the ADS1118 to pin 9.
+ads1118 = Denko::AnalogIO::ADS1118.new(bus: bus, pin: 9)
+
+# 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(12, " ")} | "
+  print "Raw: #{raw.to_s.rjust(6, " ")} | "
+  print "Voltage: "
+  print ("%.10f" % voltage).rjust(13, " ")
+  puts " V"
+end
+
+#
+# Read the ADS1118 internal temperature sensor.
+# This always uses the 128 SPS mode, and there is no polling method for it.
+# 
+temperature = ads1118.temperature_read
+puts "ADS1118 Temperature: #{temperature} \xC2\xB0C"
+puts
+
+#
+# Use the ADS1118 directly by writing values to its config registers.
+# ADS1118#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.
+#
+ads1118.read([0b10000001, 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: ads1118, 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: ads1118, 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", 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", reading, voltage)
+end
+
+sleep

data/examples/analog_io/dac_loopback.rb

@@ -0,0 +1,32 @@
+#
+# Example looping the Arduino Zero's DAC back into one of its ADC pins.
+#
+require 'bundler/setup'
+require 'denko'
+
+#
+# For the Arduino Zero: 'DAC0' = 'A0' = GPIO14.
+# For the ESP32 V1:     'DAC0' = GPIO25, 'DAC1' = GPIO26, `ADC1_4` = 32
+#
+# Connect DAC_PIN TO ADC_PIN with a jumper to test.
+#
+DAC_PIN = 'DAC0'
+ADC_PIN = 'A5'
+
+board = Denko::Board.new(Denko::Connection::Serial.new)
+dac = Denko::AnalogIO::Output.new(pin: DAC_PIN, board: board)
+adc = Denko::AnalogIO::Input.new(pin: ADC_PIN, board: board)
+
+#
+# Read values should be approximately 4x the written values, since Board#new tries to
+# set output resolution at 8-bits and input to 10-bits. Not configurable on all chips.
+# Scale may be off but, readings should still be proportional.
+#
+[0, 32, 64, 128, 192, 255].each do |output_value|
+  dac.write output_value
+  sleep 1
+  loopback_value = adc.read
+  puts "ADC reads: #{loopback_value} when DAC writes: #{output_value}"
+end
+
+board.finish_write

data/examples/analog_io/input.rb

@@ -0,0 +1,52 @@
+#
+# This is an example of how to use the sensor class
+# You must register data callbacks and have the main thread
+# sleep or in someway keep running or your program
+# will exit before any callbacks can be called
+#
+require 'bundler/setup'
+require 'denko'
+
+board = Denko::Board.new(Denko::Connection::Serial.new)
+sensor = Denko::AnalogIO::Sensor.new(pin: 'A0', board: board)
+
+# Single read with block as callback. Blocks main thread.
+# Callback fires only once then is removed automatically.
+sensor.read { |value| puts "#{Time.now} Single read: #{value}" }
+
+# Poll the sensor every 1 second with block as callback. Does not block main thread.
+# Callback fires every time data is received until #stop is called.
+sensor.poll(1) { |value| puts "#{Time.now} Polling: #{value}" }
+sleep 5
+
+# Stop polling. Automatically removes the callback from the #poll block.
+sensor.stop
+
+# Continuous listen with block as callback. Fires every time data is received until #stop is called.
+sensor.listen { |value| puts "#{Time.now} Listening: #{value}" }
+sleep 0.5
+
+# Stop listening. Automatically removes the callback from the #listen block.
+sensor.stop
+
+# Add a persistent callback.
+sensor.on_data { |value| puts "#{Time.now} Persistent callback: #{value}" }
+
+# Add a callback with a custom key.
+sensor.on_data(:test) { |value| puts "#{Time.now} Keyed callback: #{value}"}
+
+# Single read again. Block given fires only once. Callbacks added with #on_data fire also.
+sensor.read { |value| puts "#{Time.now} Single read again: #{value}" }
+
+# Continuous listen. Block fires each time. Callbacks added with #on_data continue to fire.
+sensor.listen { |value| puts "#{Time.now } Listening again: #{value}" }
+sleep 0.5
+
+# Stop listening. Automatically removes the callback from the #listen block.
+sensor.stop
+
+# Remove callbacks keyed with :test.
+sensor.remove_callbacks(:test)
+
+# Remove all callbacks.
+sensor.remove_callbacks

data/examples/connection/tcp.rb

@@ -0,0 +1,34 @@
+require 'bundler/setup'
+require 'denko'
+#
+# This example shows how to use denko when connecting to a board via TCP.
+# This applies to the WiFi and Ethernet sketches, or serial sketch + ser2net.
+# Port number defaults to 3466 (denko), but may be given as a second argument.
+# It must correspond to the listening port set when the board was flashed.
+#
+connection = Denko::Connection::TCP.new("192.168.0.77", 3466)
+# connection = Denko::Connection::TCP.new("127.0.0.1")
+# connection =  Denko::Connection::TCP.new("192.168.1.2", 3466)
+#
+board = Denko::Board.new(connection)
+led = Denko::Led.new(pin: 13, board: board)
+
+[:on, :off].cycle do |switch|
+  led.send(switch)
+  sleep 0.5
+end
+#
+# ser2net can be used to simulate a TCP interface from a board running denko serial.
+# It serves the serial interface over a TCP port from the machine running ser2net.
+#
+# Example ser2net command for an Arduino UNO connected to a Mac:
+# ser2net -u -C "3466:raw:0:/dev/cu.usbmodem621:115200"
+#
+# Tell denko to connect to the IP address of the Mac, at port 3466.
+# Note: ser2net should be used in raw TCP mode, not telnet mode (more common).
+#
+# Replace /dev/cu.usbmodem621 with your denko serial device.
+# Arduino UNOs should be something like /dev/ttyACM0 under Linux.
+#
+# http://sourceforge.net/projects/ser2net/ for more info on installing and configuring ser2net.
+#

data/examples/digital_io/rotary_encoder.rb

@@ -0,0 +1,26 @@
+#
+# Example of a smiple rotary encoder polling at ~1ms.
+#
+# WARNING: This method is not precise at all. Please do not use it for anything
+# that requires all steps to be read for precise positioning or high speed.
+#
+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, reads each pin every 1ms
+                                              steps_per_revolution: 30    # default
+
+# Reverse direction if needed.
+# encoder.reverse
+
+# Reset angle and steps to 0.
+encoder.reset
+
+encoder.add_callback do |state|
+  puts "Encoder moved #{state[:change]} steps | CW step count: #{state[:steps]} | Current angle: #{state[:angle]}\xC2\xB0"
+end
+
+sleep

data/examples/display/hd44780.rb

@@ -0,0 +1,39 @@
+#
+# This example writes "Hello World!" in the display
+#
+require 'bundler/setup'
+require 'denko'
+
+board = Denko::Board.new(Denko::Connection::Serial.new)
+lcd = Denko::Display::HD44780.new  board: board,
+                                  pins: { rs: 8, enable: 9, d4: 4, d5: 5, d6: 6, d7: 7 },
+                                  cols: 16,
+                                  rows: 2
+
+# Bitmap for a custom character. 5 bits wide x 8 high.
+# Useful for generating these: https://omerk.github.io/lcdchargen/
+heart = [	0b00000,
+        	0b00000,
+        	0b01010,
+        	0b11111,
+        	0b11111,
+        	0b01110,
+        	0b00100,
+        	0b00000 ]
+                  
+# Define the character in CGRAM address 2. 0-7 are usable.
+lcd.create_char(2, heart)
+
+# Need to call home/clear/set_cursor so we go back to writing DDRAM.
+lcd.home
+
+# End the first line with the heart by writing its CGRAM address.
+lcd.print "Hello World!   "
+lcd.write(2)
+
+# Display a clock on second line, updating approximately every second.
+loop do
+  lcd.move_to 0,1
+  lcd.print(Time.now.strftime("%I:%M:%S"))
+  sleep 1
+end

data/examples/display/ssd1306.rb

@@ -0,0 +1,40 @@
+#
+# Example using an SSD1306 driven OLED screen over I2C.
+#
+require 'bundler/setup'
+require 'denko'
+
+board = Denko::Board.new(Denko::Connection::Serial.new)
+
+#
+# Default pins for the I2C0 (first) interface on most chips:
+#
+# ATmega 328p:       SDA = 'A4'  SCL = 'A5' - Arduino Uno, Nano
+# ATmega 32u4:       SDA =   2   SCL =   3  - Arduino Leonardo, Pro Micro
+# ATmega1280 / 2560: SDA =  20   SCL =  21  - Arduino Mega
+# SAM3X8E:           SDA =  20   SCL =  21  - Arduino Due
+# SAMD21G18:         SDA =  20   SCL =  21  - Arduino Zero, M0, M0 Pro
+# ESP8266:           SDA =   4   SCL =   5
+# ESP32:             SDA =  21   SCL =  22
+# RP2040:            SDA =   4   SCL =   5  - Raspberry Pi Pico (W)
+#
+# Only give the SDA pin of the I2C bus. SCL (clock) pin must be 
+# connected for it to work, but we don't need to control it.
+#
+bus = Denko::I2C::Bus.new(board: board, pin: 'A4')
+oled = Denko::Display::SSD1306.new(bus: bus, rotate: true)
+canvas = oled.canvas
+
+# Draw some text on the OLED's canvas (a Ruby memory buffer).
+canvas.text_cursor = [27,60]
+canvas.print("Hello World!")
+
+# Add some shapes to the canvas.
+baseline = 40
+canvas.rectangle(10, baseline, 30, -30)
+canvas.circle(66, baseline - 15, 15)
+canvas.triangle(87, baseline, 117, baseline, 102, baseline - 30)
+
+# Send the canvas to the OLED's graphics RAM so it shows.
+oled.draw
+board.finish_write

data/examples/display/ssd1306_s2_pico.rb

@@ -0,0 +1,29 @@
+#
+# Example using the SSD1306 OLED built into the LOLIN ES32-S2 PICO
+#
+require 'bundler/setup'
+require 'denko'
+
+board = Denko::Board.new(Denko::Connection::Serial.new)
+
+# The OLED's reset pin on this board isn't tied high. Do it manually.
+reset = Denko::DigitalIO::Output.new(board: board, pin: 18)
+reset.high
+
+bus = Denko::I2C::Bus.new(board: board, pin: :SDA)
+oled = Denko::Display::SSD1306.new(bus: bus, width: 128, height: 32)
+canvas = oled.canvas
+
+# Draw some text on the OLED's canvas (a Ruby memory buffer).
+canvas.text_cursor = [27,31]
+canvas.print("Hello World!")
+
+# Add some shapes to the canvas.
+baseline = 15
+canvas.rectangle(10, baseline, 15, -15)
+canvas.circle(66, baseline - 7, 8)
+canvas.triangle(102, baseline, 118, baseline, 110, baseline - 15)
+
+# Send the canvas to the OLED's graphics RAM so it shows.
+oled.draw
+board.finish_write

data/examples/eeprom/built_in.rb

@@ -0,0 +1,32 @@
+#
+# Example showing how to load, modify and save the board's EEPROM.
+#
+require 'bundler/setup'
+require 'denko'
+
+board = Denko::Board.new(Denko::Connection::Serial.new)
+
+# Initialization automatically gets all EEPROM data from the board.
+# eeprom = Denko::EEPROM::BuiltIn(board: board)
+eeprom = board.eeprom
+
+# EEPROM size reported by the board.
+puts "EEPROM Size: #{eeprom.length} bytes"
+
+# Write values like an array.
+eeprom[0] = 128
+eeprom[1] = 127
+
+# Changes do not save to the board automatically.
+# Call #save to write to the board, and automatically reload from it.
+eeprom.save
+
+# Read values like an array.
+puts "Address 0 contains: #{eeprom[0]}"
+
+# Enumerate like an array.
+eeprom.each_with_index do |byte, address|
+  if address == 1
+    puts "Address #{address} contains #{byte}"
+  end
+end

data/examples/i2c/search.rb

@@ -0,0 +1,53 @@
+#
+# Example that shows the default I2C bus pins, and addresses of any
+# devices connected to the bus.
+#
+require 'bundler/setup'
+require 'denko'
+
+# Method to let the user set I2C pins.
+def enter_pins
+  puts  "Please manually specify I2C pins..."
+  print "I2C SDA pin: "; sda = gets
+  print "I2C SCL pin: "; scl = gets
+  puts
+  [sda.to_i, scl.to_i]
+end
+
+board = Denko::Board.new(Denko::Connection::Serial.new)
+
+# If no board map, ask user to set pins manually.
+unless board.map
+  puts "Error: Pin map not available for this board"
+  sda, scl = enter_pins
+
+# Else get defaults from map.
+else
+  sda = board.map[:SDA] || board.map[:SDA0]
+  scl = board.map[:SCL] || board.map[:SCL0]
+
+  # If not in map, ask user to set manually.
+  unless sda && scl
+    puts "Error: I2C pins not found in this board's pin map"
+    sda, scl = enter_pins
+  end
+end
+
+puts "Using I2C interface on pins #{sda} (SDA) and #{scl} (SCL)"
+puts
+
+bus = Denko::I2C::Bus.new(board: board, pin: sda)
+bus.search
+
+if bus.found_devices.empty?
+  puts "No devices found on I2C bus"
+else
+  puts "I2C device addresses found:"
+  bus.found_devices.each do |address|
+    # Print as hexadecimal.
+    puts "0x#{address.to_s(16).upcase}"
+  end
+end
+
+puts
+board.finish_write

data/examples/led/apa102_bounce.rb

@@ -0,0 +1,33 @@
+#
+# Walk a single pixel along the length of an APA102 strip and back,
+# changing color each time it returns to position 0.
+#
+require 'bundler/setup'
+require 'denko'
+
+RED    = [255, 0, 0]
+GREEN  = [0, 255, 0]
+BLUE   = [0, 0, 255]
+WHITE  = [255, 255, 255]
+COLORS = [RED, GREEN, BLUE, WHITE]
+PIXELS = 8
+
+# Move along the strip and back, one pixel at a time.
+positions = (0..PIXELS-1).to_a + (1..PIXELS-2).to_a.reverse
+
+board = Denko::Board.new(Denko::Connection::Serial.new)
+
+# Use the default hardware SPI bus.
+bus = Denko::SPI::Bus.new(board: board)
+strip = Denko::LED::APA102.new(bus: bus, length: PIXELS)
+
+loop do
+  COLORS.each do |color|
+    positions.each do |index|
+      strip.clear
+      strip[index] = color
+      strip.show
+      sleep 0.05
+    end
+  end
+end

data/examples/led/apa102_breathe.rb

@@ -0,0 +1,45 @@
+#
+# Walk a single pixel along the length of an APA102 strip and back,
+# changing color each time it returns to position 0.
+#
+require 'bundler/setup'
+require 'denko'
+
+RED    = [255, 0, 0]
+GREEN  = [0, 255, 0]
+BLUE   = [0, 0, 255]
+WHITE  = [255, 255, 255]
+COLORS = [RED, GREEN, BLUE, WHITE]
+PIXELS = 3
+
+# Get all the brightness values as an array.
+brightness_steps = (0..31).to_a
+
+board = Denko::Board.new(Denko::Connection::Serial.new)
+
+# Use the default hardware SPI bus.
+bus = Denko::SPI::Bus.new(board: board)
+strip = Denko::LED::APA102.new(bus: bus, length: PIXELS)
+
+# Test global brightness control first.
+strip[0] = RED
+strip[1] = GREEN
+strip[2] = BLUE
+
+# Fade up from 0 brightness then back down.
+(brightness_steps + brightness_steps.reverse).each do |value|
+  strip.brightness = value
+  strip.show
+  sleep 0.05
+end
+
+# Test per-pixel brightness by fading different pixels different directions.
+loop do
+  (brightness_steps + brightness_steps.reverse).each do |value|
+    strip[0] = RED   +  [value]
+    strip[1] = GREEN +  [31 - value]
+    strip[2] = BLUE  +  [value]
+    strip.show
+    sleep 0.1
+  end
+end

data/examples/led/builtin_blink.rb

@@ -0,0 +1,12 @@
+#
+# Blink example for standard built-in LEDs named :LED_BUILTIN
+#
+require 'bundler/setup'
+require 'denko'
+
+board = Denko::Board.new(Denko::Connection::Serial.new)
+led = Denko::LED.new(board: board, pin: :LED_BUILTIN)
+
+led.blink 0.5
+
+sleep

data/examples/led/seven_segment_char_echo.rb

@@ -0,0 +1,15 @@
+#
+# This is an example of how to use the ssd class
+#
+require 'bundler/setup'
+require 'denko'
+
+board = Denko::Board.new(Denko::Connection::Serial.new)
+ssd   = Denko::LED::SevenSegment.new board: board,
+                                    pins:  { cathode: 10, a: 3, b: 4, c: 5, d: 6, e: 7, f: 8, g: 9 }
+
+# Turn off the ssd on exit
+trap("SIGINT") { exit !ssd.off }
+
+# Display each new line on the ssd
+loop { ssd.display(gets.chomp) }

data/examples/led/ws2812_bounce.rb

@@ -0,0 +1,32 @@
+#
+# Walk a single pixel along the length of a WS2812 strip and back,
+# changing color each time it returns to position 0.
+#
+require 'bundler/setup'
+require 'denko'
+
+RED    = [255, 0, 0]
+GREEN  = [0, 255, 0]
+BLUE   = [0, 0, 255]
+WHITE  = [255, 255, 255]
+COLORS = [RED, GREEN, BLUE, WHITE]
+
+WS2812_PIN = 4
+PIXELS = 8
+
+# Move along the strip and back, one pixel at a time.
+positions = (0..PIXELS-1).to_a + (1..PIXELS-2).to_a.reverse
+
+board = Denko::Board.new(Denko::Connection::Serial.new)
+strip = Denko::LED::WS2812.new(board: board, pin: WS2812_PIN, length: PIXELS)
+
+loop do
+  COLORS.each do |color|
+    positions.each do |index|
+      strip.clear
+      strip[index] = color
+      strip.show
+      sleep 0.05
+    end
+  end
+end

data/examples/led/ws2812_builtin_blink.rb

@@ -0,0 +1,21 @@
+#
+# Blink example for the LOLIN ESP32 S3 or C3, or any board where
+# :LED_BUILTIN is the data pin for a single on-board WS2812.
+#
+require 'bundler/setup'
+require 'denko'
+
+WHITE = [255, 255, 255]
+OFF = [0, 0, 0]
+
+board = Denko::Board.new(Denko::Connection::Serial.new)
+strip = Denko::LED::WS2812.new(board: board, pin: :LED_BUILTIN, length: 1)
+
+loop do
+  strip[0] = WHITE
+  strip.show
+  sleep 0.5
+  strip[0] = OFF
+  strip.show
+  sleep 0.5
+end

data/examples/motor/l298.rb

@@ -0,0 +1,43 @@
+#
+# Example driving a DC motor with a L298 H-Bridge driver.
+#
+require 'bundler/setup'
+require 'denko'
+board = Denko::Board.new(Denko::Connection::Serial.new)
+
+# This is only 1 channel of the driver. Make a new object for each channel.
+motor = Denko::Motor::L298.new board: board, pins: {direction1: 8, direction2: 9, enable: 10}
+
+# Off without braking (initial state).
+# motor.off
+# motor.idle
+
+# Go forward at half speed for a while.
+motor.forward board.pwm_high / 2
+sleep 2
+
+# Change direction.
+motor.reverse board.pwm_high / 2
+sleep 2
+
+# Speed up without changing direction.
+motor.speed = board.pwm_high
+sleep 2
+
+# Brake to stop quickly.
+motor.brake
+sleep 1
+
+# Change from brake to forward, but 0 speed.
+motor.forward 0
+sleep 1
+
+# Gradually speed up.
+(1..20).each do |step|
+  sleep 0.5
+  motor.speed = (board.pwm_high * (step / 20.0)).round
+end
+
+# Turn it off.
+motor.off
+board.finish_write