iopsys-feed/self-diagnostics/README.md

# Self Test Diagnostics and Reports

Self test diagnostics package provides a set of tools and recipes to run diagnostics/commands and collect logs.

It provides a cli utility called `self-diagnostics`, which executes recipes defined in json files and collect logs.
```bash
# self-diagnostics -h
Generate self diagnostics report

Syntax: /usr/sbin/self-diagnostics [-m|h|l|j]

Options:
  l     List available module(s)
  m     Generate system report of specific module(s)
  j     Enable JSON output
  h     Print this help
```

It also has an uci file to configure the various parameters:

```bash
# cat /etc/config/self-diagnostics
config globals 'globals'
        option extended_spec_dir '/etc/self-diagnostics/spec'
        option exec_timeout '5'
        option report_name 'self-diagnostics-report-$MODEL-$SERIAL'
        option verbose '0'
        option compression_level '9'
```

Here:

| Options            |  Description                    |
| ------------------ | ------------------------------- |
| extended_spec_dir  | Directory path to store 3rd-party/user diagnostics recipes |
| exec_timeout       | Timeout used for each command |
| report_name        | Name of the generated report file, here $MODEL and $SERIAL replaced with ProductModel and SerialNumber |
| verbose            | Logs everythings to logread as well |
| commpression_level | Gzip compression_level 0-9, if not set, then report will not gziped |


It also provide, a rpcd script to expose `self-diagnostics` over ubus

```bash
# ubus -v list self-diagnostics
'self-diagnostics' @2c0b768d
        "list":{}
        "generate":{"modules":"String"}
```

## Recipe(s)

It has core modules and extended modules.

Core module recipes are present in `/usr/share/self-diagnostics/spec/` path, where as
extended module recipes are defined in uci option 'self-diagnostics.globals.extended_spec_dir'

Both the spec directories has recipes to run diagnostics and collect logs, these recipes are defined in json files.

```bash
# ls /usr/share/self-diagnostics/spec/
config.json   network.json  trx69.json    wifi.json
multiap.json  system.json   voice.json
```

Each json file need to follow below structure:

```json
{
  "description": "<Description of module>",
  "dependency": [
    {
      "type": "file",
      "file": "<filepath>"
    }
  ],
  "exec": [
    {
      "description": "<Description of command>",
      "cmd": "<command To Execute>",
      "dependency": [
        {
          "type": "file",
          "file": "<filepath>"
        }
      ]
    },
    {
      "description": "<Next command description>",
      "cmd": "<command to execute>"
    }
  ]
}
```

## How to use

This can be run from command line, ubus , USP-Controller and ACS.

### List available core/extension modules

```bash
# self-diagnostics -l

Core Module(s):
 - config
 - multiap
 - network
 - system
 - trx69
 - voice
 - wifi

Extension Module(s):
```

### Run and collect logs

```bash
# self-diagnostics
/tmp/self-diagnostics-report-EX600-Y.0721140081.tar.gz
```

### List available core/extension modules over ubus

```bash
# ubus call self-diagnostics list
{
        "CoreModules": [
                "config",
                "multiap",
                "network",
                "system",
                "trx69",
                "voice",
                "wifi"
        ],
        "ExtensionModules": [

        ]
}
```

### Run specific module from ubus

```bash
# ubus call self-diagnostics generate '{"modules":"config"}'
{
        "result": "/tmp/self-diagnostics-report-EX600-Y.0721140081.tar.gz"
}
```

## TR-181 Integration


TR-181 (USP) provides an Operate command `Device.SelfTestDiagnostics()` to execute it from USP-controllers.
TR-181 (CWMP) provides a diagnostics object `Device.SelfTestDiagnostics.` for the same, so its can be triggered from ACS as well.

```bash
# ubus call bbfdm operate '{"command":"Device.SelfTestDiagnostics()"}'
{
        "results": [
                {
                        "path": "Device.SelfTestDiagnostics()",
                        "data": "",
                        "output": [
                                {
                                        "Results": "Device.DeviceInfo.VendorLogFile.2",
                                        "Status": "Complete"
                                }
                        ]
                }
        ]
}
```


Once the opreate command is done, it generate a new entry in VendorLogFile, like below:

```bash
# bbfdmd -c get Device.DeviceInfo.VendorLogFile.2.
Device.DeviceInfo.VendorLogFile.2.Alias => cpe-2
Device.DeviceInfo.VendorLogFile.2.Name => /tmp/self-diagnostics-report-EX600-Y.0721140081.tar.gz
Device.DeviceInfo.VendorLogFile.2.MaximumSize => 0
Device.DeviceInfo.VendorLogFile.2.Persistent => 0
```

Which is then can be uploaded to a server using `Device.DeviceInfo.VendorLogFile.{i}.Upload()` operate command.