Skip to content
JasperNode JasperNode

Getting started

This guide takes you from a running JasperNode instance to your first piece of working logic and your first field connection. It assumes no prior JasperNode knowledge. If you have never worked with PLCs or industrial I/O, skim JasperNode vs. a traditional PLC and the Glossary alongside it.

What you need

Section titled “What you need”
  • A JasperNode instance. JasperNode is a runtime you install on a host. See Where JasperNode runs below. For a first look you can also run it on a Linux box or a development machine.
  • A modern browser. The entire product is a browser IDE — there is nothing to install on your workstation.
  • A JasperX account. Sign-in and the AI agent are provided by the JasperX cloud.

Where JasperNode runs

Section titled “Where JasperNode runs”

JasperNode is designed for Linux, from small IIoT gateways up to cloud servers. The typical target is a 4-core / 4 GB ARM edge device; the practical minimum is 2 cores and 2 GB of RAM on a trimmed, headless Linux OS.

The supported production target. Install the JasperNode binary on the host and run it as a service. All connectors — including serial and EtherCAT, which need direct hardware and predictable latency — work natively here. The installer sets up a systemd service — during the beta, install from the beta channel:

Terminal window
curl -sSL https://dl2.jasperx.io/jn/install.sh | JN_CHANNEL=beta sudo -E bash -

Ask for the connectors you need with CNTR=. The runtime ships without connectors — each one is downloaded from JasperNode’s signed connector catalogue, so a connector can be updated without updating the node. Name the ones this node needs and it installs them itself as it starts, so the node comes up already holding them:

Terminal window
curl -sSL https://dl2.jasperx.io/jn/install.sh | JN_CHANNEL=beta CNTR=modbus,s7 sudo -E bash -

Names are the connector type slugs — modbus, s7, serial, ethercat, jaspermate, lidar, mqtt, mqtt_broker, modbus_server, hmi, influxdb (see the Connector catalog). A name the catalogue does not have stops the installer, which lists the ones it does have; nothing is installed until you re-run with it corrected.

CNTR= is optional and only a starting point — you can add or remove connectors at any time in the Connector Manager, and re-running the installer with CNTR= on an up-to-date node adds them without touching the binary.

Updating later: a native Linux install updates itself on its release channel, while a container node is updated from the host by pulling the newer image and recreating the container — see Software updates and Updating a container node.

Open the IDE and sign in

Section titled “Open the IDE and sign in”

  1. Point your browser at the node. By default the runtime serves the IDE on its HTTP port. On the same machine that is http://localhost:9009; on a device, use the device’s address.

  2. Complete first-run setup. A new node shows a short Setup screen to establish node identity before anything else can be edited.

  3. Sign in with JasperX. Authentication is delegated to the JasperX cloud — there are no local user accounts. Click Login via JasperX and authorise. The first editor to register a node becomes its owner and can invite others.

After sign-in you land on the Overview dashboard: tag and script counts, connector health, the Logic Cycle run state, and recent activity.

The Overview dashboard, with the AI Agent panel on the right

Build your first logic

Section titled “Build your first logic”

Let’s create a tag that counts once per second — the “blink an LED” of JasperNode. It shows the three things that make the system tick: tags, triggers, and reactive scripts.

  1. Open the Tag Tree. In the left icon rail choose Tag Tree.

  2. Create a tag. Click the ＋ button above the tree. Create a tag named counter under a new path such as demo/, with value type number. You now have demo/counter in the tree.

  3. Attach a script. Select demo/counter, open the Scripting tab, and turn the script Enabled switch on. In the editor, write:

    // on("…") reads a tag AND makes it a trigger, so this runs each second.
    on("__sys/host/clock/second"); // the node's built-in 1 Hz clock
    if (typeof cache.count !== "number") cache.count = -1;
    cache.count = (cache.count + 1) & 0xF; // wrap 0–15
    return cache.count; // the return value becomes this tag's value

    You don’t add triggers anywhere else — calling on("__sys/host/clock/second") in the code is how you declare it. The Inputs for testing panel above the editor updates to list it as you type. (Tip: instead of typing an id, drag a tag from the tree into the editor — it drops in as on("…"); the editor also autocompletes ids inside on( / read(.)

  4. Deploy. Click Deploy. The script flips live atomically and demo/counter starts counting 0→15 and wrapping, once per second.

The counter script deployed on demo/counter — the editor, its derived input, and the deploy actions

What just happened, in JasperNode terms:

  • The script belongs to demo/counter and may only set its own value (via return or self.setValue(...)).
  • It runs only when __sys/host/clock/second changes — declared by the on(...) call, not on a fixed scan.
  • cache is a per-script object that persists between runs, so the count carries over.

See Logic & the Logic Cycle for the full execution model, the self / on / read / fn APIs, and how to chain tags together.

Connect to a device

Section titled “Connect to a device”

Logic is more useful when it reads real I/O. Connectors bridge the tag tree to the field. Here is a Modbus TCP example; every connector follows the same configure → enable pattern.

  1. Open the Connector Manager from the left rail, choose Modbus, and click ＋ New.

  2. Fill in the master. Set the transport (TCP), Host and Port (e.g. 502), the Unit ID, a Cycle time (how often to poll, in ms), and a Tags’ base path — the folder the connector’s tags are created under, e.g. modbus_data/vsd_ethernet.

  3. Map registers. Add one row per value. For each: a name, the register space (e.g. Holding Registers), the address, a direction (in = device→tag, out = tag→device), and a data type (e.g. u16).

  4. Save, then enable. Saving stores the configuration; the Enabled toggle starts the connector. Only an enabled connector touches the wire.

  5. Watch the tags. The mapped tags appear under your base path in the Tag Tree and update every cycle. The connector’s live status and latency show on its page and in the status bar.

Editing a Modbus TCP instance: the master settings and the register mapping

Ask the AI agent

Section titled “Ask the AI agent”

The AI Agent panel sits on the right edge of the IDE (toggle it from the rail, or press ⌘K / Ctrl+K). Describe what you want in plain language — “create a high-temperature alarm on demo/counter over 12”, “set up an MQTT connection to my broker”, “why is bench_s71200 disconnected?”. You can reference tags with @ mentions.

The agent reads the tree and proposes changes. Anything that would alter the running process is held at the Deploy Gate: the agent tests the change and waits for your Approve / Reject before it takes effect. Read-only investigation needs no approval. See The AI agent & Deploy Gate.

Where to go next

Section titled “Where to go next”
Architecture overview Everything is a tag Full IDE walkthrough