Quick start

Build a first Tangle project with a simulated PJLink projector, a scene and a dashboard, without any hardware.

This walkthrough builds a small working project in about 15 minutes: a room with a simulated projector, a scene, and a dashboard you can open on a phone or tablet. You need no hardware: the Tangle simulator plays the projector, speaking real PJLink on a real network port.

You will:

1. Start the simulator with its demo devices.
2. Start core, with the desktop app or the core service.
3. Open the designer and sign in.
4. Add a room and a PJLink projector, and test the connection.
5. Make a scene.
6. Make a dashboard, publish it and open it.

#Before you start

Download these from the release (see Install):

• The desktop app for your platform, or the core service archive, the CLI archive and the misc.pjlink.projector module package.
• The simulator. On macOS it is inside the desktop app's .dmg (tangle-sim).

#1. Start the simulator

Open a terminal in the folder where you put the simulator.

If you have the tangle-sim executable (for example copied from the macOS .dmg):

./tangle-sim init        # writes tangle-sim.json: two projectors, a video matrix, a DMX receiver
./tangle-sim run

If you have the script package (needs Node.js 20 or newer):

node tangle-sim.mjs run examples/demo.json

The simulator prints the port of each virtual device and opens its web UI at http://127.0.0.1:4380. The demo starts:

Leave the simulator running. Keep its web UI open in a browser tab: you will watch the projector react there.

Note: macOS asks once whether node (or tangle-sim) may accept incoming connections. Allow it if core runs on another machine.

#2. Start core

Choose one option.

#Option A: the desktop app

Open Tangle. It starts its own core and signs in. On a first start, the new empty project opens on Start a project: click Start empty. Skip to step 4.

#Option B: the core service

1. Extract the core and CLI archives, and put tangle on your PATH.
2. Install the PJLink module:

tar -xzf tangle-module-misc.pjlink.projector-1.0.0.tar.gz
tangle module add ./misc.pjlink.projector --yes

3. Create a project file named quick-start.json:

{ "id": "quick-start", "name": "Quick start" }

4. Start core from the folder where you extracted it:

./tangle-core run --project quick-start.json

Core listens on http://127.0.0.1:7340. Leave it running and open a second terminal for the next step.

#3. Open the designer and sign in

With the desktop app you are already signed in. With the core service:

1. Create a token that can edit the project:

./tangle-core token create --name designer --scopes read,control,configure

The token is printed once. Copy it.

2. Open http://127.0.0.1:7340/designer in a browser.
3. Paste the token in API token and click Sign in.

The designer opens on the Overview: counts of rooms, devices, scenes, timelines, automations and dashboards, and a Needs attention list. The project tree on the left holds everything in the project.

#4. Add a room and a projector

#Add a room

1. In the project tree, right-click Rooms and devices and choose New room….
2. Type Hall and click Add.

#Add the projector

1. Right-click Hall in the project tree and choose Add device.
2. Fill in the form:

The Settings part of the form comes from the driver: PJLink asks for host, port and an optional password.

3. Click Create device. The PJLink setup assistant opens ("Turn on network control"): it lists what to switch on in a real projector. The simulator needs none of it, so click Finish later.

Within a few seconds the status next to the device name turns online. The device page shows its live Status, ready-made Controls (press Power to try it) and its Log.

#Test the connection

Click Test connection. Core starts the module on its own with the settings in the form (without saving them) and reports, for example, Connected (online, 35 ms). If it says Not connected, check that the simulator is running and that host and port match.

Note: To try a failure, run ./tangle-sim fault pj-1 offline in the simulator folder (or switch on offline in its web UI). The device turns offline in the designer. ./tangle-sim clear pj-1 brings it back.

#Optional: find it on the network

Click All devices in the project tree, then Scan the network. After 5 seconds the list shows what answered, including the simulated projectors (PJLink class 2 search). Add opens the device form with the host filled in and, when a module matches, the module chosen (Add with PJLink projectors).

#5. Make a scene

A scene is a set of device actions recalled together.

1. Click Scenes in the project tree, then New scene.
2. Name it Presentation.
3. Click Add action. Choose Device: Hall projector, Action: power on.
4. Click Add action again. Choose Hall projector, input select, and type 31 in input (HDMI 1 on PJLink).
5. Click Create scene.

Make a second scene named Off with one action: Hall projector, power off.

#6. Make a dashboard

1. Click Dashboards in the project tree.
2. In Generate, choose the room Hall and click Generate room dashboard.

The builder opens with a page already laid out: a title, a Scenes list with Presentation and Off, and the projector's controls. Generated room dashboards use the Lobby skin.

To place a device yourself instead: drag Hall projector from the Devices list in the palette onto the page. The builder asks which layout to use (Compact, Operator or Full for PJLink) and which controls to show, then places them as a group bound to the projector.

3. Click Preview to see the dashboard as screens will. Presses in preview are only logged. Tick Live control to send them to core.
4. Click Publish. The builder confirms "Published version 1".

#Open the dashboard

Click ← to go back to the dashboard list, then Open next to your dashboard. It opens at /d/room-hall on your core: http://127.0.0.1:7340/d/room-hall with the core service. The desktop app's core uses another port, which the Open link already includes.

Try it:

• Press Presentation. Watch the simulator's web UI: the Hall projector warms up for 5 seconds, then turns on with input 31.
• Press the Power toggle. It asks for a second press ("Press again to confirm") because the module marks power as a confirmed action.
• Press Off to turn the projector off.

To open the dashboard on a phone or tablet, core must accept other machines: start it with --listen 0.0.0.0:7340 --allow-remote --insecure-http and a license or --demo, then open http://<core IP>:7340/d/room-hall.

Note: Without a license, core runs as the free designer: it serves this computer only, and at the end of each hour device connections and timelines pause until you resume. Start core with --demo to try other machines (up to 10 devices, one-hour sessions). See Licensing.

#Where the project lives

Every change is saved to the project file as you make it: quick-start.json for the core service, or the project in the app's project library for the desktop app (Export… in the project menu makes a .tangle copy). Open it to see the room, device, scenes and dashboard you made. The PJLink password, if you set one, is not in the file: it goes to the OS credential store.

#Next steps

• Follow Tutorial: a gallery installation for a complete project: several devices, automations that start and stop a room on a schedule, and a staff dashboard.
• Add the Stage projector (127.0.0.1, port 4353, password secret) and start the simulator scenario stage-pj-dies to see a device fail and recover.
• Build a show in Timelines.
• React to events, the clock and buttons with Automations.
• Learn the vocabulary in Concepts.
• Customize the dashboard: pages, screen sizes, PINs and wall panels in Dashboards.