Node.js API Client Module

Hi all,

I’ve been tinkering a bit with my new Tidbyt. I’ve build a full featured, promise-based, zero-dependency module to help you integrate.


You can install the package with npm:

> npm install tidbyt


const Tidbyt = require('tidbyt')

async function main() {
    const deviceId = process.argv[2]
    const tidbyt = new Tidbyt(process.env.TIDBYT_API_TOKEN)

    // get our requested device
    const device = await tidbyt.devices.get(deviceId)
    const { displayName, lastSeen } = device

    console.log(displayName, `Last Seen: (${lastSeen})`)

    // get a list of officially available apps
    // return as map so we can lookup app name/descriptions by id
    const apps = await tidbyt.apps.list({ asMap: true })

    // get the list of installations for this device
    const installations = await device.installations.list()

    for (const { id, appID } of installations) {
        const {
            name = 'Custom',
            description = `Unlike a regular Tidbyt app, this "installation" was pushed to ${displayName} via Tidbyt's API.`,
        } = apps.get(appID) || {}

        console.log(`  ${name} - ${id}`)
        console.log(`      ${description}`)

I’ve already used this module to build an application that can render star files and push updates to custom installations on a cron schedule. I’m using this library in conjunction with the Twitter Followers app I published to refresh and display the count a few times a day.

Things are fairly new, but I’m open to any suggestions or feedback.

Thanks and have fun tinkering!


Hey @drudge,

This rocks! Thanks so much for putting this together and sharing here. Would love to know if you have any feedback on the public API. Let us know if there is anything you’d like to see and we’ll do our best to support it. Excited to see what else you create :heart_eyes:

1 Like

Hi @mark,

Thanks! I’m loving my Tidbyt, you all far exceeded my expectations with the device!

Integrating with the API was quite straightforward and the base functionality is great. Some things that I’ve been thinking about since using it:

1. Ability to set Brightness to 0 or disable the screen

This would be very handy in the Homebridge plugin as it would allow Homekit automations to turn off the device’s screen. I would love this for my “Good night” scene.

2. Background push for applets with installations IDs

Right now all pushes interrupt the current rotation. I think this is a perfectly acceptable default, but it would be nice to have more granular control.

For example, I have an integration that pulls some metrics from our e-commerce website and shows them every 15 minutes. These metrics aren’t updated in real-time so I rather the refreshed data simply appear during the applet’s regular place in the rotation.

3. Previews for custom installations

Fetching a preview for installations added through the API does not seem to work for me. The following response is returned from the endpoint:

    "code": 2,
    "message": "getting existing device from Firestore: rpc error: code = InvalidArgument desc = Document name \"projects/tidbyt/databases/(default)/documents/Apps/\" has invalid trailing \"/\".",
    "details": []

4. Rotation Configuration

I’ve noticed that it is possible to configure the order of applets in the rotation using the mobile app. I’d love to have that control in the API. It would allow adding new installations in a specific spot or altering the “priority” of existing installations as they are updated with newer data.

5. Ability to create new installations from available apps

This would be useful to allow scripts to leverage the awesome built-in apps. For example, dynamically creating a new Time Until applet on my Tidbyt when someone creates a new scheduled Maintenance in PagerDuty or adding stock applets dynamically based on news events.

The ability to create these built-in applets, coupled with the existing ability to remove them allows for better control over the rotation externally as well.

This looks perfect. Do you perhaps have a recommendation for a simple “text to image” utility?