awtrix-ts 1.0.0

package/README.md

@@ -0,0 +1,252 @@
+# 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.
+
+### Usage
+
+```typescript
+import { Awtrix } from './api.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.
+
+```typescript
+await clock.power(true); // Turn on
+await clock.power(false); // Turn off
+```
+
+#### reboot()
+
+Reboot the device.
+
+```typescript
+await clock.reboot();
+```
+
+#### sleep(time: number)
+
+Put the device to sleep for a specified time (in seconds).
+
+```typescript
+await clock.sleep(5); // Sleep for 5 seconds
+```
+
+#### settings(settings: Settings)
+
+Update device settings.
+
+```typescript
+await clock.settings({
+  automaticAppSwitching: false,
+  globalTextColor: [0, 255, 0],
+  // ...other settings
+});
+```
+
+#### resetDefaultSettings()
+
+Resets the device settings back to default.
+
+```typescript
+await clock.resetDefaultSettings();
+```
+
+#### erase()
+
+Factory resets the device. Does not modify WiFi settings.
+
+```typescript
+await clock.erase();
+```
+
+#### screen()
+
+Get the current screen content.
+
+```typescript
+const screen = await clock.screen();
+```
+
+#### stats()
+
+Retrieve device statistics.
+
+```typescript
+console.log(await clock.stats());
+```
+
+#### effects()
+
+List available effects.
+
+```typescript
+const effects = await clock.effects();
+```
+
+#### transitions()
+
+List available transitions.
+
+```typescript
+const transitions = await clock.transitions();
+```
+
+#### loop()
+
+Get the app loop configuration.
+
+```typescript
+console.log(await clock.loop());
+```
+
+#### playMelody(rtttl: string)
+
+Play a melody using RTTTL format.
+
+```typescript
+await clock.playMelody('d=4,o=5,b=140:c6,e6,g6');
+```
+
+#### playMelodyFile(name: string)
+
+Play a melody file by name.
+
+```typescript
+await clock.playMelodyFile('melody.mp3');
+```
+
+#### setIndicator(indicator: IndicatorPayload)
+
+Set an indicator LED.
+
+```typescript
+await clock.setIndicator({
+  color: [255, 0, 0],
+  position: clock.Indicators.UpperRight,
+  // blink: 500,
+  // fade: 1000,
+});
+```
+
+#### clearIndicator(indicator: Indicators)
+
+Clear an indicator LED.
+
+```typescript
+await clock.clearIndicator(clock.Indicators.UpperRight);
+```
+
+#### moodlight(setting: MoodlightColor | MoodlightKelvin)
+
+Set moodlight color or temperature.
+
+```typescript
+await clock.moodlight({ r: 255, g: 255, b: 255 });
+```
+
+#### clearMoodlight()
+
+Turn off moodlight.
+
+```typescript
+await clock.clearMoodlight();
+```
+
+#### notify(notification: Interaction)
+
+Send a notification.
+
+```typescript
+await clock.notify({
+  text: 'Hello World!',
+  icon: '3049',
+  pushIcon: clock.PushIcon.MoveOnce,
+  effect: clock.Effects.PlasmaCloud,
+  repeat: 5,
+});
+```
+
+#### dismissNotification()
+
+Dismiss the current notification.
+
+```typescript
+await clock.dismissNotification();
+```
+
+#### app(name: string, app: Interaction)
+
+Send a custom app payload.
+
+```typescript
+await clock.app('demoApp', {
+  text: 'This is a custom app!',
+  icon: '1000',
+  repeat: 5,
+  duration: 3000,
+  effect: clock.Effects.TwinklingStars,
+  scrollSpeed: 150,
+});
+```
+
+#### launchApp(name: string)
+
+Launch an app by name.
+
+```typescript
+await clock.launchApp('demoApp');
+```
+
+#### nextApp(), previousApp()
+
+Switch between apps.
+
+```typescript
+await clock.nextApp();
+await setTimeout(2000);
+await clock.previousApp();
+```
+
+#### Progress Bar Example
+
+Display a progress bar using a custom app:
+
+```typescript
+for (let i = 0; i <= 100; i++) {
+  if (i % 5 === 0) {
+    await clock.app('Progress', {
+      text: `${i}%`,
+      progress: i,
+      duration: 1,
+    });
+    if (i === 0) {
+      await clock.launchApp('Progress');
+    }
+    if (i === 100) {
+      await clock.app('Progress', {
+        text: `Done!`,
+        color: [0, 255, 0],
+      });
+    }
+    await setTimeout(500);
+  }
+}
+```
+
+### Other
+
+- All API calls are asynchronous and return Promises.
+- The class exposes enums for transitions, indicators, and effects for convenience.

package/api.ts

@@ -0,0 +1,177 @@
+import { setTimeout } from 'node:timers/promises';
+import * as interaction from './interaction.ts';
+import * as transitions from './transitions.ts';
+import * as indicators from './indicators.ts';
+import * as settings from './settings.ts';
+import './stats.d.ts';
+import './moodlight.d.ts';
+
+class Awtrix {
+    #bootTime = 15 * 1000;
+    url: string;
+    Transitions = transitions.Transition;
+    Indicators = indicators.Indicator;
+    Effects = interaction.Effect;
+    PushIcon = interaction.PushIcon;
+
+    constructor(url: URL) {
+        this.url = url.href + 'api';
+    }
+
+    async power(power: boolean): Promise<void> {
+        await this.post('power', { power });
+    }
+
+    async sleep(time: number): Promise<void> {
+        await Promise.all([
+            await this.post('sleep', { sleep: time }),
+            await setTimeout((time * 1000) + this.#bootTime)
+        ]);
+    }
+
+    async reboot(): Promise<void> {
+        await Promise.all([
+            await this.post('reboot'),
+            await setTimeout(this.#bootTime)
+        ]);
+    }
+
+    async settings(settings: settings.Settings): Promise<void> {
+        await this.post('settings', {
+            ATIME: settings.appTime,
+            TEFF: settings.transitionEffect,
+            TSPEED: settings.transitionSpeed,
+            TCOL: settings.globalTextColor,
+            TMODE: settings.timeAppStyle,
+            CHCOL: settings.calendarHeaderColor,
+            CBCOL: settings.calendarBodyColor,
+            CTCOL: settings.calendarTextColor,
+            WD: settings.weekdayDisplay,
+            WDCA: settings.activeWeekdayColor,
+            WDCI: settings.inactiveWeekdayColor,
+            BRI: settings.matrixBrightness,
+            ABRI: settings.automaticBrightnessControl,
+            ATRANS: settings.automaticAppSwitching,
+            CCORRECTION: settings.colorCorrection,
+            CTEMP: settings.colorTemperature,
+            TFORMAT: settings.timeFormat,
+            DFORMAT: settings.dateFormat,
+            SOM: settings.startWeekOnMonday,
+            CEL: settings.celsiusTemperature,
+            BLOCKN: settings.blockNavigationKeys,
+            UPPERCASE: settings.uppercaseText,
+            TIME_COL: settings.timeAppTextColor,
+            DATE_COL: settings.dateAppTextColor,
+            TEMP_COL: settings.temperatureAppTextColor,
+            HUM_COL: settings.humidityAppTextColor,
+            BAT_COL: settings.batteryAppTextColor,
+            SSPEED: settings.scrollSpeedModification,
+            TIM: settings.enableTimeApp,
+            DAT: settings.enableDateApp,
+            HUM: settings.enableHumidityApp,
+            TEMP: settings.enableTemperatureApp,
+            BAT: settings.enableBatteryApp,
+            MATP: settings.matrixPower,
+            VOL: settings.volume,
+            OVERLAY: settings.globalEffectOverlay
+        } as settings.SettingsPayload);
+    }
+
+    async resetDefaultSettings(): Promise<void> {
+        await this.post('resetSettings');
+    }
+
+    async erase(): Promise<void> {
+        await this.post('erase');
+    }
+
+    async screen(): Promise<string> {
+        return this.get('screen');
+    }
+
+    async stats(): Promise<Stats> {
+        return this.get('stats');
+    }
+
+    async effects(): Promise<interaction.Effect[]> {
+        return this.get('effects');
+    }
+
+    async transitions(): Promise<transitions.Transitions[]> {
+        return this.get('transitions');
+    }
+
+    async loop(): Promise<{ [app: string]: number; }> {
+        return this.get('loop');
+    }
+
+    async playMelody(rtttl: string): Promise<void> {
+        await this.post('rtttl', { rtttl });
+    }
+
+    async playMelodyFile(name: string): Promise<void> {
+        await this.post('sound', { sound: name });
+    }
+
+    async setIndicator(indicator: indicators.IndicatorPayload): Promise<void> {
+        await this.post('indicator' + indicator.position, {
+            color: indicator.color,
+            blink: indicator.blink,
+            fade: indicator.fade
+        });
+    }
+
+    async clearIndicator(indicator: indicators.Indicators): Promise<void> {
+        await this.post('indicator' + indicator);
+    }
+
+    async moodlight(setting: MoodlightColor | MoodlightKelvin): Promise<void> {
+        await this.post('moodlight', setting);
+    }
+
+    async clearMoodlight(): Promise<void> {
+        await this.post('moodlight');
+    }
+
+    async notify(notification: interaction.Interaction): Promise<void> {
+        await this.post('notify', notification);
+    }
+
+    async dismissNotification(): Promise<void> {
+        await this.post('notify/dismiss');
+    }
+
+    async app(name: string, app: interaction.Interaction): Promise<void> {
+        await this.post(`custom?name=${name}`, app);
+    }
+
+    async launchApp(name: string): Promise<void> {
+        await this.post('switch', { name });
+    }
+
+    async nextApp(): Promise<void> {
+        await this.post('nextapp');
+    }
+
+    async previousApp(): Promise<void> {
+        await this.post('previousapp');
+    }
+
+    async get(endpoint: string): Promise<any> {
+        const response = await fetch(`${this.url}/${endpoint}`);
+        const data: any = await response.json();
+        return data;
+    }
+
+    async post(endpoint: string, data?: object): Promise<void> {
+        await fetch(`${this.url}/${endpoint}`, {
+            method: 'POST',
+            headers: {
+                'Content-Type': 'application/json',
+            },
+            ...(data ? { body: JSON.stringify(data) } : {}),
+        });
+    }
+}
+
+export { Awtrix };

package/indicators.ts

@@ -0,0 +1,15 @@
+export interface IndicatorPayload {
+  position: Indicators;
+  color: string | number[];
+  blink?: number; // interval in ms
+  fade?: number; // duration in ms
+}
+
+const Indicator = {
+  UpperRight: 1,
+  CenterRight: 2,
+  BottomRight: 3
+} as const;
+
+export type Indicators = typeof Indicator[keyof typeof Indicator];
+export { Indicator };

package/interaction.ts

@@ -0,0 +1,75 @@
+export interface Interaction {
+    text?: string; // The text to display
+    textCase?: number; // Changes the Uppercase setting. 0=global setting, 1 = forces uppercase; 2 = shows as sent.
+    topText?: boolean; // Draw the text on top.
+    textOffset?: number; // Sets an offset for the x position of a starting text.
+    center?: boolean; // Centers a short, non-scrollable text.
+    color?: string | number[]; // The text, bar or line color.
+    gradient?: (string | number)[]; // Colorizes the text in a gradient of two given colors.
+    blinkText?: number; // Blinks the text in an given interval in ms, not compatible with gradient or rainbow.
+    fadeText?: number; // Fades the text on and off in an given interval, not compatible with gradient or rainbow.
+    background?: string | number[]; // Sets a background color.
+    rainbow?: boolean; // Fades each letter in the text differently through the entire RGB spectrum.
+    icon?: string; // The icon ID or filename (without extension) to display on the app. You can also send a 8x8 jpg as Base64 string.
+    pushIcon?: PushIcon; // 0 = Icon doesn't move. 1 = Icon moves with text and will not appear again. 2 = Icon moves with text but appears again when the text starts to scroll again.
+    repeat?: number; // Sets how many times the text should be scrolled through the matrix before the app ends.
+    duration?: number; // Sets how long the app or notification should be displayed.
+    hold?: boolean; // Set it to true, to hold your notification on top until you press the middle button or dismiss it via HomeAssistant. This key only belongs to notification.
+    sound?: string; // The filename of your RTTTL ringtone file placed in the MELODIES folder (without extension). Or the 4 digit number of your MP3 if you're using a DFplayer.
+    rtttl?: string; // Allows to send the RTTTL sound string with JSON.
+    loopSound?: boolean; // Loops the sound or RTTTL as long as the notification is running.
+    bar?: number[]; // Draws a bargraph. Without icon maximum 16 values, with icon 11 values.
+    line?: number[]; // Draws a linechart. Without icon maximum 16 values, with icon 11 values.
+    autoscale?: boolean; // Enables or disables autoscaling for bar and linechart.
+    barBC?: string | number[]; // Backgroundcolor of the bars.
+    progress?: number; // Shows a progress bar. Value can be 0–100.
+    progressC?: string | number[]; // The color of the progress bar.
+    progressBC?: string | number[]; // The color of the progress bar background.
+    pos?: number; // Defines the position of your custom page in the loop, starting at 0 for the first position. This will only apply with your first push. This function is experimental.
+    draw?: object[]; // Array of drawing instructions. Each object represents a drawing command. See the drawing instructions below.
+    lifetime?: number; // Removes the custom app when there is no update after the given time in seconds.
+    lifetimeMode?: number; // 0 = deletes the app, 1 = marks it as staled with a red rectangle around the app.
+    stack?: boolean; // Defines if the notification will be stacked. false will immediately replace the current notification.
+    wakeup?: boolean; // If the Matrix is off, the notification will wake it up for the time of the notification.
+    noScroll?: boolean; // Disables the text scrolling.
+    clients?: string[]; // Allows forwarding a notification to other AWTRIX devices. Use the MQTT prefix for MQTT and IP addresses for HTTP.
+    scrollSpeed?: number; // Modifies the scroll speed. Enter a percentage value of the original scroll speed.
+    effect?: Effect; // Shows an effect as background. The effect can be removed by sending an empty string for effect.
+    effectSettings?: Record<string, unknown>; // Changes color and speed of the effect.
+    save?: boolean; // Saves your custom app into flash and reloads it after boot. Avoid this for custom apps with high update frequencies because the ESP's flash memory has limited write cycles.
+    overlay?: string; // Sets an effect overlay (cannot be used with global overlays).
+}
+
+const PushIcon = {
+    Static: 0,
+    MoveOnce: 1,
+    MoveRepeat: 2
+} as const;
+
+type PushIcon = typeof PushIcon[keyof typeof PushIcon];
+
+const Effect = {
+    BrickBreaker: "BrickBreaker",
+    Checkerboard: "Checkerboard",
+    Fireworks: "Fireworks",
+    PingPong: "PingPong",
+    Radar: "Radar",
+    Ripple: "Ripple",
+    Snake: "Snake",
+    TwinklingStars: "TwinklingStars",
+    TheaterChase: "TheaterChase",
+    ColorWaves: "ColorWaves",
+    SwirlOut: "SwirlOut",
+    SwirlIn: "SwirlIn",
+    LookingEyes: "LookingEyes",
+    Matrix: "Matrix",
+    Pacifica: "Pacifica",
+    Plasma: "Plasma",
+    PlasmaCloud: "PlasmaCloud",
+    MovingLine: "MovingLine",
+    Fade: "Fade"
+} as const;
+
+type Effect = typeof Effect[keyof typeof Effect];
+
+export { PushIcon, Effect };

package/moodlight.d.ts

@@ -0,0 +1,9 @@
+interface MoodlightKelvin {
+  brightness: number;
+  kelvin: number;
+}
+
+interface MoodlightColor {
+  brightness: number;
+  color: string;
+}

package/package.json

@@ -0,0 +1,18 @@
+{
+  "name": "awtrix-ts",
+  "version": "1.0.0",
+  "description": "TypeScript API for Awtrix LED Matrix Display",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/gledrich/awtrix-ts.git"
+  },
+  "main": "api.ts",
+  "type": "module",
+  "devDependencies": {
+    "eslint": "^9.39.2",
+    "eslint-config": "github:7digital/eslint-config"
+  },
+  "dependencies": {
+    "@types/node": "^25.0.3"
+  }
+}

package/settings.ts

@@ -0,0 +1,79 @@
+import * as transitions from './transitions.ts';
+
+export interface SettingsPayload {
+  ATIME?: number; // Duration an app is displayed in seconds.
+  TEFF?: number; // Choose between app transition effects.
+  TSPEED?: number; // Time taken for the transition to the next app in milliseconds.
+  TCOL?: string | number[]; // Global text color.
+  TMODE?: number; // Changes the time app style.
+  CHCOL?: string | number[]; // Calendar header color of the time app.
+  CBCOL?: string | number[]; // Calendar body color of the time app.
+  CTCOL?: string | number[]; // Calendar text color in the time app.
+  WD?: boolean; // Enable or disable the weekday display.
+  WDCA?: string | number[]; // Active weekday color.
+  WDCI?: string | number[]; // Inactive weekday color.
+  BRI?: number; // Matrix brightness.
+  ABRI?: boolean; // Automatic brightness control.
+  ATRANS?: boolean; // Automatic switching to the next app.
+  CCORRECTION?: number[]; // Color correction for the matrix.
+  CTEMP?: number[]; // Color temperature for the matrix.
+  TFORMAT?: string; // Time format for the TimeApp.
+  DFORMAT?: string; // Date format for the DateApp.
+  SOM?: boolean; // Start the week on Monday.
+  CEL?: boolean; // Shows the temperature in Celsius (Fahrenheit when false).
+  BLOCKN?: boolean; // Block physical navigation keys (still sends input to MQTT).
+  UPPERCASE?: boolean; // Display text in uppercase.
+  TIME_COL?: string | number[]; // Text color of the time app. Use 0 for global text color.
+  DATE_COL?: string | number[]; // Text color of the date app. Use 0 for global text color.
+  TEMP_COL?: string | number[]; // Text color of the temperature app. Use 0 for global text color.
+  HUM_COL?: string | number[]; // Text color of the humidity app. Use 0 for global text color.
+  BAT_COL?: string | number[]; // Text color of the battery app. Use 0 for global text color.
+  SSPEED?: number; // Scroll speed modification.
+  TIM?: boolean; // Enable or disable the native time app (requires reboot).
+  DAT?: boolean; // Enable or disable the native date app (requires reboot).
+  HUM?: boolean; // Enable or disable the native humidity app (requires reboot).
+  TEMP?: boolean; // Enable or disable the native temperature app (requires reboot).
+  BAT?: boolean; // Enable or disable the native battery app (requires reboot).
+  MATP?: boolean; // Enable or disable the matrix. Similar to power endpoint but without the animation.
+  VOL?: number; // Allows to set the volume of the buzzer and DFplayer.
+  OVERLAY?: string; // Sets a global effect overlay (cannot be used with app specific overlays).
+}
+
+export interface Settings {
+  appTime?: number;
+  transitionEffect?: transitions.Transitions;
+  transitionSpeed?: number;
+  globalTextColor?: string | number[];
+  timeAppStyle?: number;
+  calendarHeaderColor?: string | number[];
+  calendarBodyColor?: string | number[];
+  calendarTextColor?: string | number[];
+  weekdayDisplay?: boolean;
+  activeWeekdayColor?: string | number[];
+  inactiveWeekdayColor?: string | number[];
+  matrixBrightness?: number;
+  automaticBrightnessControl?: boolean;
+  automaticAppSwitching?: boolean;
+  colorCorrection?: number[];
+  colorTemperature?: number[];
+  timeFormat?: string;
+  dateFormat?: string;
+  startWeekOnMonday?: boolean;
+  celsiusTemperature?: boolean;
+  blockNavigationKeys?: boolean;
+  uppercaseText?: boolean;
+  timeAppTextColor?: string | number[];
+  dateAppTextColor?: string | number[];
+  temperatureAppTextColor?: string | number[];
+  humidityAppTextColor?: string | number[];
+  batteryAppTextColor?: string | number[];
+  scrollSpeedModification?: number;
+  enableTimeApp?: boolean;
+  enableDateApp?: boolean;
+  enableHumidityApp?: boolean;
+  enableTemperatureApp?: boolean;
+  enableBatteryApp?: boolean;
+  matrixPower?: boolean;
+  volume?: number;
+  globalEffectOverlay?: string;
+}

package/stats.d.ts

@@ -0,0 +1,22 @@
+interface Stats {
+    bat: number;
+    bat_raw: number;
+    type: number;
+    lux: number;
+    ldr_raw: number;
+    ram: number;
+    bri: number;
+    temp: number;
+    hum: number;
+    uptime: number;
+    wifi_signal: number;
+    messages: number;
+    version: string;
+    indicator1: boolean;
+    indicator2: boolean;
+    indicator3: boolean;
+    app: string;
+    uid: string;
+    matrix: boolean;
+    ip_address: string;
+}

package/test.js

@@ -0,0 +1,8 @@
+import { setTimeout } from 'node:timers/promises';
+import { Awtrix } from './api.ts';
+
+const clockUrl = 'http://192.168.1.109';
+
+const clock = new Awtrix(new URL(clockUrl));
+
+await clock.resetDefaultSettings();

package/transitions.ts

@@ -0,0 +1,17 @@
+const Transition = {
+  Random: 0,
+  Slide: 1,
+  Dim: 2,
+  Zoom: 3,
+  Rotate: 4,
+  Pixelate: 5,
+  Curtain: 6,
+  Ripple: 7,
+  Blink: 8,
+  Reload: 9,
+  Fade: 10
+} as const;
+
+export type Transitions = keyof typeof Transition;
+
+export { Transition };