Technical documentation
EcoTune Desktop Capture
MS/TP network analyzer and BACnet device explorer · Release 1 · November 2026
1. About this document
This is the reference for EcoTune Desktop Capture. It describes what the software does, how to set it up, how each number on screen is produced, and, just as important, what has and has not been verified. Where something is untested or not built, this document says so.
2. What Desktop Capture is
Desktop Capture is one HTML file that runs in Chrome or Edge. With a USB-to-RS-485 adapter on a BACnet MS/TP trunk it does two jobs:
- Analyzer. It listens to the trunk and decodes every frame: token passing, polling, replies and BACnet data. It counts errors, draws the token ring, shows routers and networks, and writes plain-English findings.
- Explorer. After you press Join ring, your computer behaves as a normal MS/TP master. You can then discover devices with Who-Is, open a device to read every object, write values, and export a points list.
The same serial adapter also gives you Modbus RTU: scan a unit-ID range, then read or write holding and input registers. Points you open on the Devices tab can be logged together on the Trends tab. It is a vendor-neutral tool. It is not a BAS front end and it does not store history on its own (aside from what you keep logged in the Trends tab for the current session).
A free demo mode runs the whole interface against a built-in simulated trunk, with no hardware and no license. A license is required to connect to a real adapter (section 8).
3. Setup and first run
3.1 What you need
- A computer running desktop Chrome or Edge. The Web Serial feature is required; Firefox and Safari do not provide it.
- A USB-to-RS-485 adapter that appears as a serial (COM) port, for example a Silicon Labs CP210x-based adapter. The adapter must switch between receive and transmit by itself, or you must tick the RTS option described below.
- Access to the trunk's A/B (+/−) terminals. Listening is harmless; reversed polarity simply shows no frames.
3.2 First run
- Open
EcoTune_Desktop_Capture.htmlin Chrome or Edge. Click Try the demo to look around without any hardware. - For a real trunk, wire the adapter to the trunk and close any other program that uses it (BQT, YABE, a terminal). Only one program can open a COM port at a time.
- Click the license chip, paste your key, and press Activate (section 8).
- Choose the baud rate the trunk runs at (9600, 19200, 38400, 57600, 76800 or 115200), or use Auto-detect baud. Click Connect adapter and pick the port in the browser pop-up.
- Traffic should appear within a second or two. The serial format is fixed at 8 data bits, no parity, 1 stop bit.
3.3 Auto-detect baud
Auto-detect tries each supported baud rate for a few seconds and keeps the one that decoded the most valid frames. Confirm the result against the trunk's known setting.
3.4 The RTS option
The Devices tab has a checkbox, Adapter needs RTS to transmit. Leave it off unless your adapter does not switch direction on its own and transmit does not work. This option has not been tested on real hardware (section 10).
4. A tour of the screens
| Area | What it shows |
|---|---|
| Header | Product name, license chip (shows Licensed · your name or Demo only), mode chip (Listen-only or Active · MAC n), a live frames-per-second readout, connection status and the light/dark toggle. |
| Command bar | Baud rate, Connect adapter, Auto-detect baud, Try the demo, Disconnect and Clear (zeroes all counters and the table). |
| Left rail | Tabs: Overview, Devices, Modbus, Trends, Ring map, Stations, Traffic, Routing, Findings, with a device count and a findings badge. |
| Status bar | A live line along the bottom: mode, baud, frames, CRC errors, utilization, token passes per second, masters, ring state, your node and device count. |
| Hover help | Every KPI, card title, table column and status-bar item has a small “i” icon. Hovering it explains what the item is and how to read it. Section 13 reproduces these explanations. |
4.1 Tabs
| Tab | Purpose |
|---|---|
| Overview | Eight KPI tiles with a one-minute trend, the frames-per-second chart, capture-health gauge, frame mix, live bus monitor, findings preview, per-station activity heat map, top talkers, ring snapshot and application-layer counts. |
| Devices | The MS/TP device explorer (section 6). |
| Modbus | Connect over the same serial adapter (RTU), scan a unit-ID range, and read or write holding and input registers. |
| Trends | Log points added from the Devices tab on one chart at a chosen interval, each line normalized to its own range so different units compare, with a table of current values and a CSV export. |
| Ring map | Masters drawn around a circle in address order, with arrows for token passes. Solid arrows are passes from the last 15 seconds, faint dotted arrows are older, amber dashed arrows skip a master that was seen earlier. Responders that are not on the ring are listed beside it. |
| Stations | Every station heard: role, status, frame and token counts, polls, data frames, data-CRC errors, device instance, vendor and last-heard time. |
| Traffic | A frame-by-frame log with decoded details and hex, filters by frame type and MAC, a pause button and CSV export. Times are when your computer received the bytes, not on-wire timing. |
| Routing | Networks reachable through routers, how each was learned, network-layer message counts, and devices seen behind routers. |
| Findings | Plain-English hints generated from the capture. They are pointers, not proof of a cause. |
5. How the analyzer works
5.1 Decoding
The analyzer looks for the MS/TP preamble (0x55 0xFF), checks the 8-bit header CRC, then, for frames that carry data, the 16-bit data CRC. Frame types decoded:
| Type | Name |
|---|---|
| 0 | Token |
| 1 | Poll For Master |
| 2 | Reply To Poll For Master |
| 3 / 4 | Test Request / Test Response |
| 5 | BACnet Data Expecting Reply |
| 6 | BACnet Data Not Expecting Reply |
| 7 | Reply Postponed |
BACnet data frames are further decoded to the application layer (Who-Is, I-Am, confirmed requests, acknowledgements, errors, rejects, aborts) and the network layer (router announcements and queries).
5.2 Error attribution
A frame with a bad header CRC has corrupt address bytes, so it is never counted against any device. A frame with a good header but a bad data CRC is attributed to its sender. This is why the two error counters are shown separately.
5.3 Bus utilization
Utilization is received bytes × 10 bits (8 data, start, stop) divided by the capacity of the line at the selected baud rate over the recent window. It is computed from bytes this computer received.
5.4 Capture-health score
score = 100 − 8 × error-rate % (capped at 40) − 15 per alert − 5 per warning − 10 if the token path is not a closed loop
5.5 Station activity heat map
One row per station, one column per second for the last 60 seconds. Each cell is the number of frames that station sent in that second, sampled once per screen refresh, so individual seconds are approximate while the totals are accurate.
5.6 Own-frame handling
Many RS-485 adapters echo what they send. Frames from your own MAC are dropped from the analysis while you are on the ring, and the Devices tab counts them as Adapter echoes ignored.
6. The device explorer
6.1 Joining the ring
Until you press Join ring, the page transmits nothing. Joining makes your computer an ordinary MS/TP master at the MAC you choose. The page then answers the ring's poll, takes the token, sends its requests, and passes the token on, using the timing rules for MS/TP, including the 40-bit-time turnaround before every transmission. A master that ignores the token twice is skipped for 10 seconds.
6.2 Discovering devices
Discover devices (Who-Is) broadcasts a Who-Is and lists every I-Am: device instance, MAC, vendor, and, through routers, devices on other networks (shown as “Network n via router MAC m”). Basic device information (name, vendor, model, firmware, description, Max APDU) is read in the background.
6.3 Opening a device
Double-click a device. The page reads the object list and then each object's name, description, present value, units and status, with progress shown. To work with devices that cannot send long replies, the page batches ReadPropertyMultiple requests, shrinks the batch when a reply will not fit (it does not use segmentation), and falls back to single ReadProperty requests when needed.
6.4 The point table
Points are grouped by object type with search, a type filter, three sort orders and Refresh values or timed Auto-refresh (2 to 60 seconds). Types use the usual short names: AI, AO, AV, BI, BO, BV, MSI, MSO, MSV and others (TL for Trend Log, SCH for Schedule, and so on).
6.5 The inspector
Click a point to read all of its properties, including the 16-slot priority array of commandable points. The lowest-numbered slot holding a value wins; release beside a slot writes a NULL to that slot.
6.6 Writing values
The write form takes a property (Present_Value and other common properties, or any property number), a value, a data type (automatic, or real, unsigned, signed, enumerated, boolean, string, object ID, double, null) and a priority from 1 to 16 or none. Release writes NULL at the chosen priority. Every write is listed in the Write log with the device's answer.
6.7 Changing a device's identity
Opening a device's own object (Device properties & write) lets you write its Object_Name and Object_Identifier (instance number), and settings such as Max_Master. Changing the instance changes how the device is addressed on the BACnet network. This was confirmed on a real controller: the new name and instance were read back, and Backnet Quick Test displayed the values that were written.
6.8 Timeouts and retries
Each request waits 3 seconds. A request that times out is retried once. A Reply Postponed from a device extends the wait.
7. Exporting points
Press Export… above the point table. The dialog lets you choose what goes in the file:
- Quick layouts: Simple list (Device, Device ID, Type, No., Name, Description), With values (adds Value, Units, Status) and Everything.
- Columns: Device, Device ID, Type, No., Point (for example
AV6), Name, Description, Value, Units, Status. Your column choices are remembered in the browser. - Which objects: “Points only” (AI, AO, AV, BI, BO, BV, MSI, MSO, MSV), “All objects”, or any combination of the types found in the device. Options to include only points with a description, or only what the table currently shows.
- Preview of the first rows before you save.
Press Download CSV for a file that opens cleanly in Excel (UTF-8 with a byte-order mark, so symbols such as °F display correctly), or Copy for Excel to paste tab-separated columns. Values and units are separate columns when both are selected, and multiple status flags are joined with “ / ”. Rows are sorted by type and number. Example, using the Simple list layout:
| Device | Device ID | Type | No. | Name | Description |
|---|---|---|---|---|---|
| ExampleDevice | 242302 | AV | 7 | effective_cool_setpoint_1 |
The Traffic tab separately exports the frame log as CSV, and the write log exports its own CSV.
8. Licensing and privacy
8.1 How the license works
A license key is a long text string beginning ECO1-. It contains the licensee's name, a license ID and the issue date, and is signed by EcoTune with a private key that never leaves EcoTune. The app holds only the matching public key and checks the signature on your computer. A key that has been edited, or was not issued by EcoTune, is rejected. The check needs no internet.
Without a license the demo, and all views of the interface, work. Connecting to a real adapter requires a valid license. To enter one, click the license chip in the header (or the prompt that appears when you press Connect), paste the key or open the license file, and press Activate. The key is stored in your browser; Remove license from this browser clears it.
8.2 What the license does and does not do
- The licensee's name is shown in the header while the app is licensed, so a copy that is passed around is visibly someone else's.
- The key is per person. See the license terms.
- Limit: the software runs on your computer, so it cannot physically prevent a determined person from editing the file to remove the check. The license is designed to deter casual sharing and to make shared copies identifiable by name, not to be unbreakable.
8.3 Privacy
The app itself contains no analytics, no remote fonts and no calls to any EcoTune or third-party server. It makes no network connections of any kind — only the serial adapter, for both MS/TP and Modbus RTU. Captures, device data and points stay on your computer. The browser's local storage holds only your license key, the light/dark choice and your export column choices.
9. Specifications
| Item | Value |
|---|---|
| Runs in | Desktop Chrome or Edge (Web Serial API required) |
| Install | None. One HTML file, works offline |
| Physical layer | USB-to-RS-485 adapter presenting a serial port |
| Serial format | 8 data bits, no parity, 1 stop bit, no flow control |
| Baud rates | 9600, 19200, 38400, 57600, 76800, 115200; auto-detect across the same list |
| Protocol | BACnet MS/TP (master) and Modbus RTU |
| BACnet services used | Who-Is / I-Am, ReadProperty, ReadPropertyMultiple, WriteProperty (with priority and NULL), Who-Is-Router-To-Network / I-Am-Router-To-Network, routed addressing through a router |
| Segmentation | Not used. Batches shrink and fall back to single reads |
| Request timeout | 3 s, one retry |
| Own address | Any master MAC you choose (1 to 127); a free one is suggested |
| Transmits | Only after Join ring |
| Network access by the app | None. Only the serial adapter (see section 8.3) |
10. What has been verified
Confirmed on a real trunk
- Connecting an adapter and decoding live MS/TP traffic.
- Joining the ring and discovering devices (Who-Is / I-Am), including a scan.
- Writing a device's Object_Identifier and Object_Name, and reading them back. Backnet Quick Test then displayed the values that were written.
Simulated tests only
- The decoder, CRC handling and counters: 27 automated checks.
- The BACnet encoder and decoder: 17 checks.
- The MS/TP master (joining, token handling, retries, turnaround, skipping dead masters): 33 checks.
- The client (discovery, batching and fallback, writes, routed devices): 39 checks.
- The license check, including edited and forged keys: 10 checks.
- Auto-detect baud, the full connect, join, read and write flow, and the export dialog, driven in a headless browser against the built-in simulator.
Not tested
- The RTS transmit option on real hardware.
- Behavior on trunks and controllers beyond the one used for field confirmation. Controllers differ; if something misbehaves, tell us.
- Browsers other than Chrome, and Edge in particular, for the full flow.
- Modbus RTU and Trend Logging against real devices. They pass the simulated test suites above, but we have not yet confirmed them on real hardware — that confirmation is in progress.
11. Limits and cautions
- Joining the ring puts a master on a live network. Use a free MAC and leave the ring when you are done.
- Writes have no confirmation. A forgotten override can keep a point out of its program's control until it is released.
- Timing on screen comes from your computer, and USB adapters buffer data, so on-wire timing is approximate.
- Devices that require segmentation to answer cannot be read in full.
- Trend Log objects are listed, but their recorded data is not downloaded.
- The capture-health score and the findings are aids, not diagnoses.
12. Troubleshooting
| Symptom | Things to check |
|---|---|
| The port does not appear in the pop-up | Another program (BQT, YABE, a terminal) has the port open. Close it and reconnect. Check the adapter's driver. |
| Connected but no frames | Baud rate; A/B polarity; whether any master is on the trunk. Try Auto-detect baud. |
| Many header CRC errors | A wrong baud rate is the first suspect. Then noise, termination and bias, or two devices transmitting at once. |
| Join ring waits and never joins | It joins when it is polled. Check that the trunk has an active master and that your MAC is within the Max Master range being polled. |
| Devices found but points will not read | Check the device's Max APDU. The page reads in smaller batches automatically; very constrained devices read one property at a time and take longer. |
| A write is refused | The error text from the device is shown (for example write-access-denied). Check priority, property and whether the point is commandable. |
| The license will not activate | Paste the complete key including the ECO1- start. Line breaks are fine. Keys expire only if one was issued with an expiry date. |
13. Glossary of on-screen items
These are the same explanations that appear when you hover the “i” icons.
KPI tiles
| Item | Meaning |
|---|---|
| Valid Frames | MS/TP frames that passed every CRC check (the 8-bit header CRC and, where the frame has data, the 16-bit data CRC). Counted since you connected. How to read it: Should climb steadily on a working trunk. If it stays at 0, no readable traffic is arriving: check the baud rate, A/B polarity, and that at least one master is on the bus. |
| Header Crc Errors | Frames whose 8-bit header CRC failed. The source and destination bytes in them are corrupt, so they are never blamed on a particular device. How to read it: A few right after connecting is normal. A steady stream usually means a wrong baud rate, electrical noise, or two devices talking at once. |
| Data Crc Errors | Frames whose header was fine but whose 16-bit data CRC failed. Because the header was good, the sender is known and shows in the Stations tab. How to read it: Errors piling up on one MAC point at that device or its wiring. Errors spread across everyone point at the trunk itself. |
| Error Rate | (Header CRC errors + data CRC errors) divided by all frames decoded, as a percentage. How to read it: Rule of thumb only: well under 1% is usually fine; a number that keeps rising is worth chasing. The sparkline shows the trend over the last minute. |
| Bus Utilization | Bytes received in the recent window × 10 bits (8 data + start + stop) divided by what the line could carry at the selected baud rate. How to read it: MS/TP rings are mostly token and poll traffic, so a quiet trunk still shows some use. A trunk that sits near 100% has no headroom for new traffic. |
| Masters On Ring | Masters that have been seen sending or receiving the token. The second line is how many token passes happen per second. How to read it: If this number is lower than the number of masters you expect, one or more are off the ring (offline, wrong baud, or a bad address). |
| Stray Bytes / Sync Losses | Times the decoder lost frame sync: bytes that did not start a valid frame, or a frame that stopped part-way. The second line is the total bytes received. How to read it: A handful is normal when you connect mid-frame. A high count relative to valid frames can come from noise, missing bias resistors, or a baud mismatch. |
| Masters Joining (Last Min) | Reply-To-Poll-For-Master frames in the last 60 seconds. A master sends one when it answers a poll to say "I am here, let me in". How to read it: One or two when a device powers up is normal. Repeated joins mean masters keep dropping off the ring and coming back. |
Cards and charts
| Item | Meaning |
|---|---|
| Frames Per Second | A two-minute history of frames decoded each second. Blue bars are valid frames; red bars are frames with a CRC error. How to read it: A flat blue wall is a healthy, constantly circulating token. Gaps mean the bus went quiet. Red spikes show when the errors happened. |
| Capture Health | A 0-100 score for a quick read of this capture. It is a heuristic made up for this tool, not a standard. How to read it: Score = 100 − 8 × error-rate % (capped at 40) − 15 per alert − 5 per warning − 10 if the token path is not a complete loop. Use the rows beside it to see what is pulling it down. |
| Frame Mix | How many frames of each MS/TP type have been decoded since connect: Token, Poll For Master, Reply To Poll, Test Request/Response, Data Expecting Reply, Data Not Expecting Reply and Reply Postponed. How to read it: Healthy rings are mostly Token with some Poll For Master. Lots of Data Expecting Reply with few replies back suggests devices that are not answering. |
| Live Bus Monitor | The newest frames decoded, newest first, in a terminal-style view. The timestamp is seconds since connect. How to read it: Good for a quick look at who is talking. The Traffic tab has the full log with filters, pause and CSV export. |
| What The Capture Is Telling You | Plain-English hints generated from counts and addresses in this capture. How to read it: They point at where to look and are not proof of a cause. The Findings tab shows all of them. |
| Station Activity | A heat map: one row per station, one column per second for the last 60 seconds. Each cell is how many frames that station sent in that second. Brighter = more. How to read it: A healthy ring shows every master lit steadily. A row that goes dark has stopped transmitting; a row that flares is a burst of data or retries. Counts are sampled once per screen refresh. |
| Top Talkers | The stations that sent the most frames, as a share of all frames sent, by MAC address. How to read it: On a token ring the shares are usually similar. One MAC far above the rest is chattier than its peers (for example, lots of polling or retries). |
| Ring Snapshot | A small token-ring map drawn from the token passes of the last 15 seconds. How to read it: A closed loop means every master hands the token to the next. See the Ring map tab for the full-size version and legend. |
| Application Layer | BACnet messages decoded from the data frames: Who-Is, I-Am, requests, replies, errors and others, plus a count per service (for example ReadPropertyMultiple). How to read it: Errors above zero are BACnet-level error, reject or abort replies, which are different from CRC errors on the wire. |
| Token Ring | Every master is placed around the circle in address order. Arrows show who passed the token to whom. How to read it: Solid arrows are passes from the last 15 seconds, faint dotted ones are older, amber dashed arrows skip a master that was seen earlier. |
| Ring Status | Whether following the most recent token pass from each master leads all the way around and back to the start. How to read it: "Token path closes" is the healthy state. "Open" means a link in the chain is missing, often a master that dropped off. |
| Responders (Not On The Ring) | Stations that only answer when asked: slaves, or masters that have not joined the ring. How to read it: Slaves never hold the token, so being listed here is normal for them. |
Status bar
| Item | Meaning |
|---|---|
| Mode | LIVE is real traffic from your adapter. DEMO is simulated traffic. IDLE is not connected. LOST means the adapter went away. |
| Baud | The serial speed the adapter is decoding at. How to read it: It must match the trunk. Auto-detect tries the common rates and keeps the one that decodes the most valid frames. |
| Frames | Valid frames decoded since connect. |
| Crc | Header plus data CRC errors since connect. |
| Util | Bus utilization over the recent window. |
| Tokens | Token passes per second. |
| Masters | Masters seen on the token ring. |
| Ring | Closed = the token path loops back to the start. Open = it does not. |
| Node | Whether this page is only listening, or is on the ring as a master (and with which MAC). |
| Devices | Devices found with Who-Is. |
| Pulse | Valid frames decoded per second right now, with the last 24 seconds as a mini bar chart. |
| Up | Time since you connected or started the demo. |
14. Support
Email nathanfalardeau@ecotuneautomation.com with what you were doing, the browser and version, and any message shown. For a trunk problem, a screenshot of the Overview and Findings tabs helps.
BACnet® is a registered trademark of ASHRAE. EcoTune Automation LLC is not affiliated with ASHRAE. © 2026 EcoTune Automation LLC.