README.md

# usp-js

Helper library for easy usp communication using mqtt over tcp or ws.

- [API documentation for usp-js](https://iopsys.se/usp-js/index.html)
- [BBF's USP reference documentation](https://usp-data-models.broadband-forum.org/tr-181-2-13-0-usp.html)

# Installation

`npm install usp-js`

# Usage

To connect provide necessary info to the default export. (Values will differ depending on setup)

```javascript
const connect = require("usp-js").default;

const run = async () => {
  // Connect
  const usp = await connect({
    host: "my.ip.here",
    username: "username",
    password: "password",
    port: 90001,
    protocol: "ws",
    fromId: "from::id",
    toId: "to::id",
  });

  // Get property
  await usp.get("Device.WiFi.").then(console.log);

  // Disconnect
  await usp.disconnect();
};

run();
```

# API

- Connect

```javascript
// options are based on https://github.com/mqttjs/MQTT.js#mqttconnecturl-options
// they additionaly require fromId and toId, more info: url.here
const usp = await connect(options);
```

- Get

  - get object - all object end with a dot

  ```javascript
  await usp.get("Device.Time.");
  // => {
  //   "CurrentLocalTime": "2020-12-15T12:33:19Z",
  //   "Enable": true,
  //   ...
  // }
  ```

  - get property

  ```javascript
  await usp.get("Device.Time.CurrentLocalTime"); // => "2020-12-15T12:33:19Z"
  ```

  - get multiple paths

  ```javascript
  await usp.get(["Device.WiFi.Radio.1.", "Device.WiFi.Radio.2."]);
  // => [
  // { ... },
  // { ... }
  // ]
  ```

  - get using pattern

  ```javascript
  await usp.get('Device.Ethernet.Interface.[Alias=="WAN"].CurrentBitRate'); // => 0
  ```

  - resolve references in get

  ```javascript
  await usp.get("Device.WiFi.Radio.1.").then(usp.resolve); // => { ... }
  // or if deeper resolution is needed (be careful when using level, going above 3 often causes an infinite reference loop)
  await usp
    .get("Device.WiFi.Radio.1.")
    .then((msg) => usp.resolve(msg, 3 /* level - defaults to 1 */)); // => { ... }
  ```

- Set

  - set object - does not need to have all attributes, but some may be required (check USP Reference)

  ```javascript
  await usp.set("Device.WiFi.Radio.1.", { Name: "radio-1" }); // => void
  ```

  - set object with allowPartial and required attributes

  ```javascript
  await usp.set("Device.WiFi.Radio.1.", { Name: { required: true, value: "radio-1" }, allowPartial: true }); // => void
  ```

  - set property

  ```javascript
  await usp.set("Device.WiFi.Radio.1.Name", "radio-1"); // => void
  ```

- Operate

  ```javascript
  const [ping, cleanPing] = await usp.operate("Device.IP.Diagnostics.IPPing()");
  const results = await ping({ Host: "iopsys.eu" });
  await cleanPing(); // clears ping subscription (optional)
  ```

- Add

  - add with no arguments - adds a new default object

  ```javascript
  await usp.add("Device.NAT.PortMapping."); // => "Device.NAT.PortMapping.3."
  ```

  - add with multiple responses

  ```javascript
  await usp.add("Device.IP.Interface.*.IPv4Address."); // => ['Device.IP.Interface.1.IPv4Address.2.', ... ]
  ```

  - add with arguments - adds a new object with provided values

  ```javascript
  await usp.add("Device.NAT.PortMapping.", {
    Description: "webserver1-set",
    ExternalPort: "80",
    Protocol: "TCP",
    Interface: "Device.IP.Interface.1",
    Enable: "true",
    InternalClient: "192.168.1.125",
    InternalPort: "5000",
  }); // => "Device.NAT.PortMapping.4."
  ```

  - add with with allowPartial and required attributes

  ```javascript
  await usp.add("Device.NAT.PortMapping.", {
    allowPartial: true,
    Description: {
      required: true,
      value: "webserver1-set",
    }
    ExternalPort: "80",
    Protocol: "TCP",
    Interface: "Device.IP.Interface.1",
    Enable: "true",
    InternalClient: "192.168.1.125",
    InternalPort: "5000",
  }); // => "Device.NAT.PortMapping.4."
  ```

- Delete

```javascript
await usp.del("Device.NAT.PortMapping.4."); // => void
```


- Get Supported DM
  
```javascript
await usp.supportedDM("Device.WiFi.")
```
- Get Supported Protocols
  
```javascript
await usp.supportedProto("Device.WiFi.")
```

- Get Instances

```javascript
await usp.instances("Device.WiFi.")
```

- Subscribe

```javascript
const clearSub = await usp.subscribe({ id: '1234', notif: 'ObjectCreation', reference: 'Device.NAT.PortMapping.' }, console.log)
```

 - optional second argument to callback gives access to full message.
  ```javascript
  await usp.subscribe({ id: '1234', notif: 'ObjectCreation', reference: 'Device.NAT.PortMapping.' }, (_, fullMsg) => console.log(fullMsg) )
  ```

- On (WIP)

  Id can be a string or a regexp. Messages, generally, have their id in the form COMMAND@random_string (i.e. NOTIFY@12345).
  (Note: does not add subscription to USP model, instead allows for internal monitoring of received messages)
  Optional second argument to callback gives access to full message.

```javascript
const clear = usp.on(/NOTIFY.*/, (data, msg) => console.log({ data, msg }))
```