aes70 1.3.6 → 1.3.8

package/src/controller/ControlClasses/OcaPowerSupply.d.ts

@@ -33,6 +33,16 @@ export declare class OcaPowerSupply extends OcaAgent {
    */
   OnChargingChanged: PropertyEvent<boolean>;
 
+  /**
+   * This event is emitted whenever LoadFractionAvailable changes.
+   */
+  OnLoadFractionAvailableChanged: PropertyEvent<number>;
+
+  /**
+   * This event is emitted whenever StorageFractionAvailable changes.
+   */
+  OnStorageFractionAvailableChanged: PropertyEvent<number>;
+
   constructor(objectNumber: number, device: RemoteDevice);
 
   /**

package/src/controller/ControlClasses/OcaPowerSupply.js

@@ -33,8 +33,8 @@ export const OcaPowerSupply = make_control_class(
     ['ModelInfo', [OcaString], 3, 2, false, false, null],
     ['State', [OcaPowerSupplyState], 3, 3, false, false, null],
     ['Charging', [OcaBoolean], 3, 4, false, false, null],
-    ['LoadFractionAvailable', [OcaFloat32], 3, 5, true, false, null],
-    ['StorageFractionAvailable', [OcaFloat32], 3, 6, true, false, null],
+    ['LoadFractionAvailable', [OcaFloat32], 3, 5, false, false, null],
+    ['StorageFractionAvailable', [OcaFloat32], 3, 6, false, false, null],
     ['Location', [OcaPowerSupplyLocation], 3, 7, true, false, null],
   ],
   []
@@ -126,3 +126,21 @@ export const OcaPowerSupply = make_control_class(
  *
  * @member {PropertyEvent<boolean>} OcaPowerSupply#OnChargingChanged
  */
+/**
+ * This event is emitted when the property LoadFractionAvailable changes in the remote object.
+ * The property ``LoadFractionAvailable`` is described in the AES70 standard as follows.
+ * Fraction of power supply's load capacity that is currently not being
+ * used. Readonly. Normal value range 0...1. A negative value indicates
+ * this data is not available.
+ *
+ * @member {PropertyEvent<number>} OcaPowerSupply#OnLoadFractionAvailableChanged
+ */
+/**
+ * This event is emitted when the property StorageFractionAvailable changes in the remote object.
+ * The property ``StorageFractionAvailable`` is described in the AES70 standard as follows.
+ * Fraction of power supply's energy storage that remains available. For
+ * battery supplies. Readonly. Normal value range 0...1. A negative value
+ * indicates this data is not available.
+ *
+ * @member {PropertyEvent<number>} OcaPowerSupply#OnStorageFractionAvailableChanged
+ */

package/src/controller/ControlClasses/OcaSensor.d.ts

@@ -10,6 +10,11 @@ import { OcaSensorReadingState } from '../../types/OcaSensorReadingState';
  * @class OcaSensor
  */
 export declare class OcaSensor extends OcaWorker {
+  /**
+   * This event is emitted whenever ReadingState changes.
+   */
+  OnReadingStateChanged: PropertyEvent<OcaSensorReadingState>;
+
   constructor(objectNumber: number, device: RemoteDevice);
 
   /**

package/src/controller/ControlClasses/OcaSensor.js

@@ -14,7 +14,7 @@ export const OcaSensor = make_control_class(
   2,
   OcaWorker,
   [['GetReadingState', 3, 1, [], [OcaSensorReadingState]]],
-  [['ReadingState', [OcaSensorReadingState], 3, 1, false, true, null]],
+  [['ReadingState', [OcaSensorReadingState], 3, 1, false, false, null]],
   []
 );
 
@@ -25,3 +25,11 @@ export const OcaSensor = make_control_class(
  * @returns {Promise<OcaSensorReadingState>}
  *   A promise which resolves to a single value of type :class:`OcaSensorReadingState`.
  */
+/**
+ * This event is emitted when the property ReadingState changes in the remote object.
+ * The property ``ReadingState`` is described in the AES70 standard as follows.
+ * Enum that describes whether current reading value is valid and if not,
+ * why not. Readonly.
+ *
+ * @member {PropertyEvent<OcaSensorReadingState>} OcaSensor#OnReadingStateChanged
+ */

package/src/controller/ControlClasses.d.ts

@@ -4,7 +4,6 @@
  * AES70-2018.
  */
 
-import { ObjectBase } from './object_base';
 import { OcaRoot } from './ControlClasses/OcaRoot';
 import { OcaWorker } from './ControlClasses/OcaWorker';
 import { OcaActuator } from './ControlClasses/OcaActuator';

package/src/controller/abstract_udp_connection.js

@@ -0,0 +1,211 @@
+/* eslint-env node */
+
+import { encodeMessage } from '../OCP1/encode_message.js';
+import { decodeMessage } from '../OCP1/decode_message.js';
+import { KeepAlive } from '../OCP1/keepalive.js';
+import { ClientConnection } from './client_connection.js';
+
+function delay(n) {
+  return new Promise((resolve) => setTimeout(resolve, n));
+}
+
+async function waitForKeepalive(socket, options) {
+  const waiter = socket.receiveMessage().then((buffer) => {
+      const pdus = [];
+      let pos = 0;
+
+      pos = decodeMessage(new DataView(buffer), 0, pdus);
+
+      if (pdus.length !== 1) throw new Error('Expected keepalive response.');
+
+      return true;
+    });
+
+  const msg = encodeMessage(new KeepAlive(1000));
+  const t = 5 * (options.retry_interval || 250);
+
+  for (let i = 0; i < 3; i++) {
+    socket.send(msg);
+
+    if (await Promise.race([waiter, delay(t)])) return;
+  }
+
+  throw new Error('Failed to connect.');
+}
+
+/**
+ * :class:`ClientConnection` subclass which implements OCP.1 with UDP
+ * transport.
+ */
+export class AbstractUDPConnection extends ClientConnection {
+  constructor(socket, options) {
+    // allow us to batch 128 bytes max
+    // Set this to a higher value, e.g. close to MTU
+    // if you are sure that the device can handle it.
+    if (!(options.batch >= 0)) options.batch = 128;
+    super(options);
+    this.socket = socket;
+    this.delay = options.delay >= 0 ? options.delay : 5;
+    this.retry_interval =
+      options.retry_interval >= 0 ? options.retry_interval : 250;
+    this.retry_count = options.retry_count >= 0 ? options.retry_count : 3;
+    this._write_out_id = -1;
+    this._write_out_callback = () => {
+      this._write_out_id = -1;
+      this._write_out();
+    };
+    this._retry_id =
+      this.retry_interval > 0
+        ? setInterval(() => this._retryCommands(), this.retry_interval)
+        : -1;
+    this.q = [];
+    socket.onmessage = (buffer) => {
+      try {
+        this.read(buffer);
+      } catch (err) {
+        console.warn('Failed to parse incoming AES70 packet: %o', err);
+      }
+      if (this.inbuf !== null) this.close();
+    };
+    socket.onerror = (err) => this.error(err);
+    this.set_keepalive_interval(1);
+  }
+
+  get is_reliable() {
+    return false;
+  }
+
+  /**
+   * Connect to the given endpoint.
+   *
+   * @param {String} options.host - hostname or ip
+   * @param {number} options.port - port number
+   * @param {number} [options.delay=10] - Delay in ms between individual packets.
+   *    This can be a useful strategy when communicating with devices which
+   *    cannot handle high packet rates.
+   * @param {number} [options.retry_interval=250] - Delay in ms after which a
+   *    command should be automatically re-sent if no response has been
+   *    received, yet.
+   * @param {number} [options.retry_count=3] - Number of times to retry sending
+   *    commands. If no response has been received after all retries, the
+   *    command will fail with an error.
+   * @param {number} [options.batch=128] - Maximum number of bytes to send
+   *    in an individual UDP packet. Note that AES70 messages which are larger
+   *    than this limit are sent anyway. This only limits how many seperate
+   *    messages are batched into a single packet.
+   * @returns {Promise<UDPConnection>}
+   *    The connection.
+   */
+  static async connect(udpApi, options) {
+    const socket = await udpApi.connect(options.host, options.port, options.type);
+
+    await waitForKeepalive(socket, options);
+
+    return new this(socket, options);
+  }
+
+  write(buf) {
+    this.q.push(buf);
+
+    if (this.tx_idle_time() >= this.delay) this._write_out();
+    else this._schedule_write_out();
+  }
+
+  flush() {
+    super.flush();
+    if (this.tx_idle_time() > this.delay) this._write_out();
+  }
+
+  cleanup() {
+    super.cleanup();
+    if (this.socket) {
+      this.socket.close();
+      this.socket = null;
+    }
+    if (this._write_out_id !== -1) {
+      clearTimeout(this._write_out_id);
+      this._write_out_id = -1;
+    }
+    if (this._retry_id !== -1) {
+      clearInterval(this._retry_id);
+      this._retry_id = -1;
+    }
+  }
+
+  _estimate_next_tx_time() {
+    return this._now() + (this.delay + 2) * this.q.length;
+  }
+
+  _write_out() {
+    if (!this.socket) return;
+    const q = this.q;
+
+    if (!q.length) return;
+
+    const buf = q.shift();
+
+    this.socket.send(buf);
+    super.write(buf);
+
+    if (q.length) this._schedule_write_out();
+  }
+
+  _schedule_write_out() {
+    const tx_idle_time = this.tx_idle_time();
+    const delay = this.delay;
+
+    if (tx_idle_time >= delay) {
+      this._write_out();
+      return;
+    }
+
+    // Already scheduled.
+    if (this._write_out_id !== -1) return;
+
+    this._write_out_id = setTimeout(
+      this._write_out_callback,
+      delay - tx_idle_time
+    );
+  }
+
+  _retryCommands() {
+    const now = this._now();
+    const retryTime = now - this.retry_interval;
+    // This is an estimate for how many commands we would manage to send
+    // off.
+    const max = 5 * (this.retry_interval / this.delay) - this.q.length;
+    const pendingCommands = this._pendingCommands;
+
+    const retries = [];
+    const failed = [];
+
+    for (const entry of pendingCommands) {
+      const [, pendingCommand] = entry;
+
+      // All later commands are newer than the cutoff.
+      if (pendingCommand.lastSent > retryTime) break;
+      if (pendingCommand.retries >= this.retry_count) {
+        failed.push(entry);
+      } else if (retries.length < max) {
+        retries.push(entry);
+      }
+    }
+
+    if (failed.length) {
+      const timeoutError = new Error('Timeout.');
+
+      failed.forEach(([handle, pendingCommand]) => {
+        pendingCommands.delete(handle);
+        pendingCommand.reject(timeoutError);
+      });
+    }
+
+    retries.forEach(([handle, pendingCommand]) => {
+      pendingCommands.delete(handle);
+      pendingCommands.set(handle, pendingCommand);
+      this.send(pendingCommand.command);
+      pendingCommand.lastSent = now;
+      pendingCommand.retries++;
+    });
+  }
+}

package/src/controller/client_connection.d.ts

@@ -1,6 +1,6 @@
 import { IConnectionOptions, Connection } from '../connection';
 
-export interface IClientConnectionOptions extends IConnectionOptions {}
+export type IClientConnectionOptions = IConnectionOptions
 
 /**
  * A generic base class for all client connections.

package/src/controller/client_connection.js

@@ -1,7 +1,6 @@
 import { RemoteError } from './remote_error.js';
 import { Connection } from '../connection.js';
 import { Response } from '../OCP1/response.js';
-import { encodeMessage } from '../OCP1/encode_message.js';
 import { KeepAlive } from '../OCP1/keepalive.js';
 import { Notification } from '../OCP1/notification.js';
 import { Arguments } from './arguments.js';
@@ -119,8 +118,12 @@ export class ClientConnection extends Connection {
     return handle;
   }
 
-  send_command(command, returnTypes) {
-    return new Promise((resolve, reject) => {
+  _estimate_next_tx_time() {
+    return this._now();
+  }
+
+  send_command(command, returnTypes, callback) {
+    const executor = (resolve, reject) => {
       const handle = this._getNextCommandHandle();
 
       command.handle = handle;
@@ -134,9 +137,18 @@ export class ClientConnection extends Connection {
 
       this._pendingCommands.set(handle, pendingCommand);
 
-      pendingCommand.lastSent = this._now();
+      pendingCommand.lastSent = this._estimate_next_tx_time();
       this.send(command);
-    });
+    };
+
+    if (callback) {
+      executor(
+        (result) => callback(true, result),
+        (error) => callback(false, error)
+      );
+    } else {
+      return new Promise(executor);
+    }
   }
 
   _removePendingCommand(handle) {

package/src/controller/make_control_class.js

@@ -58,15 +58,35 @@ function implement_method(cls, method) {
 
   const [name, level, index, argumentTypes, returnTypes] = method;
 
-  cls.prototype[name] = function () {
+  cls.prototype[name] = function (...args) {
+    const argumentCount = argumentTypes.length;
+    let callback = null;
+
+    // If there are too few arguments, this might mean
+    //
+    // - that some of them use the default encoding (e.g. 0)
+    // - that the method signature has change in the AES70 version
+    //   used
+    //
+    // this is why we do not error here, yet.
+    if (argumentCount < args.length) {
+      if (
+        argumentCount + 1 === args.length &&
+        typeof args[argumentCount] === 'function'
+      ) {
+        callback = args[argumentCount];
+        args.length = argumentCount;
+      }
+    }
+
     const cmd = new CommandRrq(
       this.ono,
       level,
       index,
-      argumentTypes.length,
-      new EncodedArguments(argumentTypes, Array.from(arguments))
+      argumentCount,
+      new EncodedArguments(argumentTypes, args)
     );
-    return this.device.send_command(cmd, returnTypes);
+    return this.device.send_command(cmd, returnTypes, callback);
   };
 }
 

package/src/controller/node_udp.js

@@ -0,0 +1,141 @@
+/* eslint-env node */
+
+import { createSocket } from 'dgram';
+import { isIPv4, isIPv6 } from 'net';
+import { lookup } from 'dns';
+
+function lookup_address(host) {
+  if (isIPv4(host))
+    return Promise.resolve(host);
+
+  return new Promise((resolve, reject) => {
+    lookup(host, { family: 4 }, (err, address) => {
+      if (err) reject(err);
+      else resolve(address);
+    });
+  });
+}
+
+export class NodeUDP {
+  get onmessage() {
+    return this._onmessage;
+  }
+
+  set onmessage(cb) {
+    if (this._onmessage && cb)
+      throw new Error('Cannot install more than one message callback.');
+
+    this._onmessage = cb;
+    this._notifyMessage();
+  }
+
+  get onerror() {
+    return this._onerror;
+  }
+
+  set onerror(cb) {
+    if (this._onerror && cb)
+      throw new Error('Cannot install more than one error callback.');
+
+    this._onerror = cb;
+    this._notifyError();
+  }
+
+  _notifyMessage() {
+    const onmessage = this.onmessage;
+
+    if (!onmessage) return;
+
+    const inbuf = this._inbuf;
+
+    if (!inbuf.length) return;
+
+    this._inbuf = [];
+
+    for (let i = 0; i < inbuf.length; i++) {
+      onmessage(inbuf[i].buffer);
+    }
+  }
+
+  _notifyError() {
+    const onerror = this.onerror;
+
+    if (!onerror) return;
+
+    const error = this._error;
+
+    if (!error) return;
+    this._error = null;
+
+    onerror(error);
+  }
+  
+  send(buf) {
+    this.socket.send(Buffer.from(buf));
+  }
+
+  receiveMessage(timeout) {
+    return new Promise((resolve, reject) => {
+      if (this._error) {
+        reject(this._error);
+      } else if (this._inbuf.length) {
+        resolve(this._inbuf.shift());
+      } else {
+        this.onmessage = (msg) => {
+          this.onmessage = null;
+          this.onerror = null;
+          resolve(msg);
+        };
+        this.onerror = (err) => {
+          this.onmessage = null;
+          this.onerror = null;
+          reject(err);
+        };
+      }
+    });
+  }
+
+  close() {
+    this.socket.close();
+    this.socket = null;
+  }
+
+  constructor(socket) {
+    this._inbuf = [];
+    this._onmessage = null;
+    this._onerror = null;
+    this.socket = socket;
+    socket.on('message', (msg, rinfo) => {
+      this._inbuf.push(msg);
+      this._notifyMessage();
+    });
+    socket.on('error', (err) => {
+      this._error = err;
+      this._notifyError(err);
+    });
+  }
+
+  static connect(host, port, type) {
+    return lookup_address(host).then((ip) => {
+      return new Promise((resolve, reject) => {
+        const socket = createSocket(type || 'udp4');
+        const onerror = function (ev) {
+          reject(ev);
+        };
+        socket.on('error', onerror);
+        socket.bind(
+          {
+            exclusive: true,
+          },
+          () => {
+            socket.on('connect', () => {
+              resolve(new this(socket));
+              socket.removeListener('error', onerror);
+            });
+            socket.connect(port, host);
+          }
+        );
+      });
+    });
+  }
+}

package/src/controller/remote_device.js

@@ -21,7 +21,6 @@ import * as RemoteControlClasses from './ControlClasses.js';
 
 import { OcaManagerDefaultObjectNumbers } from '../types/OcaManagerDefaultObjectNumbers.js';
 import { OcaNotificationDeliveryMode } from '../types/OcaNotificationDeliveryMode.js';
-import { RemoteError } from './remote_error.js';
 
 function eventToKey(event) {
   const ono = event.EmitterONo;
@@ -248,8 +247,8 @@ export class RemoteDevice extends Events {
     this.connection.close();
   }
 
-  send_command(cmd, returnType) {
-    return this.connection.send_command(cmd, returnType);
+  send_command(cmd, returnType, callback) {
+    return this.connection.send_command(cmd, returnType, callback);
   }
 
   _doSubscribe(event) {