Skip to content

Interpreter#

Guide for Coding with JavaScript in Bruce#

The Bruce JS Interpreter allows you to create scripts or even games using JavaScript.

For legacy version of this page go here: Interpreter Legacy

Some example scripts are here.

You can copy your favourite scripts in the /scripts folder and have them listed in the "Scripts" menu.

For easier development, you can use this bash script to upload code directly via serial. (linux only) Or this TypeScript developement SDK works in linux and windows.

Important: JavaScript Compatibility#

  • ❌ No modern JavaScript features – Use only ES5 syntax:
    • ❌ No let (use var instead).
    • ❌ No for...of loops (use traditional for loops with indexes).
    • ❌ No Arrow functions () => {} (use function instead).
    • ❌ No import ir from 'ir' import syntax use const ir = require('ir'); instead.
    • ❌ No External npm module imports.
    • ❌ No Object.entries(), Promise, async/await, setInterval, setTimeout (for now).

If you want modern JS features as well as TypeScript support you can go here

Uploading Your Scripts to Bruce#

When uploading scripts to Bruce, keep in mind:

Documentation#

Modules#

Module Description
globals Global variables and functions available in bruce js.
audio Controls the audio.
badusb Simulates USB keyboard input.
device Show device information.
dialog Displays dialog messages and user interactions.
display Controls the TFT Display
gpio GPIO (General Purpose Input/Output) ports
ir Interacting with infrared (IR) signals.
keyboard Access the keyboard input.
notification Controls the notification LED.
serial Serial communication.
storage File storage operations.
subghz Sub-GHz communication.
wifi Wi-Fi connection and HTTP requests.

globals#

Global variables and functions available in bruce js.

Example#

console.log(now()); // console.log prints to serial monitor
delay(1000); // Pause for 1000ms (1 second)
var myNumber = parse_int("2133"); // myNumber will be number 2133
var myString = to_string(24); // myString will be string "24"
var myHexStr = to_hex_string(1337); // myHexStr will be string "539" (because 1337 decimal is 0x539).
var str = "Hello World";
println(to_lower_case(str)); // prints: hello world
println(to_upper_case(str)); // prints: HELLO WORLD
println(random(1, 20)); // prints random value between 1 and 20
println(__dirname); // prints current dirname

globals functions#

Path#

Represents a file path along with its storage location.

Example#

const dialog = require("dialog");
dialog.pickFile({ fs: "user", path: "/" });

Properties#

Property Type Description
fs FileSystem The storage medium where the file is located
path string The file path within the selected storage medium

FileSystem#

type FileSystem = "sd" | "littlefs" | null;

Represents the storage medium where a file is located.

  • 'sd' - File stored on SD card.
  • 'littlefs' - File stored on LittleFS.
  • null - Automatically choose between SD card (if available) and LittleFS as a fallback.

__dirname#

const __dirname: string;

Path to the directory containing the current script

__filename#

const __filename: string;

Path to the current script file

BRUCE_VERSION#

const BRUCE_VERSION: string;

Version of the bruce firmware

BRUCE_PRICOLOR#

const BRUCE_PRICOLOR: number;

Primary color from the config

BRUCE_SECCOLOR#

const BRUCE_SECCOLOR: number;

Secondary color from the config

BRUCE_BGCOLOR#

const BRUCE_BGCOLOR: number;

Background color from the config

now()#

now(): number;

Returns the current time in milliseconds since the epoch

Returns#

number

The current timestamp in milliseconds

delay()#

delay(ms: number): void;

Pauses execution for the specified number of milliseconds

Parameters#

Parameter Type Description
ms number The number of milliseconds to delay

Returns#

void

parse_int()#

parse_int(text: string): number;

Converts a string to a number

Parameters#

Parameter Type Description
text string The string to convert to a number

Returns#

number

to_string()#

to_string(value: any): string;

Converts a value to a string

Parameters#

Parameter Type Description
value any The value to convert to a string

Returns#

string

to_hex_string()#

to_hex_string(text: string): string;

Converts a hex string to a number

Parameters#

Parameter Type Description
text string The hex string to convert to a number

Returns#

string

to_lower_case()#

to_lower_case(text: string): string;

Converts a string to a number

Parameters#

Parameter Type Description
text string The string to convert to a number

Returns#

string

to_upper_case()#

to_upper_case(text: string): string;

Converts a string to a number

Parameters#

Parameter Type Description
text string The string to convert to a number

Returns#

string

random()#

Call Signature#

random(min: number, max: number): number;

Returns a pseudo-random number

Parameters#

Parameter Type Description
min number Lower bound of the random value, inclusive (optional)
max number Upper bound of the random value, exclusive

Returns#

number

Call Signature#

random(max: number): number;

Returns a pseudo-random number

Parameters#

Parameter Type Description
max number Upper bound of the random value, exclusive

Returns#

number

println()#

println(...args: any[]): void;

Prints text to serial monitor and display. Alias to display.println().

Parameters#

Parameter Type Description
...args any[] Text content.

Returns#

void

require()#

require(module: string): any;

Loads a module. List of modules: modules.

Example#

const dialog = require("dialog");
dialog.message("Test.");

Parameters#

Parameter Type Description
module string The name of the module to load

Returns#

any

assert()#

assert(assertion: boolean, message?: string): boolean;

Throws an error if the assertion is false.

Example#

assert(2 + 2 === 5); // Throws an error

Parameters#

Parameter Type Description
assertion boolean Any boolean expression
message? string The Error message if assertion is false

Returns#

boolean

audio#

Controls the audio.

Example#

const audio = require("audio");

audio.tone(988, 2000); // Beeps buzzer for 2 seconds

audio functions#

audio.playFile()#

audio.playFile(filename: string): void;

Plays an audio file from storage.

Parameters#

Parameter Type Description
filename string The path to the audio file (e.g., "/sound.wav").

Returns#

void

audio.tone()#

audio.tone(
  frequency: number,
  durationMs: number,
  nonBlocking?: boolean,
): void;

Plays a tone at the specified frequency for a given duration.

Parameters#

Parameter Type Description
frequency number Frequency in Hz.
durationMs number Duration in milliseconds.
nonBlocking? boolean If true, the function will not play the tone if it would block execution.

Returns#

void

badusb#

Simulates USB keyboard input.

Example#

const badusb = require("badusb");

badusb.setup();
badusb.press(0x04); // Presses the 'A' key
badusb.release(0x04); // Releases the 'A' key
badusb.println("Hello, world!"); // Types and presses Enter

badusb functions#

badusb.setup()#

badusb.setup(): void;

Initializes the BadUSB module.

Returns#

void

badusb.press()#

badusb.press(keycode: number): void;

Simulates pressing a key using a keycode.

Parameters#

Parameter Type Description
keycode number HID keycode of the key to press.

Returns#

void

badusb.pressRaw()#

badusb.pressRaw(hid_key: number): void;

Simulates pressing a key using a raw HID key value.

Parameters#

Parameter Type Description
hid_key number Raw HID key value.

Returns#

void

badusb.hold()#

badusb.hold(keycode: number): void;

Simulates holding down a key.

Parameters#

Parameter Type Description
keycode number HID keycode of the key to hold.

Returns#

void

badusb.release()#

badusb.release(keycode: number): void;

Releases a previously pressed key.

Parameters#

Parameter Type Description
keycode number HID keycode of the key to release.

Returns#

void

badusb.releaseAll()#

badusb.releaseAll(): void;

Releases all currently held keys.

Returns#

void

badusb.print()#

badusb.print(message: string): void;

Types a string as keyboard input.

Parameters#

Parameter Type Description
message string The text to type.

Returns#

void

badusb.println()#

badusb.println(message: string): void;

Types a string followed by an "Enter" key press.

Parameters#

Parameter Type Description
message string The text to type.

Returns#

void

badusb.runFile()#

badusb.runFile(filename: string): void;

Executes a script file from storage.

Parameters#

Parameter Type Description
filename string The path to the script file.

Returns#

void

device#

Show device information.

Example#

const device = require("device");

console.log("Device Name:", device.getName());
console.log("Board:", device.getBoard());
console.log("Model:", device.getModel());
console.log("Battery Charge:", device.getBatteryCharge(), "%");

const memoryStats = device.getFreeHeapSize();
console.log("RAM Free:", memoryStats.ram_free);
console.log("PSRAM Free:", memoryStats.psram_free);

device functions#

device.getName()#

device.getName(): string;

Retrieves the device's name.

Returns#

string

The name of the device.

device.getBoard()#

device.getBoard(): string;

Retrieves the board type.

Returns#

string

The board identifier.

device.getModel()#

device.getModel(): string;

Retrieves the model name.

Returns#

string

The model of the device.

device.getBatteryCharge()#

device.getBatteryCharge(): number;

Retrieves the current battery charge level.

Returns#

number

The battery charge percentage (0-100).

device.getFreeHeapSize()#

device.getFreeHeapSize(): {
  ram_free: number;
  ram_min_free: number;
  ram_largest_free_block: number;
  ram_size: number;
  psram_free: number;
  psram_size: number;
};

Retrieves information about the device's memory usage.

Returns#

{
  ram_free: number;
  ram_min_free: number;
  ram_largest_free_block: number;
  ram_size: number;
  psram_free: number;
  psram_size: number;
}

An object containing RAM and PSRAM statistics:

  • ram_free: Free RAM available (in bytes).
  • ram_min_free: Minimum free RAM recorded (in bytes).
  • ram_largest_free_block: Largest contiguous free RAM block (in bytes).
  • ram_size: Total RAM size (in bytes).
  • psram_free: Free PSRAM available (in bytes).
  • psram_size: Total PSRAM size (in bytes).
Name Type
ram_free number
ram_min_free number
ram_largest_free_block number
ram_size number
psram_free number
psram_size number

dialog#

Displays dialog messages and user interactions.

Example#

const dialog = require("dialog");

dialog.success("Operation completed successfully.");
dialog.error("An error occurred!", true);

const options = ["Yes", "No", "Cancel"];
const selected = dialog.choice(options);

const filePath = dialog.pickFile("/documents", "txt");
dialog.viewFile(filePath);

dialog functions#

dialog.drawStatusBar()#

dialog.drawStatusBar(): void;

Draws Bruce's status bar

Returns#

void

dialog.message()#

dialog.message(
  message: string,
  buttons?: {
    left: string;
    center: string;
    right: string;
  },
): void | "left" | "center" | "right";

Displays a message dialog with up to three choices.

Example#

const dialog = require("dialog");
dialog.message("Hello!"); // Just displays the message
dialog.message("Press any key...", true); // Blocks until a key is pressed
const choice = dialog.message("Choose:", {
  left: "No",
  center: "Maybe",
  right: "Yes",
});
if (choice === "right") console.log("User chose Yes!");

Parameters#

Parameter Type Description
message string The message to display.
buttons? { left: string; center: string; right: string; } If true, waits for a key press before closing (default: false). If an object, displays up to three buttons with custom labels.
buttons.left? string -
buttons.center? string -
buttons.right? string -

Returns#

void | "left" | "center" | "right"

The button pressed ("left", "center", or "right"), or void if no buttons are used.

dialog.info()#

dialog.info(message: string, waitForKeyPress?: boolean): void;

Displays an info notification (Blue background).

Example#

const dialog = require("dialog");
dialog.info("Operation completed successfully.");

Parameters#

Parameter Type Description
message string The info message to display.
waitForKeyPress? boolean If true, waits for a key press before closing (default: false).

Returns#

void

dialog.success()#

dialog.success(message: string, waitForKeyPress?: boolean): void;

Displays an success notification (Green background).

Example#

const dialog = require("dialog");
dialog.success("Operation completed successfully.");

Parameters#

Parameter Type Description
message string The success message to display.
waitForKeyPress? boolean If true, waits for a key press before closing (default: false).

Returns#

void

dialog.warning()#

dialog.warning(message: string, waitForKeyPress?: boolean): void;

Displays an warning notification (Yellow background).

Example#

const dialog = require("dialog");
dialog.warning("Warning!");

Parameters#

Parameter Type Description
message string The warning message to display.
waitForKeyPress? boolean If true, waits for a key press before closing (default: false).

Returns#

void

dialog.error()#

dialog.error(message: string, waitForKeyPress?: boolean): void;

Displays an error notification (Red background).

Example#

const dialog = require("dialog");
dialog.error("An error occurred!", true);

Parameters#

Parameter Type Description
message string The error message to display.
waitForKeyPress? boolean If true, waits for a key press before closing (default: false).

Returns#

void

dialog.choice()#

dialog.choice(
  values: string[] | [string, string][] | {} | string[][],
): string;

Displays a choice dialog and returns the selected option.

Example#

const dialog = require("dialog");
const options = ["Yes", "No", "Cancel"];
const selected = dialog.choice(options);
console.log("Selected:", selected); // it should print "Yes", "No" or "Cancel"

const optionsNestedArray = [
  ["Go Back", "go_back"],
  ["Cancel", "cancel"],
  ["Quit", "quit"],
];
const selectedNestedArray = dialog.choice(optionsNestedArray);
console.log("selectedNestedArray:", selectedNestedArray); // it should print "go_back", "cancel" or "quit"

const optionsObject = { "Go Back": "go_back", Cancel: "cancel", Quit: "quit" };
const selectedObject = dialog.choice(optionsObject);
console.log("selectedObject:", selectedObject); // it should print "go_back", "cancel" or "quit"

Parameters#

Parameter Type Description
values string[] | [string, string][] | {} | string[][] An array of options to choose from. Can also be nested array or object.

Returns#

string

The selected option as a string.

dialog.pickFile()#

dialog.pickFile(path?: string, extension?: string): string;

Opens a file picker dialog and returns the selected file path.

Example#

const dialog = require("dialog");
const filePath = dialog.pickFile("/documents", "txt");
dialog.viewFile(filePath);

Parameters#

Parameter Type Description
path? string The initial directory path (optional).
extension? string The file extension filter (optional).

Returns#

string

The selected file path or null if no file is chosen.

dialog.prompt()#

dialog.prompt(title?: string, valueLength?: number, value?: string): string;

Opens an on-screen keyboard for user input.

Parameters#

Parameter Type Description
title? string Title of the keyboard prompt.
valueLength? number Maximum length of the input value.
value? string Initial value to display.

Returns#

string

User input.

dialog.viewFile()#

dialog.viewFile(path: string): void;

Opens and displays a file in a viewer. Displays a window where the user can scroll and exit. Blocks execution until the user exits.

Example#

const dialog = require("dialog");
const filePath = dialog.pickFile("/documents", "txt");
dialog.viewFile(filePath);

Parameters#

Parameter Type Description
path string The file path to view.

Returns#

void

dialog.viewText()#

dialog.viewText(text: string, title?: string): void;

Opens and displays text in a viewer. Displays a window where the user can scroll and exit. Blocks execution until the user exits.

Example#

const dialog = require("dialog");
dialog.viewText("text to display");

Parameters#

Parameter Type Description
text string The text to view.
title? string The optional title of the viewer window.

Returns#

void

dialog.createTextViewer()#

dialog.createTextViewer(
  text: string,
  options?: {
    fontSize: number;
    startX: number;
    startY: number;
    width: number;
    height: number;
    indentWrappedLines: boolean;
  },
): TextViewer;

Creates a TextViewer instance, allowing manual control. Unlike viewText, this does not block execution. You must handle scrolling and closing yourself. Thanks to this you can implement: scrolling to section, follow links in text, and much more. You can find example of the implementation here: https://github.com/Tawank/bruce-js-tooling/tree/master/examples/browser-bruce

Example#

const dialog = require("dialog");
const textViewer = dialog.createTextViewer("long text");
while (true) {
  if (keyboard.getPrevPress()) {
    textViewer.scrollUp();
  }
  if (keyboard.getNextPress()) {
    textViewer.scrollDown();
  }
  textViewer.draw();
  delay(100);
}

Parameters#

Parameter Type Description
text string The text to view.
options? { fontSize: number; startX: number; startY: number; width: number; height: number; indentWrappedLines: boolean; } The text viewer options.
options.fontSize? number -
options.startX? number -
options.startY? number -
options.width? number -
options.height? number -
options.indentWrappedLines? boolean -

Returns#

TextViewer

A TextViewer instance with manual controls.

display#

Controls the TFT Display

Example#

const display = require("display");

const black = display.color(0, 0, 0);
const white = display.color(255, 255, 255);

display.fill(black);
display.drawFillRect(20, 20, 50, 50, white);

delay(2000);

display functions#

display.color()#

display.color(r: number, g: number, b: number): number;

Converts RGB values to a display-compatible color format.

Parameters#

Parameter Type Description
r number Red (0-255)
g number Green (0-255)
b number Blue (0-255)

Returns#

number

A numeric representation of the color.

display.fill()#

display.fill(color: number): void;

Fills the entire screen with the specified color.

Parameters#

Parameter Type Description
color number Color value (use display.color(r, g, b) to generate one).

Returns#

void

display.setCursor()#

display.setCursor(x: number, y: number): void;

Sets the cursor position for text rendering.

Parameters#

Parameter Type Description
x number X-coordinate.
y number Y-coordinate.

Returns#

void

display.print()#

display.print(...args: any[]): void;

Prints text at the current cursor position. It also prints text to the Serial Monitor for devices without screen.

Parameters#

Parameter Type Description
...args any[] Text content.

Returns#

void

display.println()#

display.println(...args: any[]): void;

Prints text followed by a newline at the current cursor position. It also prints text to the Serial Monitor for devices without screen.

Parameters#

Parameter Type Description
...args any[] Text content.

Returns#

void

display.setTextColor()#

display.setTextColor(color: number): void;

Sets the text color.

Parameters#

Parameter Type Description
color number Text color (use display.color(r, g, b) to generate one).

Returns#

void

display.setTextAlign()#

display.setTextAlign(
  align: number | "left" | "center" | "right",
  baseline?: number | "top" | "middle" | "bottom" | "alphabetic",
): void;

Sets the text alignment and baseline for rendering text.

Example#

display.setTextAlign(1, 2); // Center align, bottom baseline
display.drawText(50, 50, "Hello!");

Parameters#

Parameter Type Description
align number | "left" | "center" | "right" Horizontal alignment of the text.
baseline? number | "top" | "middle" | "bottom" | "alphabetic" Vertical alignment of the text.

Returns#

void

display.setTextSize()#

display.setTextSize(size: number): void;

Sets the text size.

Parameters#

Parameter Type Description
size number Text size.

Returns#

void

display.drawText()#

display.drawText(text: string | number | boolean, x: number, y: number): void;

Draws text at the specified position.

Parameters#

Parameter Type Description
text string | number | boolean The text to display.
x number X-coordinate.
y number Y-coordinate.

Returns#

void

display.drawString()#

display.drawString(
  text: string | number | boolean,
  x: number,
  y: number,
): void;

Draws a string at the specified position (alias for drawText).

Parameters#

Parameter Type
text string | number | boolean
x number
y number

Returns#

void

display.drawPixel()#

display.drawPixel(x: number, y: number, color: number): void;

Draws a single pixel on the display.

Parameters#

Parameter Type Description
x number X-coordinate.
y number Y-coordinate.
color number Pixel color (use display.color(r, g, b) to generate one).

Returns#

void

display.drawLine()#

display.drawLine(
  x: number,
  y: number,
  x2: number,
  y2: number,
  color: number,
): void;

Draws a line between two points.

Parameters#

Parameter Type Description
x number Start X-coordinate.
y number Start Y-coordinate.
x2 number End X-coordinate.
y2 number End Y-coordinate.
color number Line color (use display.color(r, g, b) to generate one).

Returns#

void

display.drawRect()#

display.drawRect(
  x: number,
  y: number,
  width: number,
  height: number,
  color: number,
): void;

Draws a rectangle outline.

Parameters#

Parameter Type Description
x number X-coordinate.
y number Y-coordinate.
width number Rectangle width.
height number Rectangle height.
color number Outline color (use display.color(r, g, b) to generate one).

Returns#

void

display.drawFillRect()#

display.drawFillRect(
  x: number,
  y: number,
  width: number,
  height: number,
  color: number,
): void;

Draws a filled rectangle.

Parameters#

Parameter Type Description
x number X-coordinate.
y number Y-coordinate.
width number Rectangle width.
height number Rectangle height.
color number Color (use display.color(r, g, b) to generate one).

Returns#

void

display.drawFillRectGradient()#

display.drawFillRectGradient(
  x: number,
  y: number,
  width: number,
  height: number,
  color1: number,
  color2: number,
  direction: "horizontal" | "vertical",
): void;

Draws a filled gradient rectangle.

Parameters#

Parameter Type Description
x number X-coordinate.
y number Y-coordinate.
width number Rectangle width.
height number Rectangle height.
color1 number Color 1 (use display.color(r, g, b) to generate one).
color2 number Color 2 (use display.color(r, g, b) to generate one).
direction "horizontal" | "vertical" 'horizontal' or 'vertical'.

Returns#

void

display.drawRoundRect()#

display.drawRoundRect(
  x: number,
  y: number,
  width: number,
  height: number,
  radius: number,
  color: number,
): void;

Draws a round rectangle.

Parameters#

Parameter Type Description
x number X-coordinate.
y number Y-coordinate.
width number Rectangle width.
height number Rectangle height.
radius number Rectangle radius.
color number Outline color (use display.color(r, g, b) to generate one).

Returns#

void

display.drawFillRoundRect()#

display.drawFillRoundRect(
  x: number,
  y: number,
  width: number,
  height: number,
  radius: number,
  color: number,
): void;

Draws a filled round rectangle.

Parameters#

Parameter Type Description
x number X-coordinate.
y number Y-coordinate.
width number Rectangle width.
height number Rectangle height.
radius number Rectangle radius.
color number Color (use display.color(r, g, b) to generate one).

Returns#

void

display.drawCircle()#

display.drawCircle(x: number, y: number, r: number, color: number): void;

Draws a circle.

Parameters#

Parameter Type Description
x number X-coordinate.
y number Y-coordinate.
r number Circle radius.
color number Outline color (use display.color(r, g, b) to generate one).

Returns#

void

display.drawFillCircle()#

display.drawFillCircle(x: number, y: number, r: number, color: number): void;

Draws a filled circle.

Parameters#

Parameter Type Description
x number X-coordinate.
y number Y-coordinate.
r number Circle radius.
color number Color (use display.color(r, g, b) to generate one).

Returns#

void

display.drawXBitmap()#

display.drawXBitmap(
  x: number,
  y: number,
  bitmap: ArrayBuffer,
  width: number,
  height: number,
  fgColor: number,
  bgColor?: number,
): void;

Draws a monochrome bitmap (XBM Bitmap) at the specified position on the screen. You can convert images to this format using this online converter: https://www.online-utility.org/image/convert/to/XBM

Parameters#

Parameter Type Description
x number X-coordinate for the bitmap.
y number Y-coordinate for the bitmap.
bitmap ArrayBuffer The bitmap data stored in an ArrayBuffer (1-bit per pixel).
width number The width of the bitmap in pixels.
height number The height of the bitmap in pixels.
fgColor number The foreground color (used for 1 bits in the bitmap).
bgColor? number (Optional) The background color (used for 0 bits in the bitmap). If not provided then the background is transparent.

Returns#

void

display.drawBitmap()#

display.drawBitmap(
  x: number,
  y: number,
  bitmap: ArrayBuffer,
  width: number,
  height: number,
  bpp: 1 | 4 | 8 | 16,
  palette?: ArrayBuffer,
): void;

Draws a bitmap at the specified position on the screen.

Parameters#

Parameter Type Description
x number X-coordinate for the bitmap.
y number Y-coordinate for the bitmap.
bitmap ArrayBuffer The bitmap data stored in an ArrayBuffer. The format depends on bpp: - 16 bpp: Each pixel is a 16-bit color value (RGB565). - 8 bpp: Each pixel is an 8-bit color value (RGB332). - 4 bpp: Each pixel is a 4-bit index into palette (2 pixels per byte). - 1 bpp: Each pixel is a 1-bit index into palette (8 pixels per byte).
width number The width of the bitmap in pixels.
height number The height of the bitmap in pixels.
bpp 1 | 4 | 8 | 16 Bits per pixel (16, 8, 4, or 1).
palette? ArrayBuffer A color palette used only when bpp is 4 or 1. Each entry is a 16-bit color (RGB565).

Returns#

void

display.drawJpg()#

display.drawJpg(
  path: string | Path,
  x?: number,
  y?: number,
  center?: boolean,
): void;

Draws a JPG image on the display.

Parameters#

Parameter Type Description
path string | Path The path to the JPG file. Supports: - A string path (e.g., "/images/photo.jpg"). - A Path object specifying storage { fs: "sd", path: "/images/photo.jpg" }.
x? number X-coordinate.
y? number Y-coordinate.
center? boolean -

Returns#

void

display.drawGif()#

display.drawGif(
  path: string | Path,
  x?: number,
  y?: number,
  center?: boolean,
  playDurationMs?: number,
): void;

Draws a GIF image on the display.

Parameters#

Parameter Type Description
path string | Path The path to the GIF file. Supports: - A string path (e.g., "/images/anim.gif"). - A Path object specifying storage { fs: "sd", path: "/images/anim.gif" }.
x? number X-coordinate.
y? number Y-coordinate.
center? boolean Whether to center the image.
playDurationMs? number Duration to play the GIF.

Returns#

void

display.gifOpen()#

display.gifOpen(path: string | Path): Gif;

Opens a GIF for manual frame playback.

Parameters#

Parameter Type Description
path string | Path The path to the GIF file. Supports: - A string path (e.g., "/images/anim.gif"). - A Path object specifying storage { fs: "sd", path: "/images/anim.gif" }.

Returns#

Gif

A Gif object for controlling playback.

display.width()#

display.width(): number;

Gets the display width.

Returns#

number

Display width in pixels.

display.height()#

display.height(): number;

Gets the display height.

Returns#

number

Display height in pixels.

gpio#

GPIO (General Purpose Input/Output) ports

Example#

const gpio = require("gpio");

const led = 26;
gpio.init(led, OUTPUT);

gpio.write(led, HIGH);
delay(1000);
gpio.write(led, LOW);
delay(1000);

gpio functions#

gpio.pinMode()#

gpio.pinMode(pin: string | number, mode: Mode): void;

Configures the specified pin mode.

Parameters#

Parameter Type Description
pin string | number GPIO pin number or name (e.g., 26 or "G26").
mode Mode Pin mode (INPUT, OUTPUT, PULLUP, etc.).

Returns#

void

gpio.digitalWrite()#

gpio.digitalWrite(pin: string | number, value: boolean | PinValue): void;

Writes a digital value to a pin.

Parameters#

Parameter Type Description
pin string | number GPIO pin number or name.
value boolean | PinValue HIGH/LOW or true/false.

Returns#

void

gpio.digitalRead()#

gpio.digitalRead(pin: string | number): number;

Reads the digital state of a pin.

Parameters#

Parameter Type Description
pin string | number GPIO pin number or name.

Returns#

number

1 for HIGH, 0 for LOW.

gpio.analogWrite()#

gpio.analogWrite(pin: string | number, value: number): void;

Writes an analog value (PWM) to a pin.

Parameters#

Parameter Type Description
pin string | number GPIO pin number or name.
value number PWM duty cycle (0-255).

Returns#

void

gpio.analogRead()#

gpio.analogRead(pin: string | number): number;

Reads the analog value from a pin.

Parameters#

Parameter Type Description
pin string | number GPIO pin number or name.

Returns#

number

Analog value (0-4095 for ADC1, varies for ADC2).

gpio.touchRead()#

gpio.touchRead(pin: string | number): number;

Reads the capacitive touch sensor value from a pin.

Parameters#

Parameter Type Description
pin string | number GPIO pin number or name.

Returns#

number

Touch sensor value.

gpio.dacWrite()#

gpio.dacWrite(pin: string | number, value: number): void;

Writes a DAC (Digital-to-Analog) value to a pin.

Parameters#

Parameter Type Description
pin string | number GPIO pin number or name.
value number DAC value (0-255).

Returns#

void

gpio.ledcSetup()#

gpio.ledcSetup(
  channel: number,
  freq: number,
  resolution_bits: number,
): number;

Configures an LEDC (PWM) channel with a specific frequency and resolution.

Parameters#

Parameter Type Description
channel number LEDC channel number (0–15).
freq number PWM frequency in Hz.
resolution_bits number Resolution (1–16 bits, defining duty cycle range).

Returns#

number

The actual frequency set.

gpio.ledcAttachPin()#

gpio.ledcAttachPin(pin: number, channel: number): number;

Attaches a GPIO pin to an LEDC (PWM) channel.

Parameters#

Parameter Type Description
pin number GPIO pin number.
channel number LEDC channel number (0–15).

Returns#

number

0 on success, non-zero on failure.

gpio.ledcWrite()#

gpio.ledcWrite(channel: number, duty: number): number;

Sets the PWM duty cycle for a specific LEDC (PWM) channel.

Parameters#

Parameter Type Description
channel number LEDC channel number (0–15).
duty number Duty cycle (0 to 2^resolution_bits - 1).

Returns#

number

0 on success, non-zero on failure.

ir#

Interacting with infrared (IR) signals.

Example#

const ir = require("ir");

const signal = ir.read(5); // Waits up to 5 seconds for an IR signal
console.log("Received IR signal:", signal);

const rawSignal = ir.readRaw(5);
console.log("Received raw IR signal:", rawSignal);

const success = ir.transmitFile("/signals/power_on.ir");
console.log("Transmission successful:", success);

ir functions#

ir.read()#

ir.read(timeoutSeconds: number): string;

Reads an infrared signal within a given timeout.

Parameters#

Parameter Type Description
timeoutSeconds number Timeout duration in seconds.

Returns#

string

The received IR signal as a string.

ir.readRaw()#

ir.readRaw(timeoutSeconds: number): string;

Reads an infrared signal in raw format within a given timeout.

Parameters#

Parameter Type Description
timeoutSeconds number Timeout duration in seconds.

Returns#

string

The raw received IR signal as a string.

ir.transmitFile()#

ir.transmitFile(path: string): boolean;

Transmits an infrared signal stored in a file.

Parameters#

Parameter Type Description
path string Path to the IR signal file.

Returns#

boolean

true if the transmission was successful, otherwise false.

keyboard#

Access the keyboard input.

Example#

const keyboard = require("keyboard");

while (true) {
  if (keyboard.getAnyPress()) {
    break; // Exits the loop when a button is pressed.
  }
}

keyboard functions#

keyboard.getKeysPressed()#

keyboard.getKeysPressed(): string[];

Gets a list of currently pressed keys.

Returns#

string[]

An array of key names.

keyboard.getPrevPress()#

keyboard.getPrevPress(hold?: boolean): boolean;

Checks if the "previous" button was pressed.

Parameters#

Parameter Type Description
hold? boolean If true, returns true as long as any button is held down. If false or omitted, returns true only on press and repeats every X ms. Default: false.

Returns#

boolean

true if the button was pressed, otherwise false.

keyboard.getSelPress()#

keyboard.getSelPress(hold?: boolean): boolean;

Checks if the "select" button was pressed.

Parameters#

Parameter Type Description
hold? boolean If true, returns true as long as any button is held down. If false or omitted, returns true only on press and repeats every X ms. Default: false.

Returns#

boolean

true if the button was pressed, otherwise false.

keyboard.getNextPress()#

keyboard.getNextPress(hold?: boolean): boolean;

Checks if the "next" button was pressed.

Parameters#

Parameter Type Description
hold? boolean If true, returns true as long as any button is held down. If false or omitted, returns true only on press and repeats every X ms. Default: false.

Returns#

boolean

true if the button was pressed, otherwise false.

keyboard.getEscPress()#

keyboard.getEscPress(hold?: boolean): boolean;

Checks if the "esc" button was pressed.

Parameters#

Parameter Type Description
hold? boolean If true, returns true as long as any button is held down. If false or omitted, returns true only on press and repeats every X ms. Default: false.

Returns#

boolean

true if the button was pressed, otherwise false.

keyboard.getAnyPress()#

keyboard.getAnyPress(hold?: boolean): boolean;

Checks if any button was pressed.

Parameters#

Parameter Type Description
hold? boolean If true, returns true as long as any button is held down. If false or omitted, returns true only on press and repeats every X ms. Default: false.

Returns#

boolean

true if any button was pressed, otherwise false.

keyboard.keyboard()#

keyboard.keyboard(title: string, valueLength: number, value: string): string;

Opens an on-screen keyboard for user input.

Parameters#

Parameter Type Description
title string Title of the keyboard prompt.
valueLength number Maximum length of the input value.
value string Initial value to display.

Returns#

string

User input.

notification#

Controls the notification LED.

Example#

const notification = require("notification");

notification.blink(200); // Blinks the LED for 200ms
delay(1000);
notification.blink("short"); // Blinks using a predefined short duration

notification functions#

notification.blink(durationMs: number | "short" | "long"): void;

Blinks the notification LED for a specified duration.

This function turns the LED on, waits for the given duration, and then turns it off. Equivalent to:

digitalWrite(19, HIGH);
delay(ms);
digitalWrite(19, LOW);

Parameters#

Parameter Type Description
durationMs number | "short" | "long" Duration in milliseconds for how long the LED should blink.

Returns#

void

serial#

Serial communication.

Example#

const serial = require("serial");

serial.println("Hello, Serial Port!");
const input = serial.readln();
console.log("Received:", input);

serial functions#

serial.print()#

serial.print(...args: any[]): void;

Sends a message over the serial connection without a newline.

Parameters#

Parameter Type Description
...args any[] The values to print.

Returns#

void

serial.println()#

serial.println(...args: any[]): void;

Sends a message over the serial connection with a newline at the end.

Parameters#

Parameter Type Description
...args any[] The values to print.

Returns#

void

serial.readln()#

serial.readln(timeoutInMiliseconds?: number): string;

Reads a line of input from the serial connection.

Parameters#

Parameter Type Description
timeoutInMiliseconds? number The time (in miliseconds) to wait for a connection before failing.

Returns#

string

The received string.

serial.cmd()#

serial.cmd(command: string): boolean;

Executes a serial command list: controlling-device/serial.md.

Parameters#

Parameter Type
command string

Returns#

boolean

true if the command was successful, otherwise false.

storage#

File storage operations.

This module provides functions for reading, writing, listing, renaming, and deleting files on different storage types.

Example#

const storage = require("storage");

// Write data to a file
const success = storage.write("/data/log.txt", "Hello, world!");
if (success) {
  console.log("File written successfully!");
}

// Read data from a file
const content = storage.read("/data/log.txt");
console.log("File content:", content);

// Rename a file
const renamed = storage.rename("/data/log.txt", "/data/log_old.txt");
console.log("Rename successful:", renamed);

// Delete a file
const deleted = storage.delete("/data/log_old.txt");
console.log("Delete successful:", deleted);

// List directory contents
const files = storage.readdir("/data", { withFileTypes: true });
console.log("Files:\n", JSON.stringify(files, null, 2));

// Create a new directory
storage.mkdir("/data/newdir");

// Remove a directory
storage.rmdir("/data/newdir");

storage functions#

storage.Dirent#

Directory entry representing a file or directory.

Properties#

Property Type
name string
size number
isDirectory boolean

storage.read()#

Call Signature#

storage.read(path: string | Path, binary?: false): string;

Reads the content of a file.

Parameters#

Parameter Type Description
path string | Path The path to the file. Supports: - A string path (e.g., "/file.txt"). - A Path object specifying storage { fs: "sd", path: "/file.txt" }.
binary? false If true, returns the file content as a Uint8Array (default: false).

Returns#

string

The file content as:

  • A string if binary is false or omitted.
  • A Uint8Array if binary is true.

Call Signature#

storage.read(path: string | Path, binary: true): Uint8Array;

Reads the content of a file.

Parameters#

Parameter Type Description
path string | Path The path to the file. Supports: - A string path (e.g., "/file.txt"). - A Path object specifying storage { fs: "sd", path: "/file.txt" }.
binary true If true, returns the file content as a Uint8Array (default: false).

Returns#

Uint8Array

The file content as:

  • A string if binary is false or omitted.
  • A Uint8Array if binary is true.

storage.write()#

storage.write(
  path: string | Path,
  data: string | Uint8Array,
  mode?: "write" | "append",
  position?: string | number,
): boolean;

Writes data to a file, optionally inserting at a specific position.

Parameters#

Parameter Type Description
path string | Path The file path. Supports: - A string like "/file.txt". - A Path object like { fs: "sd", path: "/file.txt" }.
data string | Uint8Array The content to write. Can be a string or Uint8Array.
mode? "write" | "append" How to write: - "write" (default): Replace the file content. - "append": Add to the end of the file.
position? string | number Where to insert the data: - A number: Insert at this byte position. - A string: Insert before the first time this text appears. - "end": Add to the end (default for "append" mode).

Returns#

boolean

true if writing was successful, otherwise false.

storage.readdir()#

Call Signature#

storage.readdir(
  path: string | Path,
  options?: {
    withFileTypes: false;
  },
): string[];

Lists the contents of a directory.

Parameters#

Parameter Type Description
path string | Path The directory path. Supports: - A string path (e.g., "/file.txt"). - A Path object specifying storage { fs: "sd", path: "/file.txt" }.
options? { withFileTypes: false; } -
options.withFileTypes? false -

Returns#

string[]

An array of files and directories names in the directory.

Call Signature#

storage.readdir(
  path: string | Path,
  options: {
    withFileTypes: true;
  },
): Dirent[];

Lists the contents of a directory.

Parameters#

Parameter Type Description
path string | Path The directory path. Supports: - A string path (e.g., "/file.txt"). - A Path object specifying storage { fs: "sd", path: "/file.txt" }.
options { withFileTypes: true; } If { withFileTypes: true }, returns an array of Dirent objects with file type info.
options.withFileTypes true -

Returns#

Dirent[]

An array of filenames or Dirent objects if withFileTypes is true.

storage.rename()#

storage.rename(oldPath: string | Path, newPath: string): boolean;

Renames a file or directory.

Parameters#

Parameter Type Description
oldPath string | Path The current path of the file or directory. Supports: - A string path (e.g., "/file.txt"). - A Path object specifying storage { fs: "sd", path: "/file.txt" }.
newPath string The new path.

Returns#

boolean

true if the rename operation was successful, otherwise false.

storage.remove()#

storage.remove(path: string | Path): boolean;

Deletes a file or directory.

Parameters#

Parameter Type Description
path string | Path The path of the file or directory to delete. Supports: - A string path (e.g., "/file.txt"). - A Path object specifying storage { fs: "sd", path: "/file.txt" }.

Returns#

boolean

true if the delete operation was successful, otherwise false.

storage.mkdir()#

storage.mkdir(path: string | Path): boolean;

Creates a directory, including parent directories if necessary.

Parameters#

Parameter Type Description
path string | Path The path to the directory.

Returns#

boolean

true if the directory was successfully created, otherwise false.

storage.rmdir()#

storage.rmdir(path: string | Path): boolean;

Removes an empty directory.

Parameters#

Parameter Type Description
path string | Path The path to the directory.

Returns#

boolean

true if the directory was successfully removed, otherwise false.

subghz#

Sub-GHz communication.

This module allows interaction with Sub-GHz frequencies for reading and transmitting data.

Example#

const subghz = require("subghz");

// Set frequency to 433 MHz
subghz.setFrequency(433);

// Read incoming signal for 5 seconds
const receivedData = subghz.read(5);
console.log("Received Data:", receivedData);

// Transmit a stored signal file
const success = subghz.transmitFile("/plug1_on.sub");
if (success) {
  console.log("Transmission successful!");
}

subghz functions#

subghz.setFrequency()#

subghz.setFrequency(freq: number): void;

Sets the frequency for Sub-GHz communication.

Parameters#

Parameter Type Description
freq number Frequency in MHz (e.g., 433 for 433 MHz).

Returns#

void

subghz.read()#

subghz.read(timeoutSeconds: number): string;

Reads an incoming signal.

Parameters#

Parameter Type Description
timeoutSeconds number Maximum time in seconds to wait for a signal.

Returns#

string

The received signal as a string.

subghz.readRaw()#

subghz.readRaw(timeoutSeconds: number): string;

Reads raw incoming signal data.

Parameters#

Parameter Type Description
timeoutSeconds number Maximum time in seconds to wait for a signal.

Returns#

string

The raw received signal as a string.

subghz.transmitFile()#

subghz.transmitFile(filename: string): boolean;

Transmits a saved signal from a file.

Parameters#

Parameter Type Description
filename string The path to the file containing the signal to transmit.

Returns#

boolean

true if the transmission was successful, otherwise false.

wifi#

Wi-Fi connection and HTTP requests.

Example#

const wifi = require("wifi");

if (!wifi.connected()) {
  wifi.connect("MySSID", 10, "password123");
}

const networks = wifi.scan();
console.log("Available Networks:", networks);

const response = wifi.httpFetch("https://example.com/api", {
  method: "GET",
  headers: { "Content-Type": "application/json" },
});
console.log(response.body);

WiFi functions#

wifi.connected()#

wifi.connected(): boolean;

Checks if the device is connected to a Wi-Fi network.

Returns#

boolean

true if connected, otherwise false.

wifi.connect()#

wifi.connect(
  ssid: string,
  timeoutInSeconds: number,
  password: string,
): boolean;

Connects to a Wi-Fi network.

Parameters#

Parameter Type Description
ssid string The name of the Wi-Fi network (SSID).
timeoutInSeconds number The time (in seconds) to wait for a connection before failing.
password string The Wi-Fi password.

Returns#

boolean

true if successfully connected, otherwise false.

wifi.connectDialog()#

wifi.connectDialog(): void;

Opens a dialog to select and connect to a Wi-Fi network.

Returns#

void

wifi.disconnect()#

wifi.disconnect(): void;

Disconnects from the current Wi-Fi network.

Returns#

void

wifi.scan()#

wifi.scan(): {
  encryptionType:
 | "OPEN"
 | "WEP"
 | "WPA_PSK"
 | "WPA2_PSK"
 | "WPA_WPA2_PSK"
 | "ENTERPRISE"
 | "WPA2_ENTERPRISE"
 | "WPA3_PSK"
 | "WPA2_WPA3_PSK"
 | "WAPI_PSK"
 | "WPA3_ENT_192"
 | "MAX";
  SSID: string;
  MAC: string;
}[];

Scans for available Wi-Fi networks.

Returns#

{ encryptionType: | "OPEN" | "WEP" | "WPA_PSK" | "WPA2_PSK" | "WPA_WPA2_PSK" | "ENTERPRISE" | "WPA2_ENTERPRISE" | "WPA3_PSK" | "WPA2_WPA3_PSK" | "WAPI_PSK" | "WPA3_ENT_192" | "MAX"; SSID: string; MAC: string; }[]

An array of available networks, each containing:

  • encryptionType: The type of encryption used (e.g., WPA2, WEP).
  • SSID: The name of the network.
  • MAC: The MAC address of the access point.

wifi.httpFetch()#

Call Signature#

wifi.httpFetch(
  url: string,
  options?: {
    method:
 | "GET"
 | "POST"
 | "DELETE"
 | "PATCH"
 | "PUT"
 | "HEAD"
 | "OPTIONS"
 | "TRACE"
 | "CONNECT";
    body: string;
    binaryResponse: false;
    headers: string[] | [string, string][] | Record<string, string>;
  },
): {
  status: number;
  ok: boolean;
  body: string;
};

Performs an HTTP request.

Parameters#

Parameter Type Description
url string The URL to fetch.
options? { method: | "GET" | "POST" | "DELETE" | "PATCH" | "PUT" | "HEAD" | "OPTIONS" | "TRACE" | "CONNECT"; body: string; binaryResponse: false; headers: string[] | [string, string][] | Record<string, string>; } Request options including method, body, and headers.
options.method? | "GET" | "POST" | "DELETE" | "PATCH" | "PUT" | "HEAD" | "OPTIONS" | "TRACE" | "CONNECT" -
options.body? string -
options.binaryResponse? false -
options.headers? string[] | [string, string][] | Record<string, string> -

Returns#

{
  status: number;
  ok: boolean;
  body: string;
}

An object containing:

  • status: The HTTP response status code (e.g., 200, 404).
  • ok: true if the response status is 200-299, otherwise false.
  • body: The response body as a string.
Name Type
status number
ok boolean
body string

Call Signature#

wifi.httpFetch(
  url: string,
  options?: {
    method:
 | "GET"
 | "POST"
 | "DELETE"
 | "PATCH"
 | "PUT"
 | "HEAD"
 | "OPTIONS"
 | "TRACE"
 | "CONNECT";
    body: string;
    responseType: "string";
    headers: string[] | [string, string][] | Record<string, string>;
  },
): {
  status: number;
  ok: boolean;
  body: string;
};

Performs an HTTP request.

Parameters#

Parameter Type Description
url string The URL to fetch.
options? { method: | "GET" | "POST" | "DELETE" | "PATCH" | "PUT" | "HEAD" | "OPTIONS" | "TRACE" | "CONNECT"; body: string; responseType: "string"; headers: string[] | [string, string][] | Record<string, string>; } Request options including method, body, and headers.
options.method? | "GET" | "POST" | "DELETE" | "PATCH" | "PUT" | "HEAD" | "OPTIONS" | "TRACE" | "CONNECT" -
options.body? string -
options.responseType? "string" -
options.headers? string[] | [string, string][] | Record<string, string> -

Returns#

{
  status: number;
  ok: boolean;
  body: string;
}

An object containing:

  • status: The HTTP response status code (e.g., 200, 404).
  • ok: true if the response status is 200-299, otherwise false.
  • body: The response body as a string.
Name Type
status number
ok boolean
body string

Call Signature#

wifi.httpFetch(
  url: string,
  options?: {
    method:
 | "GET"
 | "POST"
 | "DELETE"
 | "PATCH"
 | "PUT"
 | "HEAD"
 | "OPTIONS"
 | "TRACE"
 | "CONNECT";
    body: string;
    responseType: "binary";
    headers: string[] | [string, string][] | Record<string, string>;
  },
): {
  status: number;
  ok: boolean;
  body: Uint8Array;
};

Performs an HTTP request.

Parameters#

Parameter Type Description
url string The URL to fetch.
options? { method: | "GET" | "POST" | "DELETE" | "PATCH" | "PUT" | "HEAD" | "OPTIONS" | "TRACE" | "CONNECT"; body: string; responseType: "binary"; headers: string[] | [string, string][] | Record<string, string>; } Request options including method, body, and headers.
options.method? | "GET" | "POST" | "DELETE" | "PATCH" | "PUT" | "HEAD" | "OPTIONS" | "TRACE" | "CONNECT" -
options.body? string -
options.responseType? "binary" -
options.headers? string[] | [string, string][] | Record<string, string> -

Returns#

{
  status: number;
  ok: boolean;
  body: Uint8Array;
}

An object containing:

  • status: The HTTP response status code (e.g., 200, 404).
  • ok: true if the response status is 200-299, otherwise false.
  • body: The response body as a string.
Name Type
status number
ok boolean
body Uint8Array

Call Signature#

wifi.httpFetch(
  url: string,
  options?: {
    method:
 | "GET"
 | "POST"
 | "DELETE"
 | "PATCH"
 | "PUT"
 | "HEAD"
 | "OPTIONS"
 | "TRACE"
 | "CONNECT";
    body: string;
    responseType: "string" | "binary";
    headers: string[] | [string, string][] | Record<string, string>;
  },
): {
  status: number;
  ok: boolean;
  body: string | Uint8Array;
};

Performs an HTTP request.

Parameters#

Parameter Type Description
url string The URL to fetch.
options? { method: | "GET" | "POST" | "DELETE" | "PATCH" | "PUT" | "HEAD" | "OPTIONS" | "TRACE" | "CONNECT"; body: string; responseType: "string" | "binary"; headers: string[] | [string, string][] | Record<string, string>; } Request options including method, body, and headers.
options.method? | "GET" | "POST" | "DELETE" | "PATCH" | "PUT" | "HEAD" | "OPTIONS" | "TRACE" | "CONNECT" -
options.body? string -
options.responseType? "string" | "binary" -
options.headers? string[] | [string, string][] | Record<string, string> -

Returns#

{
  status: number;
  ok: boolean;
  body: string | Uint8Array;
}

An object containing:

  • status: The HTTP response status code (e.g., 200, 404).
  • ok: true if the response status is 200-299, otherwise false.
  • body: The response body as a string.
Name Type
status number
ok boolean
body string | Uint8Array