What each write command does¶
Every write command refuses on any doubt before it writes, and reports "verified" only after a read-back matches your project. This page lists, per command, what it writes, refuses, backs up and verifies. A refusal exits non-zero before anything is written; the confirmation and real-gateway rules are on Safety.
Warning
Every command on this page transmits on the bus. Point it at the simulator or a bench device until you trust it.
Without a terminal or --yes, assign, adopt, replace and commission
refuse before opening a connection, because their first bus step acts on the
device in programming mode. The other write commands first show what they
would change, then refuse at the prompt.
flash, apply, restore, replace and commission with --flash or
--apply also refuse, on a real gateway, a device whose application program
bussard's device-support list does not
rate proven or likely, before anything is written; a likely device is
written with a line saying it is not confirmed on a real device.
--allow-unsupported writes it anyway; back the device up first. plan,
describe, device, status and audit print the verdict, so you
know before you ask for a write.
write sends one group value¶
- Writes a single group value (
on/off,up/down, a number, a percentage). Nothing is stored on a device, but actuators move. - Refuses a protected group address without
--force, and a secured group address it holds no key for. - Confirms with the address, the decoded value and the gateway, and verifies only that the interface acknowledged the telegram. A group write has no reply from the device, so neither bussard nor an assistant may report that the device executed it.
apply writes links and parameters¶
- Writes the device's link tables (the group address and association
tables) and, when
bussard.lockpins the product data or--productis given, the parameter octets that differ. Tables are rewritten wholesale, so re-runningapplyis idempotent. A device that already matches is not asked about and not written. - Refuses, before the bus is touched, a project that fails validation, a
pinned archive that is missing or changed, and a
--productor--applicationthat contradicts the lock without--force. It refuses a device whose application id or mask differs from the lock, naming thebussard flashit needs, and a parameter change that shows or hides a com-object. With--plan <hash>it refuses a device that no longer matches thestate_hashof the approved plan (plan --json). - Backs up the pre-apply tables to
<dir>/captures/backups/<ia>-<timestamp>.json, and the parameter memory to<dir>/captures/backups/parameters/when parameters change, with the interface-object properties parameters are placed in. If a backup cannot be written, the apply refuses. - Verifies by reading the tables and parameters back. A System 7 table write ends with a basic restart, as in ETS, and the read-back waits for the device to answer again.
The prompt reads apply these N changes to <ia> through <gateway>? [y/N]. To
go back, re-apply from your project or restore the backup. The parameter half is
the parameter-only download.
Device-managed parameters (Access="None", owned by the application at
runtime) always differ from your project. A plan with only those differences is
"nothing to write"; alongside another write they are written at your project's
value, as ETS does.
backup and restore¶
bussard backup is read-only on the bus. It reads every device in your project into
<dir>/captures/backups/<UTC timestamp>/, one JSON file per device plus a
manifest.json that lists every device, including skipped (a mask bussard
cannot read), unreachable and failed (exit 1). On System B it includes the
parameters; on System 7 it cannot. apply hints while no snapshot exists.
bussard restore <backup-dir> <ADDRESS> is apply with the backup as the
desired state: the same plan, confirmation, pre-write backup, verify and gate.
It writes link tables only. A fresh backup restored onto an unchanged device
plans empty and writes nothing.
bussard restore --parameters <backup.json> <ADDRESS> replays a parameter
backup with the parameter-only download. It refuses a backup of another
device, application or mask, and a device that does not run the application.
It writes only placed octets and the parameter properties the backup holds,
keeps device-managed octets as the device holds them, backs up what it
overwrites and verifies by read-back.
restart restarts one device¶
bussard restart <ADDRESS> restarts the device the way ETS's Restart device
does: the device re-runs its application, as a power cycle of that one device
would. Parameters, tables and the address stay. It is what a device needs when
it should take up a change at startup.
- Asks once, naming the device and the gateway, behind the real-gateway gate.
- Picks the form ETS picks from the product data: a System B
application that supports Secure gets the confirmed restart (master reset, erase code
1), which the device answers; every other device gets a bare
A_Restart, which it does not answer. - Verifies a confirmed restart by its answer: only error code 0 counts, and no answer or another code exits 1. A basic restart cannot be verified, so it is reported as sent, not as restarted.
- Checks the device comes back by reconnecting until it answers its
descriptor read again with the mask it reported before the restart. A
device that stays silent past
--timeout(30 s), or comes back as another mask, exits 1. - Acts on the bus: a device may transmit its status objects as it starts, as it does when bus voltage returns. Anything that listens to those addresses sees them.
flash downloads an application¶
- Writes a whole application program: parameters at the vendor defaults
plus the device file's values, and the address, association and
group-object tables from your project's links. The image comes from the archive
bussard.lockpins underproducts/, checked by its SHA-256, or from--product. - Refuses before any bus access a pinned archive that is missing or
changed, and a
--productor--applicationthat contradicts the lock unless--force(which then pins it). On System B it refuses a device whose manufacturer is neither the application's nor its original manufacturer, unless--force. Identity drift against the lock is printed, not refused: a flash is how it is fixed. - Backs up nothing. A factory-fresh device has no prior application to save, and the command says so before it writes:
NOTE: a first flash assumes the device is factory-fresh; no backup is
possible (there is no prior application to save). Recovery from a failed
flash is re-running `bussard flash`.
- Verifies that the application reads back as
Loadedafter the restart and spot-checks the written segments.
The freshness check. Because there is no backup, the read-only pre-flight reads the device's load state (whether an application is loaded) first:
| What the device reports | What flash does |
|---|---|
| No application loaded | Proceeds: the device is factory-fresh. |
An object left Loading or in Error by an interrupted flash |
Proceeds: re-flashing is the recovery. |
| The same application already loaded | Proceeds without --force, with a notice. |
| A different application loaded | Refuses; --force overrides. |
| An application it cannot identify | Refuses; --force overrides. |
| A load state it cannot read | Refuses as unknown; --force overrides. |
A refusal names the resident application and the ways forward: capture the
device first (reconstruct, or apply, which backs up), or --force, which
prints one loud line naming device, gateway and what is destroyed. Unreadable
is never fresh. A loaded System 7 device is asked for its application id
(PID_PROGRAM_VERSION of the application object): an id that names another
application is refused by that id, and otherwise the load state and the first
octets of its code decide whether it runs the same application.
The factory reset (System B). Many applications write only the octets
that differ from a fill byte. An allocation with the fill flag asks the device
to fill the whole segment first, so in that segment no octet of an earlier
image survives; an allocation without it keeps the memory, as ETS's does (the
par procedure of a device that runs the same application then writes the
whole image, and a segment without <Data> leaves the octets no parameter
occupies as the device holds them). flash opens the download with the load
procedure's own unloads, as ETS does on a fresh or a programmed device, and
checks that the device filled: the segment's MCB check where the procedure has
one, otherwise a read of skipped octets after the restart. Only a --force
over another application or an unknown one opens the download of an
application that supports Secure with a confirmed factory reset, which no
captured ETS download sends: it keeps the address, erases application,
parameters, links and the Data Secure keys, waits for the reboot (at most a
minute) and
streams every object in full. A device that refuses or ignores the reset fails
the flash before anything is written. --no-factory-reset leaves it out.
System 7 downloads write every region in full and never reset. An
application that does not support Secure is never reset either: ETS sends it no
master reset, only the download's own unloads, and ends its download with a
bare A_Restart.
Recovery. The download is idempotent: re-run the same `bussard flash
`, and fall back to ETS if that fails. A device is not functional until a flash reports the application `Loaded` and verified. **Connection loss.** A flash survives a dropped device connection and a lost tunnel of up to 60 seconds, and resumes the current step. Longer, it stops with a hint naming the gateway and the device partly written: re-run it. `apply`, `describe`, `reconstruct`, `plan` and `write` reconnect too but do not resume; run them again. A pending group write goes out up to a minute late. A device connection left idle past the device's 6 s timeout (at a confirmation prompt, for example) is reopened at the next request, with no error. ??? note "Details" - **Load-state reads.** System B: `PID_LOAD_STATE_CONTROL` of the application objects (types 3 and 4) and the application id in `PID_PROGRAM_VERSION`; other objects only when no application object reports a state. System 7: each load-state machine. - **Reset.** Only over another or an unknown application (above): master reset, erase code 7. `flash` waits the reboot time the device reports, reconnects and streams every object; the group-object table is not kept after a reset. - **Load-state changes** are confirmed by the state in the device's answer, as ETS does, else read back. After the restart `flash` re-reads the application object's state; a segment whose MCB CRC check passed is not sampled again. If the application is not `Loaded`, everything is read. - **Restart timing.** It waits the reported process time, then probes from 0.5 s after it (1.5 s of quiet after a bare `A_Restart`). A probe waits 500 ms for the acknowledgement and up to 2 s for the answer; a negative `L_Data.con` means "not up yet". `flash -v` prints readiness per restart. - **Reconnect.** An unacknowledged frame or a failed heartbeat logs `gateway connection lost`; bussard sends a DISCONNECT, retries after 1, 2, 4, 8, 8 ... s, logs `gateway connection re-established` and re-sends the frame. A chunked write resumes from the last confirmed chunk. `BUSSARD_TUNNEL_RECONNECT_SECS` changes the 60 s (`0` turns it off). Waits on a restart are covered too; the restart is not re-sent unless the link dropped before the device could receive it. Retries stop 90 s after the first failure. - **Secure tunnel over TCP.** After 5 s of silence it sends a CONNECTIONSTATE_REQUEST and treats 2 more silent seconds as a lost link. `BUSSARD_TCP_READ_DEADLINE_MS` changes the 5 s (`0` turns it off). ## `flash --parameters-only` patches parameters - **Writes** only the parameter octets that differ, on a device that already runs the application, then completes the load and restarts the device. On System B it runs the standard's partial download (Configuration Procedures 03_05_03 ยง3.5.3), as ETS runs the product's `par` procedure: it unloads the parameter object, opens it, re-allocates its segment in Mode 0 (the device keeps the memory and the base), and writes at the base the device reports after the allocation. Where the device moved the segment it writes the whole image there; where the reference reads zero it stops. On System 7 it opens and completes the load-state machine without an allocation. It never factory-resets or touches the link tables. `apply` runs the same download after the tables. - **Backs up** the parameter memory to `