sen-ether-client 0.1.0

package/API.md

@@ -0,0 +1,239 @@
+# sen-ether-client API
+
+Public import:
+
+```js
+import { Sen, SenInterest, SenRemoteObject } from 'sen-ether-client';
+```
+
+## Compatibility
+
+`sen-ether-client@0.1.x` supports:
+
+- kernel protocol `9`
+- ether protocol `2`
+
+These protocol versions are checked during the SEN handshake. A different
+kernel or ether protocol should be treated as unsupported unless `sen-ether-client`
+explicitly adds support for it.
+
+The protocol STL files are included in `resources/protocol` as the source for
+the codec. The SEN release noted in that folder is informational; it is not a
+compatibility check.
+
+The generated protocol module is loaded at runtime; STL parsing is a maintenance
+step, not part of connection or message decoding.
+
+## Sen
+
+```js
+const sen = await Sen.connect();
+
+// with explicit options:
+const sen = new Sen(options);
+await sen.connect(options);
+```
+
+Connection options:
+
+- `interfaceAddress`: local interface address or interface name for multicast
+  discovery.
+- `tcpHub`: optional SEN TCP discovery hub as `host:port`. If omitted,
+  multicast discovery is used.
+- `session`: optional SEN session name. If omitted, `Sen` can use queries for
+  different sessions and connects to each one on demand.
+- `timeout`: discovery and operation timeout in ms.
+- `discoverySettleMs`: discovery settle time after the first process is found.
+  Defaults to `100`.
+- `reconnect`: whether to reconnect and restart interests.
+- `reconnectDelayMs`: delay between reconnect attempts.
+- `maxReconnectAttempts`: maximum reconnect attempts.
+- `participantReadyTimeoutMs`: short non-fatal grace timeout for bus
+  participant acknowledgements. Defaults to `1000`.
+- `socketKeepAlive`: enable TCP keepalive. Defaults to `true`.
+- `socketIdleTimeoutMs`: optional TCP idle timeout. Defaults to `0` because
+  valid SEN connections can be quiet on TCP while bus data flows separately.
+
+`Sen.connect()` uses multicast discovery. `sen-ether-client` reads this SEN environment
+variable as its multicast default:
+
+- `SEN_ETHER_DISCOVERY_PORT`
+
+Multicast group, bind address and interface selection are explicit `sen-ether-client`
+options, not SEN environment variables.
+
+Preferred multi-session usage:
+
+```js
+const sen = await Sen.connect();
+
+const hmi = await sen.interest('SELECT * FROM hmi.diagnostics');
+const world = await sen.interest('SELECT * FROM world1.environment');
+```
+
+TCP discovery hub usage:
+
+```js
+const sen = await Sen.connect({ tcpHub: '127.0.0.1:65222' });
+```
+
+Explicit single-session usage is still supported:
+
+```js
+const hmi = await Sen.connect({ session: 'hmi' });
+await hmi.interest('SELECT * FROM hmi.diagnostics');
+```
+
+If a SEN bus name itself contains dots and is not a session-qualified bus, pass
+it explicitly. This is useful for standalone scenarios that run in one Ether
+session but publish on a bus such as `scenario.environment`:
+
+```js
+const scenario = await Sen.connect({
+  session: 'scenario'
+});
+
+const objects = await scenario.interest('SELECT * FROM scenario.environment', {
+  bus: 'scenario.environment',
+  forceBus: true
+});
+```
+
+Main methods:
+
+- `await sen.connect(options)`
+- `await sen.interest(query, options)`
+- `await sen.session(name)`
+- `sen.listSessions()`
+- `sen.listBuses(options)`
+- `await sen.bus(name, options)`
+- `sen.objects()`
+- `sen.getObject(selector)`
+- `await sen.waitForObject(selector, options)`
+- `await sen.close()`
+
+Session and bus navigation:
+
+```js
+const sen = await Sen.connect();
+
+for (const sessionName of sen.listSessions()) {
+  const session = await sen.session(sessionName);
+  console.log(sessionName, session.listBuses());
+}
+
+const diagnostics = await sen.session('hmi').then(hmi => hmi.bus('diagnostics'));
+```
+
+Main events:
+
+- `connect`
+- `close`
+- `reconnecting`
+- `reconnect`
+- `reconnectError`
+- `warning`
+- `object`
+- `remove`
+- `change`
+- `event`
+
+## SenInterest
+
+Returned by `await sen.interest(query)`.
+
+```js
+const interest = await sen.interest('SELECT * FROM hmi.diagnostics');
+const object = await interest.waitFor('EtherProbe');
+```
+
+Main methods:
+
+- `interest.objects()`
+- `interest.get(selector)`
+- `await interest.waitFor(selector, options)`
+- `interest.close()`
+
+Main events:
+
+- `object`
+- `remove`
+- `change`
+- `changes`
+- `event`
+- `stale`
+- `restart`
+
+For browser gateways or high-frequency telemetry, request only the properties
+you need and emit batches instead of one JS event per property update:
+
+```js
+const tracks = await sen.interest('SELECT hmi.tactical.BaseTrack FROM hmi.loadtest', {
+  properties: ['latitude', 'longitude', 'altitude', 'trackHeading'],
+  changeMode: 'batch',
+  batchIntervalMs: 16,
+  batchMaxSize: 1000,
+  maxQueuedChanges: 10000,
+  backpressure: 'drop-oldest',
+  coalesce: true
+});
+
+tracks.on('changes', ({ changes, dropped }) => {
+  // Send one compact WebSocket frame to the browser.
+});
+```
+
+`changeMode: 'individual'` is the default and preserves the traditional
+`change`/`change:<property>` events. `changeMode: 'both'` emits both forms.
+
+## SenRemoteObject
+
+Returned by `interest.waitFor(...)`, `interest.getObject(...)`, or
+`sen.getObject(...)`.
+
+```js
+console.log(await object.get('label'));
+await object.set('label', 'from-js');
+console.log(await object.call('ping', ['hello']));
+```
+
+Main properties:
+
+- `id`
+- `name`
+- `className`
+- `snapshot`
+- `timestampNs`: latest SEN source timestamp as a nanosecond `BigInt`
+- `propertyTimestamps`: `Map<string, bigint>` with the latest known timestamp per property
+
+Main methods:
+
+- `object.matches(selector)`
+- `await object.waitForType(options)`
+- `await object.get(property)`
+- `object.getPropertyTimestamp(property)`
+- `await object.set(property, value)`
+- `await object.call(method, args)`
+
+Main events:
+
+- `change`
+- `change:<property>`
+- SEN runtime event names emitted by the remote object.
+- `stale`
+
+`change.timestampNs` is also a nanosecond `BigInt`. This keeps SEN's original
+64-bit timestamp precision. Convert it explicitly at JSON boundaries:
+
+```js
+tracks.on('change', ({ object, name, value, timestampNs }) => {
+  websocket.send(JSON.stringify({
+    object: object.name,
+    name,
+    value,
+    timestampNs: timestampNs?.toString()
+  }));
+});
+```
+
+Low-level protocol modules are intentionally not public API.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Marcos Pérez
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,227 @@
+# sen-ether-client
+
+JavaScript client for SEN from Node.js.
+
+[SEN](https://github.com/airbus/sen) is a general-purpose, distributed,
+object-oriented system for applications that demand high modularity and rich
+communication.
+
+```js
+import { Sen } from 'sen-ether-client';
+
+const sen = await Sen.connect();
+
+const diagnostics = await sen.interest('SELECT * FROM hmi.diagnostics');
+const probe = await diagnostics.waitFor('EtherProbe');
+
+probe.on('change:label', ({ value }) => {
+  console.log('label changed:', value);
+});
+
+console.log(await probe.get('label'));
+await probe.set('label', 'from-js');
+console.log(await probe.call('ping', ['hello']));
+
+await sen.close();
+```
+
+## Install
+
+```bash
+npm install sen-ether-client
+```
+
+## Compatibility
+
+`sen-ether-client` speaks SEN ether directly, so compatibility is tied to SEN protocol
+versions, not to a specific SEN release name.
+
+| sen-ether-client | Kernel protocol | Ether protocol |
+| --- | ---: | ---: |
+| 0.1.x | 9 | 2 |
+
+If a remote kernel reports another kernel or ether protocol version during the
+SEN handshake, `sen-ether-client` treats it as incompatible until that protocol version
+is explicitly supported.
+
+The protocol STL files used to maintain this codec are shipped in
+`resources/protocol`. The source SEN release recorded there is informational;
+runtime compatibility is checked only with the kernel and ether protocol
+numbers announced by the remote process.
+
+The runtime imports generated protocol constants from those STL files, so the
+hot path does not parse STL while receiving updates.
+
+## Connect
+
+By default, `sen-ether-client` uses SEN ether multicast discovery and connects to the
+visible SEN processes:
+
+```js
+const sen = await Sen.connect();
+```
+
+If your SEN ether discovery port is configured through SEN's environment,
+`sen-ether-client` reads the same variable:
+
+```bash
+export SEN_ETHER_DISCOVERY_PORT=60543
+```
+
+For machines with more than one network interface, select the multicast
+interface explicitly with either its IPv4 address or interface name:
+
+```js
+const sen = await Sen.connect({ interfaceAddress: 'enp0s25' });
+```
+
+If your setup uses a SEN TCP discovery hub instead of multicast, pass it
+explicitly:
+
+```js
+const sen = await Sen.connect({
+  tcpHub: '127.0.0.1:65222'
+});
+```
+
+`sen-ether-client` can work with several SEN sessions from the same client. The session
+is inferred from the query:
+
+```js
+const hmi = await sen.interest('SELECT * FROM hmi.diagnostics');
+const world = await sen.interest('SELECT * FROM world1.environment');
+```
+
+You can also navigate explicitly through sessions and buses:
+
+```js
+const sen = await Sen.connect();
+
+console.log(sen.listSessions());
+
+const hmi = await sen.session('hmi');
+console.log(hmi.listBuses());
+
+const diagnostics = await hmi.bus('diagnostics');
+const probe = await diagnostics.waitFor('EtherProbe');
+```
+
+You can also connect to one explicit session:
+
+```js
+const hmi = await Sen.connect({
+  session: 'hmi'
+});
+
+const diagnostics = await hmi.interest('SELECT * FROM hmi.diagnostics');
+```
+
+## Interests
+
+Create an interest with a normal SEN query:
+
+```js
+const tracks = await sen.interest('SELECT * FROM world1.environment');
+```
+
+Listen for objects and changes:
+
+```js
+tracks.on('object', object => {
+  console.log(object.name, object.className);
+});
+
+tracks.on('change', ({ object, name, value }) => {
+  console.log(object.name, name, value);
+});
+```
+
+For browser gateways or high-frequency telemetry, batch changes and decode only
+the properties needed by the UI:
+
+```js
+const tracks = await sen.interest('SELECT hmi.tactical.BaseTrack FROM hmi.loadtest', {
+  properties: ['latitude', 'longitude', 'altitude', 'trackHeading'],
+  changeMode: 'batch',
+  coalesce: true
+});
+
+tracks.on('changes', ({ changes }) => {
+  websocket.send(JSON.stringify(changes.map(({ object, name, value, timestampNs }) => ({
+    object: object.name,
+    name,
+    value,
+    timestampNs: timestampNs?.toString()
+  }))));
+});
+```
+
+Get an object by name, id, class name, or predicate:
+
+```js
+const aircraft = await tracks.waitFor('blue-air-1');
+
+const firstAircraft = await tracks.waitFor(
+  object => object.className === 'rpr.Aircraft'
+);
+```
+
+## Objects
+
+Read and write properties:
+
+```js
+const label = await probe.get('label');
+await probe.set('label', 'ready');
+```
+
+Call methods:
+
+```js
+const result = await probe.call('ping', ['hello']);
+```
+
+Subscribe to property changes:
+
+```js
+probe.on('change:label', ({ value, previous, timestampNs }) => {
+  console.log(previous, '->', value, timestampNs);
+});
+```
+
+SEN timestamps are exposed as nanosecond `BigInt` values (`timestampNs`) so the
+64-bit source timestamp is not rounded by JavaScript numbers.
+
+Subscribe to SEN runtime events:
+
+```js
+probe.on('probeEvent', event => {
+  console.log(event.args);
+});
+```
+
+## CLI
+
+List visible SEN processes:
+
+```bash
+npx sen-ether-scan --tcp-hub 127.0.0.1:65222 --timeout 3000
+```
+
+Probe a bus:
+
+```bash
+npx sen-ether-probe \
+  --tcp-hub 127.0.0.1:65222 \
+  --bus hmi.diagnostics
+```
+
+## API
+
+The public import is:
+
+```js
+import { Sen, SenInterest, SenRemoteObject } from 'sen-ether-client';
+```
+
+See [API.md](./API.md) for the complete public interface.