Scripting language API~
Euphonium contains a berry-lang scripting language that can be used to tweak the system for your needs. The following page documents the internal API used in all scripts. Feel free to check euphonium/scripts
to see how this is used internally.
globals
~
Global utilities
Commands~
Command | Signature | Supported platforms |
---|---|---|
sleep_ms |
(milliseconds: int) -> void . Pauses execution for given amount of milliseconds. |
All |
core
~
Manages euphonium's core functionality, mostly shared utils.
Implemented by Core.cpp
Commands~
Command | Signature | Supported platforms |
---|---|---|
core.start_plugin |
(pluginName: string, pluginConfig: map) -> void Starts given plugin's audio thread with following configuration. |
All |
core.platform |
() -> string .Returns platform on which euphonium is currently running. Result being either esp32 or desktop |
All |
core.version |
() -> string .Returns current version of the system. Example result: 0.0.14 |
All |
FormContext
~
Class used in plugins that handles UI creation and interaction in the web-ui.
Implemented by form_ctx.be
Class methods~
All of the following methods are available on the FormContext
class instance.
Command | Signature | Supported platforms |
---|---|---|
text_field |
(key: string, config: FieldConfig) -> void Adds a text field to the configuration. See FieldConfig below for parameters. |
All |
select_field |
(key: string, config: FieldConfig) -> void Adds a option select / picker field to the configuration. See FieldConfig below for parameters. |
All |
checkbox_field |
(key: string, config: FieldConfig) -> void Adds a checkbox to the configuration. See FieldConfig below for parameters. |
All |
create_group |
(key: string, config: [key: string, label: string]) -> void Adds a new config group to the configuration. |
All |
Interface FieldConfig
~
Field | Signature | Field type |
---|---|---|
label |
string Configuration field's label visible over the control in the interface. |
All |
hint |
string Used as a hint in the text field. |
text_field |
default |
string Field's default value. |
All |
values |
list All of select field's available values. |
select_field |
group |
string Group that a given field belongs to, previously registered with create_group |
All |
http
~
Allows for registering endpoints on the internal HTTP server.
Implemented by http.be
and HTTPModule.cpp
Commands~
Command | Signature | Supported platforms |
---|---|---|
http.handle |
(method: string, path: string, response_handler: [(request) -> void]) -> void Register a new HTTP endpoint under given path . Response handler is a method that takes HTTPRequest as a parameter. See examples below for usage. |
All |
http.emit_event |
(type: string, body: map) -> void .Broadcasts a server-side event to all connected devices. body will be serialized into json string. |
All |
Object HTTPRequest
~
Command | Signature | Supported platforms |
---|---|---|
write_json |
(body: map, status: int) -> void .Writes a response json to given connection. Body is passed as a map of data to be serialized into json. Status is the HTTP status code of the response. |
All |
write_text |
(body: string, status: int) -> void .Writes the response as text/plain . |
All |
json_body |
() -> map Parses given request's body string into json and returns it as map |
All |
query_params |
() -> map Returns map of parsed query parameters of the given request. |
All |
url_params |
() -> map Returns map of parsed url parameters of the given request. |
All |
Example~
HTTP server usage
Handle simple GET and return "Hello, world!"
http.handle('GET', '/hello_world', def (request)
request.write_text("Hello world!", 200)
end)
http.handle('POST', '/create_cat', def (request)
if request.json_body() == nil
http.write_text("No body", request['connection'], 400)
else
# Parse json body
var parsed_body = request.json_body()
# Create response
var response = { 'name': parsed_body['name'], 'age': 3 }
request.write_json(response, 200)
end
end)
playback
~
Manages playback state of the system.
Commands~
Command | Signature | Supported platforms |
---|---|---|
playback.set_eq |
(low: int, mid: int, high: int) -> void .If EqualizerProcessor is enabled, this changes the eq's settings. 1 point on the scale means 3 db. Defaults to 0, 0, 0 (no eq). |
All |
playback.set_pause |
(paused: boolean) -> void .Pauses the playback state. This also triggers a pause event. |
All |
playback.empty_buffers |
() -> void .Empties internal audio buffers of the system. Call this during playback changes / stop pause. |
All |
playback.soft_volume |
(volume: int) -> void Changes the system's software volume. Volume is between 0 and 100 . |
All |
euphonium
~
Global euphonium instance object. Handles main events, and keeps a state of plugin registry.
Commands~
Command | Signature | Supported platforms |
---|---|---|
euphonium.register_plugin |
(plugin: Plugin) -> void Registers a new euphonium plugin. plugin is a instance of plugin to register in the system. |
All |
input
~
ESP32 specific
Allows registration of callbacks for input events. Useful for adding buttons, encoders and such.
Commands~
Command | Signature | Supported platforms |
---|---|---|
hooks
~
Hooks allow to run different instructions during certain boot stages. Used for example to pull up an IO during boot.
Commands~
Command | Signature | Supported platforms |
---|---|---|
hooks.add_handler |
(bootstage: int, handler: [() -> void]) -> void Register a new hook. Different bootstage values described below. |
All |
enum hooks.BOOTSTAGE
~
Command | Description | Supported platforms |
---|---|---|
hooks.ON_INIT |
Called earliest during boot, after scripting VM init. | All |
hooks.POST_SYSTEM |
Called after all core logic has been initialized, before plugins startup. | All |
hooks.POST_PLUGIN |
Called after all plugins have been initialized | All |
hooks.AP_INIT |
Called after AP network has been initialized. | esp32 |
hooks.WIFI_INIT |
Called after WiFi has been initialized. | esp32 |
Example~
Sample hook that runs after boot
Define I2S configuration, output 256 x MCLK clock on GPIO0.
hooks.add_handler(hooks.ON_INIT, def ()
print("On boot called!")
end)
i2s
~
Controls I2S bus. Mainly used for DAC support.
Implemented by I2SDriver.cpp
Commands~
Command | Signature | Supported platforms |
---|---|---|
i2s.install |
(configuration: I2SConfig) -> void Installs I2S driver. See below for description of I2SConfig structure. |
esp32 |
i2s.delete |
() -> void .Uninstalls the current I2S driver. |
esp32 |
i2s.set_expand |
(src: int, dst: int) -> void .Enables expand from src bits to dst bits in driver write. Useful for 32bit DAC support. |
esp32 |
i2s.disable_expand |
() -> void .Disables bits expand. |
esp32 |
Object I2SConfig
~
Field | Description |
---|---|
sample_rate |
int Defines sample rate for the incoming data signal. WARNING - Sample rate is only initial, will be further changed in case od dynamic sample rate |
bits_per_sample |
int Bits per sample for incoming data. |
comm_format |
one of I2S_CHANNEL_FMT_RIGHT_LEFT , I2S_CHANNEL_FMT_ALL_RIGHT , I2S_CHANNEL_FMT_ALL_LEFT or I2S_CHANNEL_FMT_ONLY_RIGHT |
channel_format |
one of I2S_COMM_FORMAT_I2S , I2S_COMM_FORMAT_MSB , I2S_COMM_FORMAT_PCM_SHORT or I2S_COMM_FORMAT_PCM_LONG |
mclk |
int if defined and larger than 0, outputs given mclk on GPIO0. |
Example~
Sample driver configuration
Define I2S configuration, output 256 x MCLK clock on GPIO0.
var config = I2SConfig()
config.sample_rate = 44100
config.bits_per_sample = 16
config.comm_format = I2S_CHANNEL_FMT_RIGHT_LEFT
config.channel_format = I2S_COMM_FORMAT_I2S
config.mclk = 256 * 44100
i2s.install(config)
i2c
~
Controls I2C bus on supported platforms. Mainly used in different drivers.
Implemented by I2CDriver.cpp
Commands~
Command | Signature | Supported platforms |
---|---|---|
i2c.install |
(sda: int, scl: int) -> void Installs I2C driver under given pins. |
esp32 |
i2c.detect |
(addr:int) -> bool .Tries to detect device under given addr. Returns true if device found. |
esp32 |
i2c.read_bytes |
(addr:int, reg:int, size:int) -> int or nil .Read a value of 1..4 bytes from address addr and register reg. Returns nil if no response. |
esp32 |
i2c.write_bytes |
(addr:int, reg:int, val:bytes) -> nil Writes the val bytes sequence as bytes() to address addr register reg. |
esp32 |
i2c.read |
(addr:int, reg:int, size:int) -> int or nil .Reads a singular bytes from a given register. |
esp32 |
i2c.write |
(addr:int, reg:int, val:int) -> nil Writes a singular byte to a given register. |
esp32 |
i2c.write_raw |
(addr:int, val:bytes) -> nil Write a raw sequence of bytes to the given device. |
esp32 |
i2c.read_raw |
(addr:int, val:bytes, size: int) -> int or nil Writes the val sequence of bytes on the i2c line, and then reads size bytes. |
esp32 |
Example~
Write few bytes to I2C device
Configure I2C on 21 and 23 pins, then perform two writes.
i2c.install(21, 23)
var deviceAddr = 0x10
# Write 0x01 to register 0x00
i2c.write(deviceAddr, 0x00, 0x01)
# Write byte sequence to register 0x01
i2c.write_bytes(deviceAddr, 0x01, bytes('1a01'))
gpio
~
Controls GPIO pins on supported platforms. Mainly used in different drivers.
Implemented by GPIODriver.cpp
Commands~
Command | Signature | Supported platforms |
---|---|---|
gpio.digital_write |
(gpio: int, state: int) -> void Sets GPIO to LOW/HIGH. Needs physical pin number |
esp32 |
gpio.digital_read |
(gpio: int) -> int Returns digital state of given physical GPIO. Either gpio.LOW or gpio.HIGH |
esp32 |
gpio.pin_mode |
(gpio: int, mode: int) -> int Changes the GPIO mode. Only use if if you know what you're doing, by default Euphonium handles GPIO mode itself. Mode can have the following values: gpio.INPUT, gpio.OUTPUT, gpio.PULLUP, gpio.INPUT_PULLUP, gpio.PULLDOWN |
esp32 |
gpio.analog_read |
(gpio: int) -> real .Returns the voltage on a given pin in mV. Only used with DAC pins. |
esp32 |
gpio.register_button |
(gpio: int, event_type: gpio.EVENT_TYPE, handler: [() -> void], config: map([high_state: bool])) -> void Registers a new handler called after interaction with a given button on provided gpio . Supports press, double press, and long press. |
esp32 |
enum input.EVENT_TYPE
~
Command | Description | Supported platforms |
---|---|---|
gpio.PRESS |
Called on single press of a button. | esp32 |
gpio.DOUBLE_PRESS |
Called on double press of a button. | esp32 |
gpio.LONG_PRESS |
Called on long press of a button. | esp32 |
Example~
GPIO Driver usage
Sets GPIO 21 as output, writes its state to HIGH.
gpio.pin_mode(21, gpio.OUTPUT)
gpio.digital_write(21, gpio.HIGH)
Example~
Example button that changes volume when pressed
Register a button on gpio 5, and call a function from playback
when pressed.
gpio.register_button(5, input.PRESS, def ()
print("Volume up called!")
playback.set_volume(playback.volume + 5)
end, { 'high_state': true })
led_strip
~
Allows for control of addressable LEDs like the WS28xx and SK6812. Underneath it uses esp32's RMT driver, to drive up to 8 separate strip instances.
Implemented by LEDDriver.cpp
Class LEDStrip
~
Field | Signature | Supported platforms |
---|---|---|
init / constructor |
(type: LED_TYPE, pin: int, len: int, channel: RMT_CHANNEL, brightness: int?) LEDStrip constructor. Allows control of a singular strip, with a driver type , connected under a GPIO pin . channel is the RMT channel to use. If brightness is provided, the entire LED chain will be dimmed accordingly. |
esp32 |
show |
() -> void Called on existing instance. Will update the LED strip with previously assigned color values |
esp32 |
set_item |
(index, item: [r: number, g: number, b: number]) -> void This implements the API for setting color of individual LEDs via a standard color assign. See example below for usage. r , g and b range from 0 to 255. |
esp32 |
enum led_strip.LED_TYPE
~
Value | Description |
---|---|
LED_WS2812 |
Indicates WS2812 LED type. |
LED_WS2812B |
Indicates WS2812B LED type. |
LED_SK6812 |
Indicates SK6812 LED type. |
LED_WS2813 |
Indicates WS2813 LED type. |
Example~
LED Driver usage
Registers a new LED strip under pin 21, consisting of 12 WS2812 leds, at lower brightness. Then turns the first LED red, the second one green.
volume_strip = LEDStrip(LED_WS2812, 21, 12, RMT_CHANNEL_0, 150)
# change the first LED to red and second one to green.
volume_strip[0] = [255, 0, 0] # red in RGB format
volume_strip[1] = [0, 255, 0] # green in RGB format
# display the changes on the strip
volume_strip.show()
wifi
~
Controls internal state of the platform's WiFi. Used internally by wifi.be
.
Implemented by WiFiDriver.cpp
Commands~
Command | Signature | Supported platforms |
---|---|---|
wifi.init_stack |
() -> void Initializes the WiFi stack |
esp32 |
wifi.connect |
(ssid: string, password: string, fromAP: bool) -> void Attempts WiFi connection. fromAP should be set according to the current WiFi mode. |
esp32 |
wifi.start_ap |
(ssid: string, password: string) -> void Starts an access point with given credentials. |
esp32 |
wifi.start_scan |
() -> boid .Starts scanning of WiFi networks. |
esp32 |