Skip to main content

Debugging on device

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.

tip

Quick tip: install autocomplete for CLI commands with sos autocomplete install. Read more.

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​

info

The updated CLI v2.3.0 and above provides direct console messages from the connected device in your terminal. To use this feature, use the latest available CoreApp.

Navigate to your applet's root directory and use:

Connect to device using signageOS CLI
sos device connect --device-uid deviceUid --hot-reload

You can obtain the deviceUid from the Box on the device detail page - UID (for REST API).

After the command initiates successfully, the CLI will provide you with hot reload and a direct stream of console logs right in your terminal.

warning

Older or legacy devices might not send all console logs given the outdated Chromium. But in general it is still the best and easiest way to get information about application behavior on these platforms.

Troubleshooting​

If you're having trouble getting your device to connect to the CLI app, check the console and follow the next troubleshooting steps.

  1. Run in your terminal: sos device connect --device-uid deviceUID --hot-reload --force. The flag --force enforces closing all alive connections and starting over.
  2. If the device is not in the same network as your machine, use the flag --use-forward-server that allows the CLI debugging remotely. Use this option only on your test/lab devices.
  3. If the console displays the message Press Ctrl + c to disconnect, it indicates the application likely failed to load. In this situation, reload the device's CoreApp and execute the terminal instruction again.

Legacy Guide for CLI v2.2.0 and older​

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.