ifm3d command line tool
Overview
ifm3d ships with a command line tool of the same name. The ifm3d command
line tool is used to both introspect the state of a camera as well as mutate
parameters.
To carry out a particular task, you evoke one of the ifm3d
subcommands. To get a listing of available subcommands, you can pass the
--help option.
$ ifm3d --help
ifm3d Command Line Interface (CLI)
Usage: ifm3d [OPTIONS] SUBCOMMAND
Options:
-h,--help Print this help message and exit
-v,--version Print version information
--ip TEXT:IPV4 [192.168.0.69]
IP address of the sensor
--xmlrpc-port UINT [80] XMLRPC port of the sensor
--password TEXT Password for establishing an edit-session with the sensor
--log-level TEXT:{CRITICAL,ERROR,WARN,INFO,DEBUG,VERBOSE,NONE} [WARN]
The minimum severity of messages that will be logged, possible values are in descending order
--log-file TEXT Log to a file instead of stderr
Subcommands:
o3x1xx Interact with the O3X1xx devices
o3d3xx Interact with the O3D3xx devices
ovp8xx Interact with the OVP8xx video processing units
discover Discover ifm devices on the network.
Each of the supported family of cameras, O3X1xx, O3D3xx and OVP8xx, provides specific subcommands that cater to their specific features. To access these, the name of the camera family will be used as the first subcommand, potentially followed by additional commands.
For example, to read out the current configuration on a connected OVP8xx, one would use:
$ ifm3d ovp8xx config get
{
"applications": {
"classes": {
"mcc": {
"instanceSchema": {
"$schema": "http://json-schema.org/draft-07/schema#",
"additionalProperties": false,
"properties": {
"class": {},
"configuration": {},
"data": {},
...
When accessing a device using non-default parameters, one can add global arguments to the command. For example, to read out the current configuration of a connected OVP, at IP 192.168.0.70, one would use:
$ ifm3d ovp8xx config get --ip=192.168.0.70
{
"applications": {
"classes": {
"mcc": {
"instanceSchema": {
"$schema": "http://json-schema.org/draft-07/schema#",
"additionalProperties": false,
"properties": {
"class": {},
"configuration": {},
"data": {},
...
The documentation for each command and subcommand is available using the --help argument.
For example, to display the documentation for the O3D3xx:
$ ifm3d o3d3xx --help
Interact with the O3D3xx devices
Usage: ifm3d o3d3xx [OPTIONS] SUBCOMMAND
Options:
-h,--help Print this help message and exit
Subcommands:
app-types List the application types supported by the sensor.
config Configure sensor settings from a JSON description of the desired sensor state. See also 'dump'.
cp Create a new application on the sensor, bootstrapped from a copy of an existing one.
discover Discover ifm devices on the network.
dump Serialize the sensor state to JSON.
export Export an application or whole sensor configuration into a format compatible with ifm Vision Assistant.
hz Compute the actual frequency at which the FrameGrabber is running.
imager-types List the imager types supported by the sensor.
import Import an application or whole sensor configuration that is compatible with ifm Vision Assistant's export format (*.o3d3xxapp).
jitter Collects statistics on framegrabber (and optionally, image construction) jitter.
ls Lists the applications currently installed on the sensor.
passwd Sets the password on the sensor.
reboot Reboot the sensor
reset Reset the sensor to factory defaults.
rm Deletes an application from the sensor.
swupdate Perform a firmware update on the camera.
time Get/set the current time on the camera.
trace Get trace messages from the internal camera trace buffer.
Configuring
Using the ifm3d CLI can be a quick way to configure or read out parts of the device configuration. It can be used in conjunction with the tool jq to set portions of the configuration, or alternatively a configuration file in JSON format can be used.
For example, to change the name of an OVP8xx device, one can use:
$ echo {} | jq '.device.info.name="My favorite O3R"' | ifm3d ovp8xx config set
Alternatively, a configuration file can be used, by providing its path in the --file argument.
For example:
$ ifm3d ovp8xx config set --file=config.json
To read out a specific subset of the configuration, one can use:
$ ifm3d ovp8xx config get --path "/device/info/name"
{
"device": {
"info": {
"name": "My favorite O3R"
}
}
}
Note
The configuration uses the JSON format, which means that the command-line JSON processor jq can be used to further process the results.
Diagnostic
Device diagnostic
The O3R platforms provides diagnostic to help monitor the health of the system at runtime, and to provide debug information in case troubleshooting help is needed.
To retrieve the currently active diagnostic, one can use:
$ ifm3d ovp8xx diagnostic get
{
"bootid": "2e49ea23-2f03-4965-8d48-fe08e72c23dd",
"events": [],
"timestamp": "1651170509113082016",
"version": {
"diagnostics": "1.0.1",
"euphrates": "1.42.9",
"firmware": "1.20.11.6034"
}
}
In the example above, there is no active diagnostics.
By default, only the active diagnostic is displayed. To filter the diagnostic messages, for example to retrieve all active diagnostics from the “/applications/instances/app0/type” source, use:
$ ifm3d ovp8xx diagnostic get --filter '{"source": "/applications/instances/app0/type", "state": "active"}'
{
"bootid": "7a4ea1e6-1869-4500-bd2d-c32aad956ca9",
"events": [
{
"description": "Short term unstable framerate of ODS input streams. This may happen sporadically (especially after changing the activePorts parameter). This might be caused by an overloaded system (please consider the potential influence of OEM Docker containers).",
"id": 105006,
"name": "ERROR_ODSAPP_UNSTABLE_FRAMERATES",
"severity": "minor",
"source": "/applications/instances/app0/type",
"state": "active",
"stats": {
"count": 1,
"lastActivated": {
"bootid": "7a4ea1e6-1869-4500-bd2d-c32aad956ca9",
"timestamp": "1703415152874733952"
},
"lastDeactivated": {
"bootid": "",
"timestamp": "0"
}
},
"targets": [
{
"description": "Targets one application",
"name": "app",
"node": "/applications/instances/app0"
}
]
},
],
"groups": {
"app0": "minor",
"app1": "not_available",
"app10": "not_available",
"app11": "not_available",
"app12": "not_available",
"app13": "not_available",
"app14": "not_available",
"app15": "not_available",
"app16": "not_available",
"app17": "not_available",
"app18": "not_available",
"app19": "not_available",
"app2": "not_available",
"app3": "not_available",
"app4": "not_available",
"app5": "not_available",
"app6": "not_available",
"app7": "not_available",
"app8": "not_available",
"app9": "not_available",
"port0": "no_incident",
"port1": "no_incident",
"port2": "no_incident",
"port3": "no_incident",
"port4": "not_available",
"port5": "not_available",
"port6": "no_incident"
},
"timestamp": "1703415367567905984",
"version": {
"diagnostics": "1.0.4",
"euphrates": "1.42.16",
"firmware": "1.20.19.6210"
}
}
Service report
In addition to the diagnostic, a service report can be downloaded. The generated ZIP file should be shared with ifm support team when requesting troubleshooting help, as it contains detailed information about the state and configuration of the system.
To download it, use:
$ ifm3d ovp8xx getServiceReport > service_report.zip
$ unzip service_report.zip
$ ls
configuration.json deserializer_info.json diagnostics.json emmc_devices_health.json filesystem_info.txt journalctl.log manifest.json schema.json service_report.zip