Set up a device.
Understand what it returns.

Busloom is a project-based Modbus engineering tool. The project describes a device and how to interpret it; the native runtime talks to the device; views schedule reads; tags decode the returned bits or words; diagnostics retain the evidence. These are separate layers on purpose.

The five objects you need to understand

Project

The portable description of one device or device family: profiles, views, tags, Trends, automation, and display rules.

Connection profile

A named physical route to the device. It answers where and how to connect, not what the registers mean.

View

A read source. It defines an address space, addresses, and interval, then produces raw bits or 16-bit words.

Tag

Meaning attached to one starting address: name, data type, byte/word order, scale, unit, limits, and labels.

Session data

Live values, traffic, chart samples, and run output. It disappears unless you record or export it.

Your first verified read

1. Create an empty project

   Use the start screen, File → New Project, the project menu, or the command palette. Busloom intentionally creates no placeholder view.

2. Add a connection profile

   Open Project Settings → Connection profiles, choose RTU, TCP, or TLS, and enter the physical connection parameters.

3. Connect

   Select the profile in the app bar and connect. A connected transport alone does not start polling.

4. Find an address

   If the map is unknown, open Auto Scan and run Quick. If the map is known, skip scanning and create a view directly.

5. Create and start a view

   Add a view for the correct address space and range. Start it from the floating bar. The status changes from stopped to running.

6. Verify one value

   Open Register Inspector for the address. Compare the raw word or bit with the device manual before adding data type, order, and scale.

7. Save the project

   Save as .busloom.json. Close and reopen it once; a reusable setup is only proven when it survives a new session.

Modbus exposes four independent address spaces. The number 10 in Holding registers and the number 10 in Input registers are different objects. Every read therefore needs both an address space and a zero-based PDU address.

One exchange, three identities

Unit ID

Identifies the Modbus server/slave behind the connection. On RTU it selects a bus participant; on TCP it is still relevant for gateways.

PDU address

The zero-based address sent in the Modbus request. This is the canonical identity Busloom stores for a tag.

Transaction

One logical request and response. Raw Traffic shows its TX and RX frames together in chronological order.

What Busloom validates

Busloom does not accept a response merely because bytes arrived. It validates the RTU or TCP envelope, Unit ID, function, declared lengths, requested quantity, byte count, and response shape. A valid Modbus exception is preserved as a completed protocol exchange; malformed transport or PDU data is reported separately.

Most Modbus confusion happens before any decoding. Documentation notation is a label used by manuals; the wire protocol carries a zero-based PDU offset. Busloom stores the PDU address and may display a selected documentation notation alongside it.

Translate documentation addresses deliberately

From words to engineering value

1. Read raw words

   Use Register Inspector and keep hexadecimal visible. For a 32-bit value, record both consecutive 16-bit words.

2. Choose the data type

   Select signed/unsigned integer, float, ASCII, hexadecimal, binary, or Boolean according to the manual—not according to a plausible-looking result.

3. Set word order

   For multi-register values, decide which 16-bit word is most significant. Vendors often call this word swap.

4. Set byte order

   If required by the device, swap bytes inside each 16-bit word. Treat byte and word order as independent choices.

5. Apply engineering conversion

   Busloom presents the decoded number after scale and offset. Record the unit and precision only after the numeric interpretation is proven.

6. Test a second operating point

   Change the real process or compare another known value. One plausible sample is not enough to prove endianness and scale.

A .busloom.json file is the reviewable source of truth for one device or device family. It should be safe to share after reviewing endpoint names and certificate paths. Credentials, accepted certificate pins, account state, and live history are not embedded.

A practical team workflow

1. Keep one canonical project

   Store the .busloom.json beside related firmware or test assets. Relative TLS paths resolve from the project directory.

2. Create named profiles

   Use one profile per real endpoint or bench. Use Duplicate As to create a variant instead of overwriting another engineer's setup.

3. Review before committing

   Project files are readable JSON. Check connection endpoints, certificate paths, new tags, write-capable automation, and view ranges.

4. Create a focused version

   Professional local Git integration commits only the active project file. It does not initialize a repository, change branches, push, or include unrelated files.

Save, recovery, and reopening

Save and Save As write the project. An unsaved recovery draft is maintained locally as crash protection, but it is not a second portable project. Opening another project replaces project-owned configuration and clears project-specific runtime such as prior scan results; recordings and reports open as independent Replay tabs instead.

A connection profile answers where the device is and how bytes reach it. It does not start views or define decoding. Busloom keeps one active serialized connection so reads, writes, scans, automation, and diagnostics agree on the same transport history.

RTU setup

1. Connect the adapter

   Refresh/discover ports and identify the adapter by system path. Close any terminal or vendor tool that may own it.

2. Match serial framing

   Copy baud, parity, data bits, and stop bits exactly. A wrong Unit ID can still produce silence, but wrong framing usually makes every Unit ID fail.

3. Find the Unit ID if unknown

   Run Unit-ID discovery. It probes IDs 1–247 with one FC03 request at PDU 0 and accepts both data and valid exception responses as evidence of a device.

4. Connect, then inspect Health

   A successful open only proves the OS port opened. Perform a read and verify a completed exchange in Raw Traffic.

TCP and TLS setup

For TCP, start with the documented host, port, and Unit ID. Port 502 is conventional, not mandatory. For TLS, prefer normal CA verification. A local certificate pin is machine-specific and is not written to the project. Skip verification and certificate paths belong to the selected project profile; use skip verification only for deliberate development setups.

Connection lifecycle

Connected

The transport is open. It does not imply any source view is running.

Degraded / retrying

A request failed and the configured retry/reconnect path is active.

Disconnected

The transport is closed or the retry policy was exhausted. The next operation may reopen it on demand.

A view is a subscription to one Modbus address space. It owns an address selection and poll interval. The native scheduler—not a browser timer—turns that selection into FC01/02/03/04 requests, retains raw history, and publishes bounded UI updates.

Choose the address selection

Create and validate a view

1. Pick the address space

   Coils, Discrete inputs, Holding registers, and Input registers use different function codes and cannot share one view.

2. Select addresses

   Enter a range or custom set. Include every continuation word required by multi-register tags.

3. Inspect Read Plan

   Review exact blocks, function codes, gaps, continuation words, and estimated frame sizes before polling.

4. Set a realistic interval

   Choose an interval the device and link can sustain. Fast UI refresh does not create faster polling.

5. Start the source

   Use the floating bar. Running, stopped, waiting, and error states describe acquisition—not connection state.

6. Verify timestamps and frames

   At least two successful cycles should update timestamps and produce matching traffic before you build dependent Trends or automation.

When polling is too slow

• Check Connection Health for actual latency, retries, and RTU utilization before reducing the interval.
• Prefer coherent blocks over many isolated addresses when the device accepts the intervening range.
• Do not include known illegal gaps merely to create one visually neat range.
• Remember that automation temporarily owns the connection and may interrupt background requests.

Views answer “what should Busloom read?” Tags answer “what does the data mean?” A tag begins at one PDU address and may consume one bit, one word, or several consecutive words depending on its codec.

Tag anatomy

Identity

Name, address space, starting PDU address, group, and manual order.

Codec

Boolean, signed/unsigned integer, float, ASCII, hexadecimal, or binary plus required register count.

Layout

Byte and word order for multi-register values.

Engineering semantics

Scale, offset, precision, unit, limits, and value labels.

A safe decoding workflow

1. Name the raw location

   Create the tag with the correct address space and PDU address. Do not compensate for addressing mistakes with a scale or word swap.

2. Choose the codec

   Match the vendor's width and signedness. Ensure the source view includes every consumed word.

3. Prove layout

   Use hexadecimal raw words and a known device value to establish byte/word order.

4. Apply scale and offset

   Only after the raw numeric value is correct, add the documented engineering conversion.

5. Add presentation

   Set unit, precision, value labels, and limits. These should communicate meaning, not hide uncertainty.

6. Test boundary values

   Verify zero, negative values, high range, or enumerated states where possible.

Import a vendor register map

Busloom imports CSV, TSV, and XLSX through a preview rather than guessing column meaning. Choose whether source addresses are PDU offsets or documentation addresses, map columns to Busloom fields, review validation errors, then decide whether conflicts add only or update existing tags.

Writes change real equipment. Busloom keeps the protocol visible and applies write protection at the native boundary so UI actions, automation, CLI, and MCP cannot bypass a read-only profile.

Before the first write

• Confirm the active project, connection profile, Unit ID, address space, and PDU address.
• Read the current value and inspect its raw representation.
• Confirm whether the device expects one coil/register or a multi-value operation.
• Use a read-only profile whenever the task does not require changes.
• Understand the machine state, interlocks, and consequences outside Busloom.

Manual write procedure

1. Open the value editor

   Start from the exact row or decoded tag. The editor shows the target and expected representation.

2. Enter the engineering value

   Busloom validates type, finite numeric input, limits, and the codec's encodable range before producing raw bits or words.

3. Review the confirmation

   Verify profile, Unit ID, address space, PDU address, function, and encoded payload—not only the friendly tag name.

4. Send the write

   Busloom uses FC05/FC06 for a single value or FC15/FC16 for supported multiple-value writes.

5. Verify independently

   Read the target again and inspect Raw Traffic. An echoed write response proves protocol acceptance, not necessarily physical actuation.

Diagnostics observe the same native transaction stream as ordinary polling and writes. Start with the narrowest question; do not run an exhaustive scan when one known request can identify the fault.

Choose Quick or Exhaustive scan

A diagnostic sequence that preserves evidence

1. Reduce the test

   Stop unrelated views and reproduce with one address, one profile, and one expected value.

2. Check Health

   Decide whether the failure is connection, timeout/retry, Modbus exception, malformed response, TLS, or CRC-related.

3. Open the transaction

   Use Raw Traffic source attribution to inspect the exact request and response bytes.

4. Compare protocol fields

   Verify Unit ID, function, PDU address, quantity, byte count, exception code, and timing.

5. Record a bounded artifact

   Capture only the interval needed to reproduce. Export a session when another person must inspect it without the device.

A Trend subscribes to numeric or Boolean values produced by source views. It does not create its own polling loop. Its floating bar reports how many required sources are running and can start missing sources from the Trend.

Create a useful Trend

1. Choose a question

   Prefer a small set of signals that explain one behavior, such as setpoint, measured value, enable, and alarm.

2. Attach series

   Add numeric or Boolean tags from source views. Existing saved Trends are edited in Project Settings to keep viewing and configuration separate.

3. Start missing sources

   Use the floating bar. The source counter makes incomplete acquisition explicit.

4. Set the time window

   Use a window that shows the process dynamics without compressing meaningful transitions.

5. Record before reproducing

   If the event matters, start a bounded recording before triggering it. Exporting afterward only sees retained history.

Replay semantics

A replay tab is explicitly labeled Replay and owns an immutable local timeline. Scrubbing or changing playback speed never writes a project or sends traffic. Raw Traffic replay keeps the ordinary filters and frame inspector; Trend replay reconstructs chart samples and capture completeness, including dropped-count warnings.

Automation executes against project tags and connection profiles through the same native connection, codecs, write guards, and Raw Traffic attribution as the desktop UI. A Professional license is required to run it; Community projects may still retain definitions.

Build the first safe scenario

1. Start with reads and expectations

   Prove symbolic tag targets and decoding before adding a write.

2. Add typed inputs

   Use parameters for values that change between runs. Use a dataset when the same scenario must run for multiple named cases.

3. Add control flow sparingly

   If/Else expresses a branch, Retry repeats a bounded child sequence, and nested scenarios reuse a named workflow.

4. Dry run

   Dry run validates and presents planned writes without changing the device. Review every target and encoded value.

5. Run against the intended profile

   Automation has priority over background polling and may interrupt/reopen the shared connection.

6. Inspect and export the report

   Use iteration, case, nested step, captured variable, observed value, duration, log, and transaction ID evidence.

Reports and comparison

Export JSON for lossless replay, JUnit for CI, or standalone HTML for a human-readable artifact. Imported reports open in read-only Replay without a connection or rerun path. Compare a candidate against a compatible baseline to see semantic regressions, improvements, changed observations, and duration deltas matched by stable case and step identity.

The busloom binary runs without Tauri or a WebView. It reads the same schema-1 project, freezes the selected run profile and connection profile, and invokes the same native automation runner as the desktop application.

Install and verify the command

1. Install from Busloom

   Open Application Preferences → Command-line interface and install the launcher into a directory on your PATH.

2. Open a new terminal

   Shells cache command lookup. Start a new terminal or refresh the shell after installation.

3. Verify

   Run busloom --help and busloom license status before relying on the command in CI.

Run saved automation

busloom run ./device.busloom.json \
  --run-profile "Smoke test" \
  --connection "Bench RTU" \
  --dry-run \
  --report junit \
  --output ./report.xml

License operations

busloom license status
busloom license request --output ./machine.busloom-license-request
busloom license install ./machine.busloom-license
busloom license inspect ./machine.busloom-license

The CLI supports offline activation. Export a request on the target machine, turn it into a device license in My Busloom on a connected machine, then install the signed response on the target. Use the desktop app for the online device-code flow.

Busloom can expose the open desktop session as a local Model Context Protocol server. It is an adapter to the same project, connection, scan, view, tag, write, and automation paths—not a second hidden Modbus client.

Enable a client

1. Open Application Preferences → MCP

   MCP is a Professional feature and is disabled by default.

2. Enable the local server

   The listener binds only to 127.0.0.1 and Busloom must remain open.

3. Copy URL and bearer token

   Configure the client for Streamable HTTP and send the token in the Authorization header.

4. Keep prompts enabled first

   Read and project operations can proceed, while tag writes and real write-capable automation ask in Busloom.

5. Regenerate after exposure

   Regenerating the token restarts the enabled server and disconnects existing clients.

What an agent can orchestrate

The MCP surface covers project creation/open/save, profiles, port and Unit-ID discovery, connection, scans, views, tags, acquisition, bounded observation of changing values, writes, diagnostics, and automation. Mutations use the same project validator and undo/history path. Unsaved MCP edits remain unsaved until the project is explicitly saved.

Seven-day trial

On the first run you can continue with Community or start the Professional trial. Declining it does not throw it away: start it later from Application Preferences → License & activation. The trial lasts seven days on that installation, enables Professional workflows for evaluation, and does not restart after it expires.

Permanent device activation

One purchased Professional license is assigned to one device. The installed certificate is verified locally and has no heartbeat or expiry. There is no self-service release; support handles legitimate hardware replacement. License state is device-local and never enters a project.

Software updates

Application Preferences → Software updates checks the public stable manifest. Checking after launch is enabled by default and can be disabled there. The check never installs an update: download, installation, and restart remain explicit. The platform artifact is verified with a dedicated embedded update-signing public key. Community and Professional receive the same versions.

Start from the visible symptom

Minimal support package

• Busloom version, operating system, and transport type.
• The exact operation, expected result, and actual result.
• Active profile facts with secrets and private infrastructure removed.
• A bounded Raw Traffic or Trend session that contains one reproduction.
• The project only after reviewing endpoints, notes, and certificate paths.

Glossary

PDU address

Zero-based address carried in the Modbus protocol data unit.

Documentation address

Human-facing notation such as 40001; its base and prefix convention must be confirmed.

Unit ID

Server/slave identifier used on RTU and by many TCP gateways.

Source view

Running acquisition definition that produces raw bits or words.

Tag

Named decoding definition beginning at one address.

Frame

One transmitted or received RTU ADU or TCP ADU shown as protocol evidence.

Session artifact

Read-only saved Trend or Raw Traffic capture that can replay without a device.

Project artifact

Editable .busloom.json configuration used for future work.