Skip to main content

Connect Applet to Device Using signageOS CLI

Speed up your development with instant deployment of your applet directly from the command line interface (CLI) to a device in your local network using signageOS.

Prerequisites​

Before you begin, ensure you have the following:

  • A signageOS account.
  • signageOS CLI installed.
  • At least one organization set up in signageOS Box (create one here).
  • Node.js version 10.15.0 or later, including NPM (download here; previous versions here).
  • A terminal application (e.g., Shell, Gitbash, PowerShell, Windows Terminal, or Cmder).
tip
  • Consider using nvm to manage Node.js versions.
  • Windows Terminal and Cmder support multiple windows for efficiency.

Setup Instructions​

  1. Navigate to your applet project directory: cd /path/to/your/project.
  2. Install dependencies: npm install.
  3. Build the project: npm run build (or use a custom command).
  4. Upload the applet to signageOS: sos applet upload.
  5. Create an applet bundle: sos applet build.

Device Connection​

After completing the setup, connect your applet to a device in your local network:

Navigate to your applet's root directory and use:

Connect to device using signageOS CLI
sos device connect

You can pass these arguments after command, or the command will provide you with interactive selection

ArgumentDescriptionDefault value
--ip (required)Local network computer IP addressAuto-detected
--device-uid (required)Device UID from signageOS BoxSTDIN
--applet-dir (required)Applet project directoryCurrent directory ${PWD}
info

It may take a few seconds for the applet to appear on your device.

To exit development mode, press CTRL + C (or CMD + C on Mac) in the terminal. This will end the connection and revert the display to its previous state.

Enable Hot Reload for efficient debugging​

warning

Hot reload requires the signageOS webpack plugin, which is included with applets created using the CLI command sos applet generate. In this case, use npm run connect in step 2 below.

If your applet was not generated using the CLI, use sos applet start --hot-reload in step 2 below.

warning

The applet must be uploaded to the same organization as the device you are connecting to!

  1. Follow the setup instructions to upload and build your applet
  2. In the first terminal window, within your applet project directory, run npm run connect or sos applet start --hot-reload regarding to the way your applet was created (see above).
  3. In the second terminal window, also within your applet project directory, run sos device connect to connect to the device.
info

You can find more information and arguments for the sos applet start command at https://github.com/signageos/cli?tab=readme-ov-file#applet-start.

Connection troubleshooting​

Hot reloading relies on port 8091 being open and listening for external connections.

You can check whether there are any firewall rules for that port to ensure that incoming connections are not blocked:

# UNIX-like systems
sudo iptables -L -n | grep 8091
# Windows
netsh advfirewall firewall show rule name=all | findstr "8091"

Once the connect server is started (either by running npm run connect or sos device connect), you should see the port open:

# UNIX-like systems
sudo netstat -tuln | grep 8091
# output should be like
# tcp6       0      0 :::8091                 :::*                    LISTEN

# Windows
netstat -ano | findstr :8091

Notes​

The sos applet upload step is required only once to assign a unique UID to your applet.