README.md

# usp-js

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

[USP Reference](https://usp-data-models.broadband-forum.org/tr-181-2-13-0-usp.html)

# Installation
`npm install usp-js`

# Usage

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

const run = async () => {
  // Connect
  const usp = await connect({
    host: "192.168.1.1",
    username: "admin",
    password: "admin"
  });

  // 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
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 property
  ```javascript
  await usp.set("Device.WiFi.Radio.1.Name", "radio-1"); // => void
  ```

- Operate - WIP (response message not working yet)

  - operate without no arguments
  ```javascript
  await usp.operate("Device.SelfTestDiagnostics()");
  ```

  - operate with arguments (for required args check USP Reference)
  ```javascript
  await usp.operate("Device.IP.Diagnostics.IPPing()", { Host: "iopsys.eu" });
  ```


- Add

  - add with no arguments - adds a new default object
  ```javascript
  await usp.add("Device.NAT.PortMapping.");  // => "Device.NAT.PortMapping.3."
  ```

  - 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."
  ```

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