awtrix-ts

TS wrapper for Awtrix API.

Awtrix API

The Awtrix class provides a TypeScript interface for interacting with the Awtrix device API. It supports device control, settings management, notifications, app switching, indicators, moodlight, and more.

Installation

npm i --save awtrix-ts

Usage

import { Awtrix } from 'awtrix-ts';

const awtrix = new Awtrix(new URL('http://your-awtrix-device-ip'));

await awtrix.power(true); // Turn device on
await awtrix.notify({ text: 'Hello World!' }); // Send a notification

Methods

power(power: boolean)

Turn the device on or off.

await awtrix.power(true); // Turn on
await awtrix.power(false); // Turn off

reboot()

Reboot the device.

await awtrix.reboot();

sleep(time: number)

Put the device to sleep for a specified time (in seconds).

await awtrix.sleep(5); // Sleep for 5 seconds

settings(settings: Settings)

Update device settings.

await awtrix.settings({
  automaticAppSwitching: false,
  globalTextColor: [0, 255, 0],
  // ...other settings
});

resetDefaultSettings()

Resets the device settings back to default.

await awtrix.resetDefaultSettings();

erase()

Factory resets the device. Does not modify WiFi settings.

await awtrix.erase();

screen()

Get the current screen content.

const screen = await awtrix.screen();

stats()

Retrieve device statistics.

console.log(await awtrix.stats());

effects()

List available effects.

const effects = await awtrix.effects();

transitions()

List available transitions.

const transitions = await awtrix.transitions();

loop()

Get the app loop configuration.

console.log(await awtrix.loop());

playMelody(rtttl: string)

Play a melody using RTTTL format.

await awtrix.playMelody('d=4,o=5,b=140:c6,e6,g6');

playMelodyFile(name: string)

Play a melody file by name.

await awtrix.playMelodyFile('melody.mp3');

setIndicator(indicator: IndicatorPayload)

Set an indicator LED.

await awtrix.setIndicator({
  color: [255, 0, 0],
  position: awtrix.Indicators.UpperRight,
  // blink: 500,
  // fade: 1000,
});

clearIndicator(indicator: Indicators)

Clear an indicator LED.

await awtrix.clearIndicator(awtrix.Indicators.UpperRight);

moodlight(setting: MoodlightColor | MoodlightKelvin)

Set moodlight color or temperature.

await awtrix.moodlight({ brightness: 170, kelvin: 2300 });

await awtrix.moodlight({ brightness: 170, color: '#FF00FF' });

clearMoodlight()

Turn off moodlight.

await awtrix.clearMoodlight();

notify(notification: Interaction)

Send a notification.

await awtrix.notify({
  text: 'Hello World!',
  icon: '3049',
  pushIcon: awtrix.PushIcon.MoveOnce,
  effect: awtrix.Effects.PlasmaCloud,
  repeat: 5,
});

dismissNotification()

Dismiss the current notification.

await awtrix.dismissNotification();

app(name: string, app: Interaction)

Send a custom app payload.

await awtrix.app('demoApp', {
  text: 'This is a custom app!',
  icon: '1000',
  repeat: 5,
  duration: 3000,
  effect: awtrix.Effects.TwinklingStars,
  scrollSpeed: 150,
});

launchApp(name: string)

Launch an app by name.

await awtrix.launchApp('demoApp');

nextApp(), previousApp()

Switch between apps.

await awtrix.nextApp();
await setTimeout(2000);
await awtrix.previousApp();

deleteApp(name: string)

Delete a custom app.

await clock.deleteApp('myApp');

Progress Bar Example

Display a progress bar using a custom app:

for (let i = 0; i <= 100; i++) {
  if (i % 5 === 0) {
    await awtrix.app('Progress', {
      text: `${i}%`,
      progress: i,
      duration: 1,
    });
    if (i === 0) {
      await awtrix.launchApp('Progress');
    }
    if (i === 100) {
      await awtrix.app('Progress', {
        text: 'Done!',
        color: [0, 255, 0],
      });
    }
    await setTimeout(500);
  }
}

Draw Pixels

Draw shapes on the display:

await clock.notify({
  draw: [
    new clock.draw.Pixel(0, 0, [255, 0, 0]),
    new clock.draw.Line(0, 1, 15, 1, [0, 255, 0]),
    new clock.draw.Rectangle(2, 2, 12, 6, [0, 0, 255]),
    new clock.draw.FilledRectangle(3, 3, 10, 4, [255, 255, 0]),
    new clock.draw.Circle(8, 1, 3, [0, 255, 255]),
    new clock.draw.FilledCircle(8, 3, 2, [255, 0, 255]),
    new clock.draw.Text(0, 1, 'AWTRIX', [255, 255, 255]),
  ],
});

Other

• All API calls are asynchronous and return Promises.
• The class exposes enums for transitions, indicators, and effects for convenience.