Socket.io RPC

FreedeckRPC provides a simple interface to connect external applications to Freedeck, allowing you to send notifications, edit tiles in real-time, manage plugins, configure settings, and authenticate with the Freedeck server.

This documentation is for usage of the freedeck/rpc module, it’s not available as a npm module, but you can clone the repo to get it.

Features

🔔 Send notifications to Freedeck
🎛️ Edit tiles in real-time
🔌 Manage plugins
⚙️ Configure settings
🔐 Secure authentication with Freedeck server

Installation

git clone https://github.com/Freedeck/rpc

npm install socket.io-client

yarn add socket.io-client

pnpm add socket.io-client

Quick Start

Import the module

const { RPCClient, RPCScopes } = require('./FreedeckRPC');

Identify your application

RPCClient.identify({
  id: RPCClient.generateID('MyApp', 'YourName'),
  title: 'My Freedeck App',
  author: 'Your Name',
  version: '1.0.0',
  authorizationMessage: 'Allow MyApp to connect to Freedeck?'
});

Connect to Freedeck

RPCClient.connect('freedeck://localhost', [RPCScopes.sendNotifications]);

Listen for events and send notifications

RPCClient.on('status-update', (data) => {
  console.log('Status:', data.stage);
});

RPCClient.on('authorization', () => {
  RPCClient.notify('Hello from my app!');
});

API Reference

RPCClient

The main client object for interacting with Freedeck. All methods and properties are accessed through this object.

Methods

identify(appInfo)

Identifies your application to the Freedeck server.Parameters:

appInfo (Object):
- id (string): Unique application ID (use generateID())
- title (string): Display name of your application
- author (string): Your name or organization
- version (string): Application version
- authorizationMessage (string): Message shown to user during authorization

RPCClient.identify({
  id: RPCClient.generateID('WeatherApp', 'JohnDoe'),
  title: 'Weather Dashboard',
  author: 'John Doe',
  version: '2.1.0',
  authorizationMessage: 'Allow Weather Dashboard to send weather updates?'
});

connect(url, scopes)

Connects to a Freedeck server.Parameters:

url (string): Server URL (supports freedeck:// protocol or standard HTTP)
scopes (Array): Array of permission scopes (default: [RPCScopes.sendNotifications])

// Connect to local Freedeck
RPCClient.connect('freedeck://localhost');

// Connect with multiple scopes
RPCClient.connect('freedeck://192.168.1.100', [
  RPCScopes.sendNotifications,
  RPCScopes.editTilesLive
]);

notify(...messages)

Sends a notification to Freedeck.Parameters:

...messages: Messages to send (will be joined with spaces)

RPCClient.notify('Battery low:', '15%');
RPCClient.notify('Download complete!');

on(event, callback)

Listens for events from the RPC client.Parameters:

event (string): Event name
callback (function): Event handler

Available Events:

status-update

Connection status changes

connection

Connection state updates

authorization

User authorization granted

reply

Server responses

RPCClient.on('status-update', (data) => {
  console.log('Status changed to:', data.stage);
});

RPCClient.on('authorization', () => {
  console.log('User authorized the app!');
  // Now you can send notifications
});

generateID(appName, author)

Generates a unique application ID.Parameters:

appName (string): Name of your application
author (string): Author name

Returns: Base64-encoded unique ID

const appId = RPCClient.generateID('MusicPlayer', 'DevStudio');

generateAuthToken(appID)

Generates an authentication token for an application.Parameters:

appID (string): Application ID

Returns: Base64-encoded authentication token

validateAuthToken(token)

Validates an authentication token format.Parameters:

token (string): Token to validate

Returns: Boolean indicating if token is valid

Properties

RPCScopes

Permission scopes that define what your application can do with Freedeck.

number

default:1

Send notifications to Freedeck

number

default:10

Edit tiles without reloading

number

default:11

Edit tiles with reload

number

default:400

Edit Freedeck configuration

number

default:200

Add new plugins

number

default:201

Reload existing plugins

number

default:202

Disable plugins

number

default:203

Enable plugins

const RPCScopes = {
  sendNotifications: 1,      // Send notifications to Freedeck
  
  editTilesLive: 10,         // Edit tiles without reloading
  editTilesReload: 11,       // Edit tiles with reload
  
  configEdit: 400,           // Edit Freedeck configuration
  
  pluginsAdd: 200,           // Add new plugins
  pluginsReload: 201,        // Reload existing plugins
  pluginsDisable: 202,       // Disable plugins
  pluginsEnable: 203         // Enable plugins
};

Connection States

The client goes through several states during connection. Monitor these states to handle the connection lifecycle properly.

disconnected

Initial state - not connected to any server

preflight

Preparing connection parameters and validation

initializing

Setting up Socket.IO connection to server

requesting-auth

Sending authorization request to server

prompting-user

User sees authorization dialog in Freedeck

connected@{url}

Successfully connected and authorized

denied

User rejected authorization (app exits automatically)

Error Handling

RPCClient.on('status-update', (data) => {
  if (data.stage === 'denied') {
    console.log('User denied authorization');
    // Handle rejection gracefully
  }
});

// The client automatically exits on denial
// Override this behavior by handling the event before it reaches the default handler

Advanced Usage

Custom Logging

// Set log level (0 = errors only, 1 = normal, 2+ = verbose)
RPCClient.logLevel = 2;

Handoff API

For alternative communication when direct RPC isn’t available:

// Get handoff token
RPCClient.handoffAPI.getToken().then(token => {
  console.log('Handoff token:', token);
});

// Send notification via handoff
RPCClient.handoffAPI.notify('MyApp', 'Hello via handoff!');

Examples

Simple Notification App

const { RPCClient, RPCScopes } = require('./FreedeckRPC');

// Setup app
RPCClient.identify({
  id: RPCClient.generateID('NotifyApp', 'Me'),
  title: 'Simple Notifier',
  author: 'Me',
  version: '1.0.0',
  authorizationMessage: 'Send notifications to Freedeck?'
});

// Connect and send notifications
RPCClient.connect('freedeck://localhost');

RPCClient.on('authorization', () => {
  setInterval(() => {
    const time = new Date().toLocaleTimeString();
    RPCClient.notify('Current time:', time);
  }, 60000); // Every minute
});

Status Monitor

const { RPCClient, RPCScopes } = require('./FreedeckRPC');

RPCClient.identify({
  id: RPCClient.generateID('StatusMonitor', 'Admin'),
  title: 'System Status Monitor',
  author: 'Admin',
  version: '1.0.0',
  authorizationMessage: 'Monitor system status?'
});

RPCClient.on('status-update', (data) => {
  console.log(`Connection status: ${data.stage}`);
});

RPCClient.on('authorization', () => {
  console.log('✅ Connected and authorized!');
  
  // Monitor system and send alerts
  checkSystemStatus();
});

function checkSystemStatus() {
  // Your monitoring logic here
  const cpuUsage = Math.random() * 100;
  
  if (cpuUsage > 80) {
    RPCClient.notify('⚠️ High CPU usage:', `${cpuUsage.toFixed(1)}%`);
  }
}

RPCClient.connect('freedeck://localhost');

Troubleshooting

Common Issues

Connection fails: Ensure Freedeck is running on the specified URL
Authorization denied: User must click “Allow” in the Freedeck authorization dialog
Notifications not appearing: Make sure you have sendNotifications scope and are authorized

Debug Mode

// Enable verbose logging
RPCClient.logLevel = 2;

// Listen to all events for debugging
RPCClient.on('connection', (data) => console.log('Connection:', data));
RPCClient.on('reply', (data) => console.log('Reply:', data));

Requirements

Node.js
socket.io-client package
Running Freedeck application
Network access to Freedeck server

Getting Started

Customization

Development Resources

API References

Features

Installation

Quick Start

API Reference

RPCClient

Methods

status-update

connection

authorization

reply

Properties

RPCScopes

Connection States

Error Handling

Advanced Usage

Custom Logging

Handoff API

Examples

Simple Notification App

Status Monitor

Troubleshooting

Common Issues

Debug Mode

Requirements

​Features

​Installation

​Quick Start

​API Reference

​RPCClient

​Methods

status-update

connection

authorization

reply

​Properties

​RPCScopes

​Connection States

​Error Handling

​Advanced Usage

​Custom Logging

​Handoff API

​Examples

​Simple Notification App

​Status Monitor

​Troubleshooting

​Common Issues

​Debug Mode

​Requirements

Features

Installation

Quick Start

API Reference

RPCClient

Methods

Properties

RPCScopes

Connection States

Error Handling

Advanced Usage

Custom Logging

Handoff API

Examples

Simple Notification App

Status Monitor

Troubleshooting

Common Issues

Debug Mode

Requirements