Forem: Josu Igoa

Writing an action for Ideckia

Josu Igoa — Wed, 08 Mar 2023 09:04:41 +0000

If you don't know what Ideckia is, I wrote an introductory post.

To get some context, this is how the Ideckia server works:

Read the layout.json file where all the items are defined (with their attached actions).
Initializes all the actions defined in that file and injects to action each instance the properties defined for each case.

In this post we will create our very first Ideckia action, a simple parametrized action to update an item with a text, we will follow these steps:

Create the JavaScript file with the Ideckia actions structure
Configure the new action in the editor.
Check it is working as expected

As a proof of what easy (and fast) is to create an action for Ideckia: I've created the action itself, configured it in the editor, documented each step, took screenshots, write a basic post, some bugfixes in the server... and it took me only 10 minutes.

Creation of the action file

If we haven't Ideckia in our machine, we must download and uncompress it in a directory.

Go to the actions directory and create a new directory called simpleaction (or the name you prefer, is your action!). Inside that directory create a file called index.js, this name is mandatory, so you can't pick another one, sorry.

Paste this code in the index.js file.

class SimpleAction {

    // Method called to inject the properties and server access (dialogs, logs...)
    setup(props, server) {
        this.props = props == null ? {} : props;
        if (this.props.name == null) {
            this.props.name = 'Ideckia';
        }
        this.server = server;
    }

    // Method called when the action is loaded
    init(initialState) {
        return new Promise((resolve, reject) => {
            resolve(initialState);
        });
    }

    // Method called when the item is clicked in the client
    execute(currentState) {
        return new Promise((resolve, reject) => {
            currentState.text = `Clicked at ${Date.now()}`;
            this.server.dialog.info('Extra! Extra!', `A simple hello from a simple action! My name is [${this.props.name}]!`);
            resolve(currentState);
        });
    }

    // Method called when the item is long pressed in the client
    onLongPress(currentState) {
        return new Promise((resolve, reject) => {
            resolve(currentState);
        });
    }

    // Method called from the editor to create an UI to configure the action
    getActionDescriptor() {
        return {
            name: "simpleaction",
            description: "Demo of a simple Ideckia action",
            props: [{
                name: "name",
                type: "String",
                isShared: false,
                defaultValue: "Ideckia",
                description: "A name shown in the window",
                values: []
            }]
        };
    }
}

exports.IdeckiaAction = SimpleAction;

Explanation

There are two methods that needs to be explained: execute and getActionDescriptor.

execute: This method is called when the item is clicked in the client. The code we put in there will do this:
- Update the text of the client item.
- Show up a information dialog box with the given text. The text is the property called name.
getActionDescriptor: This method is called by the editor. It returns the properties that can be configured by the editor. In the example above, we've added the property name.

Configure the action

Now we must start the application (if it isn't already). When it is running, go to the editor. We will add the action to the panel to test it. At this point it's convenient to be familiar with the concepts used by Ideckia

Select an empty item

Add a state to the item. It will ask you to select between 'Change directory' or 'Multi State'. We will selecte the second one.

(Optional) Select the state element and edit it: text, text color, background color, icon, text size...

Add an action to the state

Select our action from the actions list

Set the property of our action

Click the Update server layout button to save the changes.

Time to test

Be sure you have Ideckia running. Open an Ideckia client (mobile, desktop). If you don't have any of these, the editor can be used as client checking the checkbox in the top right corner. Once it is selected, any click on an item will be considered a click in a client, triggering the action in the server.

So, click the item in any (or every!) client connected to the server et voilà! The item text will show the current timestamp and a info dialog box will pop up in your screen.

Here is the entire code of this project

Change the code and play with it

Ok, you've seen what is going on. Now it is time to tinker with the new action. What will happen if you...

Add a new property to change the title of the dialog box?
Change the background color of the item when it is clicked?

Remember that the state of the item has this structure:

ItemState = {
    text
    textSize
    textColor
    textPosition
    icon
    bgColor
}

Have fun!

Open source StreamDeck alternative

Josu Igoa — Thu, 16 Feb 2023 11:26:31 +0000

I've always been attracted by StreamDeck for developers productivity.

Mute/unmute microphone ...*
Open all the needed applications when starting the day at once ...*
Write log-in information (user/password) ...*

*... with a single click of a button

But, you must buy a hardware of thousands of € or pay a smartphone app (monthly 2.99€) just for testing. Only works for windows & mac and writing plugins is not very straighforward (at least for me).

It is very important for me to create my own plugins

Alternatives

I know there are some alternative solutions that works with smartphones such as touch-portal and macrodeck but they have some things that I don't like.

They are closed source (Maybe macrodeck is now open sourced? If it's so, too late, I'm on my way!).
You have to install some dependencies (java and .net) to run them.
There is no solution for linux machines
They have a complex system to create plug-ins (install SDK, create a package...)

So, as any software developer, because the solutions out there weren't satisfing my needs 150%: I created my own solution!

My own solution (a.k.a. Ideckia)

My main goal was to create a tool which was very easy to write plug-ins for it (and hack the existing ones). A tool which was able to work the same way in windows, macos and linux.

The first I though was the name :-) I had the perfect name for it: ideckia

irekia means "open" in my mother language, Basque. And deck... well, you get the reference, right?

After that come the minor things, the plan for the app:

Create a server in the computer with duplex communication for the client (smartphone, desktop...).
Save all the data in a plain json file. Human readable, no crypto-data
Use NodeJS as it is cross-platform
Make the actions (or plug-ins) in a single JavaScript file
- The actions may match a structure which the server expects to call some functions: initializing, item-pressed...
- As the actions are Javascript files, you can use the vast library from npm
Load the actions to run at startup from a directory. Making them interchangeable/hackable.

I will dig in the server, actions and client.

Server side

These are the core concepts of the app:

Layout: Bunch of items
Item: An element that has a single or multiple states. It is clickable in the client.
State: Definition of the item status: text, textColor, bgColor, icon and an action list.
Action: Action which will be fired (can be more than one in a state) in the host computer when the item is pressed in the client.

The server is a simple app which reads a JSON file which defines the layout. The work of the server is to manage the current directory, send the needed information to show in the client. And when an item is clicked in the client, the servers runs the actions attached to that item or sets the directory to show. This server-client communication is done by Websockets.

The server directory tree looks like this

|-- ideckia         -> the app executable
|-- app.props       -> properties for the server (actions directory path, layout file path, log level, listening port...)
|-- layout.json     -> the layout information
|-+ actions         -> directory where the actions are stored

The layout can be edited by hand, but the server provides an integrated editor to edit your layout. Open the browser and go to http://localhost:8888/editor (the port is the one where the server is running). I know it is not the prettiest thing, but it does get the job done.

Now we'll see how are the actions internals.

Actions

Actions sources are available in the actions folder usually (configurable via app.props file next to the executable). Every action is defined in it's own folder and an index.js file in it.

|-- ideckia
|-- app.props
|-- layout.json
|-- actions
|   |-- my_action
|       |-- index.js
|   |-- another_action
|       |-- index.js
|       |-- dependencies.js
|       |-+ node_modules

This index.js file must have this functions defined to be called from the server when loaded and executed:

setup(props, server):Void
- Server will call to this method to inject the configuration properties of the action instance and some convenient functions from the server.
init(initialState:ItemState):Promise
- The server will call to this once, to initialize what you need
execute(currentState:ItemState):Promise
- The server will call when the associated item is clicked.
onLongPress(currentState:ItemState):Promise
- The server will call when the associated item is long pressed.
getActionDescriptor():ActionDescriptor
- This method is used by the editor.

There are some default actions that comes in the default ideckia package:

Command: Execute an application or shell file with given parameters
Keyboard: Create hotkeys, write strings... A wrapper for NutJs
Counter: Count how many times the item is clicked. Can be a countdown too.
Random color: Generate random color and show it in the item.
Stopwatch: Executing this action, will start and pause a timer shown in the button itself.
Timezones: Show the time in the configurated timezones.
Worklog: Log you daily work in a plain json file.
FTP-Connect: Connect to FTP in a simple and fast way.
SSH-Connect: Connect to SSH in a simple and fast way.
Open weather: Show the weather in the configured towns.
Clementine control: Control Clementine.
Mute mic: Mute / unmute microphone.
Toot: Publish a toot in mastodon.
Wait: Waits given milliseconds until the next action.
Countdown: Countdown timer
Log-in: Writes username and password and presses 'Enter' (this action uses Keyboard, it is mandatory).
Color-picker: Show in the item the color of the pixel where the mouse is.
Obs-control: Control OBS Studio (replacing former obs-websocket action)
KeePasXC: Get write the username and password from KeePassXC. This action uses Log-in, it is mandatory.
Emoji: Shows a random emoji every time is clicked

Client

The server sends the panel information to any connected client. And those clients send to the server which item has been clicked. There is a mobile client written in Flutter.

What I've achieved

Cross-platform application (windows, mac and linux)
Portable (no installation needed)
- Use PKG to create a single executable
- light executable < 40MB
modular and hackable
- Any action can be changed
- The editor can be easily stylized
All the layout info in a plain json file
Tons of NPM packages usable
Easy to create and test new actions

More info here