Command-line Applications and Examples

Most of the example applications presented below use identical parameters when called. In addition to the help output -h|--help and the version -v|--version, these are the computer name or IP address -a|--address and the port -p|--port of the device. The hostname and the IP address(es) of The-Black-Box device is shown on the central display.

The command line tools have in common that on the one hand the periodic execution and on the other hand the console output can be configured.

Note

Unless otherwise specified, integers must be entered in decimal notation. Hexadecimal notation is currently not supported.

Execution Control

Most applications have a parameter that determines the frequency of repetitions -f|--frequency. This parameter (the period) is given in milliseconds. As the execution time is generally infinite, it is possible to terminate the application after a certain number of executions. By specifying --stop and a number, the application is automatically terminated according to the specified number of periods. It is also possible to use --error to specify the number of errors that lead to the termination of the application. For example, by specifying --stop 10 --error 1, the application is executed ten times or terminated automatically after the first error. Specifying -1|--once sets both parameters to one and is therefore equivalent to --stop 1 --error 1.

Note

If an application is started in interactive mode, i.e. the user has to make an input, the parameters presented have no meaning.

Output Control

To control the console output, the severity of the output can be specified. By default, all messages are output. This setting is useful for testing purposes or for troubleshooting. In normal operation, the setting should be set to info using --severity info or in short -s info. Additional trace information are logged specifying --debug. However this options is only required during software development.

The output is sent to the console by default, but can also be logged to a file using the command line parameter -F|--file. A file name must be specified, for example --file log.txt.

The output behavior can be controlled in detail by the parameter -C|--console: either the log messages are output to the standard output stream (logical identifier 1) using --console std or to the error output stream (logical identifier 2) using --console err. These streams can be further processed at operating system level (for example, the streams can be redirected within a shell or forwarded to a pipeline). By specifying --console off or -Coff, the console output is completely suppressed.

JSON Output

To further process the results in other applications or on the operating system, it is possible to return the results in JSON format (single line). To do this, the parameter -J|--json must be specified when calling. To prevent the JSON output from being mixed with the other log messages, these should be switched off using -Coff (see above).

The JSON objects can be roughly divided into three categories: (1) result, (2) acknowledgement, and (3) error. A result message contains a return value whose structure depends on the corresponding call. In the simplest case, if a digital input pin is queried, the result is 0 or 1 (data type: number). In other cases, however, the return can also have a more complex structure according to the JSON possibilities (for example, a data type array or object). In addition, an ISO8601 timestamp is returned as a formatted character string for further processing.

A result object is returned e.g. a value is queried.

{
    "timestamp": "iso8601",
    "result": "return-value"
}

An acknowledgement is returned if no specific return value is expected.

{
    "timestamp": "iso8601",
    "acknowledgement": true
}

An error object is returned if the command could not be executed.

{
    "timestamp": "iso8601",
    "error": {
           "code": 123,
           "message": "msg"
    }
}