You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
{{ message }}
Repository navigation
Commit 8a01853
Browse filesBrowse the repository at this point in the historyBrowse files
Written by the documentation repository's own tools/sync-*.py against MeshBench/meshbench@e589c6c, then built by gen.py. Editing a generated page here is overwritten by the next release.
58 nodes on real firmware, one companion on a loopback port it prints. Point a client at that address; -serial gives a pty instead.
348
+
56 of the fixture's 58 nodes on real firmware - the SDR observer and the emitter boot none - and one companion on a loopback port it prints. Point a client at that address; -serial gives a pty instead.
349
349
350
350
| flag | default | for | meaning |
351
351
|---|---|---|---|
@@ -454,6 +454,8 @@ One panel filling the window, filtered, over a fixed view, closing itself. That
454
454
|`-terrain`|`false`| capture | shade the relief at startup |
455
455
|`-theme`|`dark`| capture | dark or light |
456
456
|`-unverified-wiring`|`false`| result | run boards whose emulation wiring nobody has watched boot yet |
457
+
|`-update-check`|`false`| capture | ask whether a newer release exists shortly after startup, whatever the schedule says |
458
+
|`-update-feed`| none | data | ask this URL whether a newer release exists instead of the published release feed |
457
459
|`-version`|`false`| output | print the version and exit |
**Options and functions** · [Option](#option) · [CodeOf](#codeof)
42
42
@@ -64,6 +64,14 @@ For a script somebody runs repeatedly by hand: the second run carries on from th
64
64
65
65
Note which half you got, because they differ in one important way. Attaching does not own the process and Close leaves it running; launching owns it and Close stops it. Owned reports which happened, so a script that must not take the session down with it can say so.
66
66
67
+
### `AttachTo(ctx context.Context, s Session) (*Workbench, error)`
68
+
69
+
AttachTo connects to a session from Sessions, rather than to an address typed out again.
70
+
71
+
It exists because a TCP session cannot be reattached to by address alone: its token is in its own file and not in the per-user rendezvous file, which two of them share. The row carries the token, so this works where Attach(ctx, Socket(row.Address)) would reach the wrong session or none.
72
+
73
+
Deliberately no "attach to whatever is running": where several are up and none was named, guessing is how a script ends up driving the session somebody else was watching. Ask Sessions, choose, and say which.
Sessions asks this workbench what else is running beside it, for a script that is already attached to one.
210
+
211
+
The same list Sessions returns, with two differences: the row for this session has Self set and is described from the inside rather than by being asked over its own socket, and no row carries a token - a secret that belongs in the 0600 file it came from, not in a reply. So the rows are for choosing by; AttachTo wants one from Sessions.
212
+
199
213
### `(w *Workbench) SetKeepAbove(ctx context.Context, on bool) (bool, error)`
200
214
201
215
SetKeepAbove sets it, and reports what it now is.
@@ -222,6 +236,12 @@ Topics known today: "status" (a new console line) and "snapshot" (a compact summ
222
236
223
237
Verbs is every method this build answers.
224
238
239
+
### `(w *Workbench) VersionCheck() string`
240
+
241
+
VersionCheck says what became of the release check at connect: empty when the two ends compared equal, and a sentence naming what was skipped and why when one of them was not a release build.
242
+
243
+
Reported rather than logged, because a client is a library: a script that wants the line in its output can print it, and one that does not is not made noisy by a rule that did not apply to it.
WaitIdle waits for every job to finish - the honest way to wait out a warm, which is what most of them are.
@@ -1004,6 +1024,23 @@ After time.Duration
1004
1024
Last string
1005
1025
```
1006
1026
1027
+
### VersionMismatch
1028
+
1029
+
VersionMismatch is a released client driving a workbench from a different release, reported at connect rather than discovered later.
1030
+
1031
+
Distinct from ProtocolMismatch, and from a verb's Refused, because a script has to be able to tell "these two were never meant to be used together" from "this build declined what I asked". The remedies have nothing in common.
1032
+
1033
+
```go
1034
+
// Client and Workbench are the releases each end belongs to, as they are
1035
+
// spelled on PyPI, npm and the release page.
1036
+
Client string
1037
+
Workbench string
1038
+
// Said is the workbench's own refusal when it was the end that noticed,
1039
+
// kept whole. Empty when this client noticed first, which happens against
1040
+
// a build old enough to ignore what the client declared.
1041
+
Said string
1042
+
```
1043
+
1007
1044
## Values
1008
1045
1009
1046
### Aimed
@@ -1287,13 +1324,33 @@ Total int `json:"total"`
1287
1324
Starting bool`json:"starting"`
1288
1325
```
1289
1326
1327
+
### Ground
1328
+
1329
+
Ground is what elevation data a study actually had under it, and whether having none of it was a decision.
1330
+
1331
+
Every study answers with the same keys, so a script checks one thing however it asked the question. Chosen is the distinction that matters: a bare-earth run the operator asked for is a legitimate offline result, and one nobody was asked about is the model being quietly more optimistic than its own documented best case.
1332
+
1333
+
```go
1334
+
State string`json:"state"`
1335
+
Chosen bool`json:"chosen"`
1336
+
Note string`json:"note"`
1337
+
TilesSampled int`json:"tiles_sampled"`
1338
+
TilesCached int`json:"tiles_cached"`
1339
+
```
1340
+
1341
+
-`(g Ground) Bare() bool` - Bare reports a study with no elevation under it anywhere, which the propagation model prices as free space: the most optimistic answer it has.
1342
+
1290
1343
### Hello
1291
1344
1292
1345
Hello is what a connection is talking to. Snapshot, read once at connect.
1293
1346
1294
1347
```go
1295
1348
Protocol int`json:"protocol"`
1296
1349
Version string`json:"version"`
1350
+
// Release is the release the workbench belongs to, empty for a build from
1351
+
// a working copy. Version is prose; this is the number the pairing rule is
1352
+
// decided on.
1353
+
Release string`json:"release"`
1297
1354
// Mode is "workbench" or "headless".
1298
1355
Mode string`json:"mode"`
1299
1356
Socket string`json:"socket"`
@@ -1303,6 +1360,10 @@ Verbs int `json:"verbs"`
1303
1360
// start has to be able to ask.
1304
1361
PID int`json:"pid"`
1305
1362
StartedAt time.Time`json:"started_at"`
1363
+
// Project and Nodes are what this session has open, which is what tells
// is pointed at a T-Deck, which is an ordinary thing to do.
1421
1482
Board Board`json:"board"`
1422
1483
FirmwareBoard string`json:"firmware_board"`
1423
-
Sent int`json:"sent"`
1424
-
Heard int`json:"heard"`
1425
-
Selected bool`json:"selected"`
1484
+
// No Sent or Heard: what a node has transmitted and received is on
1485
+
// NodeStat, from the engine's own scoreboard. They were carried here as
1486
+
// well and answered nought for every node in every reply, which reads as a
1487
+
// silent mesh rather than as a field nobody filled in.
1488
+
Selected bool`json:"selected"`
1426
1489
```
1427
1490
1428
1491
### NodeStat
@@ -1565,6 +1628,14 @@ At time.Duration
1565
1628
Every time.Duration
1566
1629
```
1567
1630
1631
+
### Session
1632
+
1633
+
Session is one running workbench: where it answers, what process it is, when it started, and what it has open. Snapshot, read once.
1634
+
1635
+
The description - version, mode, project, node count - is asked of the session while the list is being built, so it is what was true a moment ago rather than what was true when the session started. It is empty for a session too busy to answer in the moment it was asked; the session is still listed, because it is still running.
1636
+
1637
+
-`Sessions() ([]Session, error)` - Sessions lists the workbenches running on this machine, oldest first.
1638
+
1568
1639
### Shot
1569
1640
1570
1641
Shot is a captured display: a PNG written under the node's own work directory, with the frame's dimensions.
Copy file name to clipboardExpand all lines: pages/reference-js.md
-89Lines changed: 0 additions & 89 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -30,93 +30,4 @@ is still reachable, by name, through `call`; the
30
30
31
31
Every export of the Node client - the classes with their constructors, properties and methods, the module functions and the constants - lifted from the JSDoc in `pkg/client-js/meshbench.mjs`, so it cannot drift from the module a script imports. Start at [Scripting a session](scripting.html) for how a session is opened, and the [cookbook](cookbook.html) for whole programs.
One connection to a workbench, and the queue that keeps two callers from interleaving a half-frame on the wire.
44
-
45
-
```js
46
-
newWorkbench(sock, address, callTimeoutMs)
47
-
```
48
-
49
-
**Properties**
50
-
51
-
-`address`
52
-
53
-
### `static Workbench.attach(opts = {})`
54
-
55
-
Open a connection to a running workbench, and do the protocol handshake before handing it back - a workbench speaking a version this client does not understand is refused here, not on whichever call happens to notice.
56
-
57
-
### `Workbench.call(verb, params, timeoutMs)`
58
-
59
-
Run one verb and return its result. Rejects if the workbench has not answered within `timeoutMs` - the default is `DEFAULT_CALL_TIMEOUT_MS`, set at `attach()` via `callTimeoutMs`, the same length Python's socket timeout defaults to. Pass `null` to wait indefinitely for a call known to take a while.
60
-
61
-
### `async Workbench.hello()`
62
-
63
-
Ask the workbench what it is, and refuse a protocol this client does not speak. `attach()` calls this itself before handing back a connection, so calling it again is only useful to re-check.
64
-
65
-
### `Workbench.close()`
66
-
67
-
Close the connection. Any calls still in flight reject.
68
-
69
-
## Errors
70
-
71
-
### WorkbenchError
72
-
73
-
Extends `Error`.
74
-
75
-
A verb the workbench refused, carrying its classification so a caller can tell "no such node" from "the workbench is closing" without matching prose.
76
-
77
-
```js
78
-
newWorkbenchError(message, code)
79
-
```
80
-
81
-
**Properties**
82
-
83
-
-`name`
84
-
-`code`
85
-
86
-
## Module functions
87
-
88
-
### `defaultAddress`
89
-
90
-
```js
91
-
defaultAddress()
92
-
```
93
-
94
-
Where a workbench answers on this operating system unless told otherwise. Matches the Go and Python clients exactly, because the choice is by OS, not by language: all three must name the same address on one machine.
95
-
96
-
## Constants
97
-
98
-
### `PROTOCOL`
99
-
100
-
```js
101
-
exportconstPROTOCOL=1;
102
-
```
103
-
104
-
The wire version this client speaks. A workbench answering anything else is refused rather than failing halfway through a script.
105
-
106
-
### `DEFAULT_CALL_TIMEOUT_MS`
107
-
108
-
```js
109
-
exportconstDEFAULT_CALL_TIMEOUT_MS=300000;
110
-
```
111
-
112
-
How long a call waits for a reply before it gives up, unless a caller says otherwise. Matches the Python client's socket timeout, so a script ported between the two waits the same length of time before it hears about a verb the workbench never answered.
113
-
114
-
### `MAX_UNIX_PATH`
115
-
116
-
```js
117
-
exportconstMAX_UNIX_PATH=104;
118
-
```
119
-
120
-
The shortest sun_path any platform we run on allows: 108 on Linux, 104 on macOS and the BSDs. Matches the Go and Python clients exactly.
![github-actions[bot]](https://avatars.githubusercontent.com/in/15368?v=4&size=40){kind=avatar}
0 commit comments