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)

Handle POST with json body, return a json response

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