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

• 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. The runtime itself is free; AI usage is licensed per project (see Licensing).

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.

Linux (native)

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.

macOS / Windows (container)

There are no native macOS or Windows builds. Run JasperNode inside a Linux container with Docker or Podman. Network connectors (Modbus TCP, MQTT, S7 over Ethernet, InfluxDB, Modbus Server) reach peers over your LAN exactly as they would natively.

Hardware-attached connectors need extra host setup:

• Serial / Modbus RTU — on Windows, pass a USB-serial adapter into WSL2 with usbipd-win; on macOS, bridge the port over TCP on the host (e.g. socat) or use a network-serial gateway (MOXA NPort, Digi PortServer) and connect over the LAN.
• EtherCAT — not supported on macOS or Windows hosts; the container virtualisation layer breaks the raw-socket timing it needs. Deploy to Linux hardware for EtherCAT.

Note

JasperNode ships as a single self-contained binary (with the IDE baked in) and as a container image. Obtain the build for your platform from your JasperX distribution, place it on the host, and start it. The runtime serves its own IDE — you do not deploy the IDE separately.

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. (During IDE development the Vite dev server runs on :9010 and proxies the API to :9009 — that is the address used for the screenshots in these docs.)

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.

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 Node Views, then the Tag Tree tab.

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:

   // Runs every time a trigger value changes. `cache` survives across runs.
   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

4. Add a trigger. Under Inputs & Test → Triggers, click ＋ Add and choose __sys/host/clock/second — the node’s built-in 1 Hz clock. A change on a trigger is what makes the script run.

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

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 — it is 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/fn APIs, and how to chain tags together.

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.

Direction is explicit

JasperNode never guesses whether a mapping is an input or an output — you declare in or out per register. While a connector owns a tag as an in (input) and is enabled, scripts and the UI cannot overwrite that tag; the field is the source of truth. To simulate the field, disable the connector first. See Connectors → Direction.

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

Architecture overview Everything is a tag Full IDE walkthrough

Licensing in brief

The JasperNode binary is free. The AI agent is licensed as a “job” that covers a project from development through commissioning; reaching production mode closes the job. A new project is a new job. These modes also change how aggressively the AI is allowed to act — see Operating modes.