Module, Parameter und Services

Die Softwaremodule des rc_cube heißen in der REST-API Nodes und vereinen jeweils bestimmte algorithmische Funktionen. Über folgenden Befehl lassen sich alle Softwaremodule der REST-API mit ihren jeweiligen Services und Parametern auflisten:

curl -X GET http://<host>/api/v1/nodes

Informationen zu einem bestimmten Modul (z.B. rc_stereocamera) lassen sich mit folgendem Befehl abrufen:

curl -X GET http://<host>/api/v1/nodes/rc_stereocamera
Status:

Während der Laufzeit stellt jedes Modul Informationen zu seinem aktuellen Status bereit. Dies umfasst nicht nur den aktuellen Verarbeitungsstatus des Moduls (z.B. running oder stale), sondern die meisten Module melden auch Laufzeitstatistiken oder schreibgeschützte Parameter, sogenannte Statuswerte. Die Statuswerte des rc_stereocamera-Moduls lassen sich beispielsweise wie folgt abrufen:

curl -X GET http://<host>/api/v1/nodes/rc_stereocamera/status

Bemerkung

Die zurückgegebenen Statuswerte sind modulspezifisch und werden im jeweiligen Softwaremodul dokumentiert.

Bemerkung

Statuswerte werden nur gemeldet, wenn sich das jeweilige Modul im Zustand running befindet.

Parameter:

Die meisten Module stellen Parameter über die REST-API des rc_cube zur Verfügung, damit ihr Laufzeitverhalten an den Anwendungskontext oder die Anforderungen angepasst werden kann. Die REST-API ermöglicht es, den Wert eines Parameters zu setzen und abzufragen. Darüber hinaus stellt sie weitere Angaben, wie z.B. den jeweiligen Standardwert und zulässige Minimal- bzw. Maximalwerte von Parametern, zur Verfügung.

Die rc_stereomatching-Parameter lassen sich beispielsweise wie folgt abrufen:

curl -X GET http://<host>/api/v1/nodes/rc_stereomatching/parameters

Der quality-Parameter dieses Moduls könnte wie folgt auf den Wert Full gesetzt werden:

curl -X PUT http://<host>/api/v1/nodes/rc_stereomatching/parameters?quality=Full

oder äquivalent

curl -X PUT --header 'Content-Type: application/json' -d '{ "value": "Full" }' http://<host>/api/v1/nodes/rc_stereomatching/parameters/quality

Bemerkung

Laufzeitparameter sind modulspezifisch und werden in dem jeweiligen Softwaremodul dokumentiert.

Bemerkung

Die meisten Parameter, die die Module über die REST-API anbieten, lassen sich auch über die benutzerfreundliche Web GUI des rc_cube erkunden und austesten.

Bemerkung

Einige der Parameter, die über die REST-API des rc_cube bereitgestellt werden, sind auch über die GigE Vision 2.0/GenICam-Schnittstelle zugänglich. Die Einstellung dieser Parameter über die REST-API und die Web GUI ist verboten, solange ein GenICam-Client verbunden ist.

Zudem bietet jedes Modul, das Laufzeitparameter bereitstellt, auch Services, um die aktuellen Parametereinstellungen zu speichern oder um die Werkseinstellungen aller Parameter wiederherzustellen.

Services:

Einige Module bieten auch Services, die sich über die REST-API aufrufen lassen. Hierzu gehört beispielsweise das oben bereits genannte Speichern und Wiederherstellen von Parametern oder auch das Starten und Stoppen von Modulen. Die Services des Moduls zur Hand-Auge-Kalibrierung lassen sich beispielsweise wie folgt aufrufen:

curl -X GET http://<host>/api/v1/nodes/rc_hand_eye_calibration/services

Um einen Service eines Moduls aufzurufen, wird eine PUT-Anfrage mit servicespezifischen Argumenten für die jeweilige Ressource gestellt (siehe das "args"-Feld des Service-Datenmodells). Beispielsweise lässt sich folgendermaßen eine Bildaufnahme mit dem Stereo-Matching-Modul auslösen:

curl -X PUT --header 'Content-Type: application/json' -d '{ "args": {} }' http://<host>/api/v1/nodes/rc_stereomatching/services/acquisition_trigger

Bemerkung

Die Services und zugehörigen Argumente sind modulspezifisch und werden im jeweiligen Softwaremodul dokumentiert.

Die folgende Liste enthält alle REST-API-Anfragen zum Status des Moduls und seinen Parametern und Services:

GET /nodes

Abruf einer Liste aller verfügbaren Module.

Musteranfrage

GET /api/v1/nodes HTTP/1.1

Musterantwort

HTTP/1.1 200 OK
Content-Type: application/json

[
  {
    "name": "rc_stereocamera",
    "parameters": [
      "fps",
      "exp_auto",
      "exp_value",
      "exp_max"
    ],
    "services": [
      "save_parameters",
      "reset_defaults"
    ],
    "status": "running"
  },
  {
    "name": "rc_hand_eye_calibration",
    "parameters": [
      "grid_width",
      "grid_height",
      "robot_mounted"
    ],
    "services": [
      "save_parameters",
      "reset_defaults",
      "set_pose",
      "reset",
      "save",
      "calibrate",
      "get_calibration"
    ],
    "status": "stale"
  },
  {
    "name": "rc_stereomatching",
    "parameters": [
      "quality",
      "seg",
      "fill",
      "minconf",
      "mindepth",
      "maxdepth",
      "maxdeptherr"
    ],
    "services": [
      "save_parameters",
      "reset_defaults"
    ],
    "status": "running"
  }
]
Antwort-Headers:
 
Statuscodes:
  • 200 OK – Erfolgreiche Verarbeitung (Rückgabe: NodeInfo-Array)
Referenzierte Datenmodelle:
 
GET /nodes/{node}

Abruf von Informationen zu einem einzelnen Modul.

Musteranfrage

GET /api/v1/nodes/<node> HTTP/1.1

Musterantwort

HTTP/1.1 200 OK
Content-Type: application/json

{
  "name": "rc_stereocamera",
  "parameters": [
    "fps",
    "exp_auto",
    "exp_value",
    "exp_max"
  ],
  "services": [
    "save_parameters",
    "reset_defaults"
  ],
  "status": "running"
}
Parameter:
  • node (string) – Modulname (obligatorisch)
Antwort-Headers:
 
Statuscodes:
  • 200 OK – Erfolgreiche Verarbeitung (Rückgabe: NodeInfo)
  • 404 Not Found – Modul nicht gefunden
Referenzierte Datenmodelle:
 
GET /nodes/{node}/parameters

Abruf von Parametern eines Moduls.

Musteranfrage

GET /api/v1/nodes/<node>/parameters?name=<name> HTTP/1.1

Musterantwort

HTTP/1.1 200 OK
Content-Type: application/json

[
  {
    "default": 25,
    "description": "Frames per second in Hz",
    "max": 25,
    "min": 1,
    "name": "fps",
    "type": "float64",
    "value": 25
  },
  {
    "default": true,
    "description": "Switching between auto and manual exposure",
    "max": true,
    "min": false,
    "name": "exp_auto",
    "type": "bool",
    "value": true
  },
  {
    "default": 0.007,
    "description": "Maximum exposure time in s if exp_auto is true",
    "max": 0.018,
    "min": 6.6e-05,
    "name": "exp_max",
    "type": "float64",
    "value": 0.007
  }
]
Parameter:
  • node (string) – Modulname (obligatorisch)
Anfrageparameter:
 
  • name (string) – Schränkt Ergebnisse auf Parameter mit diesem Namen ein (optional).
Antwort-Headers:
 
Statuscodes:
  • 200 OK – Erfolgreiche Verarbeitung (Rückgabe: Parameter-Array)
  • 404 Not Found – Modul nicht gefunden
Referenzierte Datenmodelle:
 
PUT /nodes/{node}/parameters

Aktualisierung mehrerer Parameter.

Musteranfrage

PUT /api/v1/nodes/<node>/parameters HTTP/1.1
Accept: application/json

[
  {
    "name": "string",
    "value": {}
  }
]

Musterantwort

HTTP/1.1 200 OK
Content-Type: application/json

[
  {
    "default": 25,
    "description": "Frames per second in Hz",
    "max": 25,
    "min": 1,
    "name": "fps",
    "type": "float64",
    "value": 10
  },
  {
    "default": true,
    "description": "Switching between auto and manual exposure",
    "max": true,
    "min": false,
    "name": "exp_auto",
    "type": "bool",
    "value": false
  },
  {
    "default": 0.005,
    "description": "Manual exposure time in s if exp_auto is false",
    "max": 0.018,
    "min": 6.6e-05,
    "name": "exp_value",
    "type": "float64",
    "value": 0.005
  }
]
Parameter:
  • node (string) – Modulname (obligatorisch)
JSON-Objekt-Array zur Anfrage:
 
  • parameters (ParameterNameValue) – Liste von Parametern (obligatorisch)
Anfrage-Header:
Antwort-Headers:
 
Statuscodes:
  • 200 OK – Erfolgreiche Verarbeitung (Rückgabe: Parameter-Array)
  • 400 Bad Request – Ungültiger Parameterwert
  • 403 Forbidden – Aktualisierung des Parameters verboten, z.B. weil er aufgrund einer laufenden GigE Vision-Anwendung gesperrt ist oder keine valide Lizenz für dieses Modul vorliegt.
  • 404 Not Found – Modul nicht gefunden
Referenzierte Datenmodelle:
 
GET /nodes/{node}/parameters/{param}

Abruf eines bestimmten Parameters eines Moduls.

Musteranfrage

GET /api/v1/nodes/<node>/parameters/<param> HTTP/1.1

Musterantwort

HTTP/1.1 200 OK
Content-Type: application/json

{
  "default": "H",
  "description": "Quality, i.e. H, M or L",
  "max": "",
  "min": "",
  "name": "quality",
  "type": "string",
  "value": "H"
}
Parameter:
  • node (string) – Modulname (obligatorisch)
  • param (string) – Name des Parameters (obligatorisch)
Antwort-Headers:
 
Statuscodes:
  • 200 OK – Erfolgreiche Verarbeitung (Rückgabe: Parameter)
  • 404 Not Found – Modul oder Parameter nicht gefunden
Referenzierte Datenmodelle:
 
PUT /nodes/{node}/parameters/{param}

Aktualisierung eines bestimmten Parameters eines Moduls.

Musteranfrage

PUT /api/v1/nodes/<node>/parameters/<param> HTTP/1.1
Accept: application/json

{
  "value": {}
}

Musterantwort

HTTP/1.1 200 OK
Content-Type: application/json

{
  "default": "H",
  "description": "Quality, i.e. H, M or L",
  "max": "",
  "min": "",
  "name": "quality",
  "type": "string",
  "value": "M"
}
Parameter:
  • node (string) – Modulname (obligatorisch)
  • param (string) – Name des Parameters (obligatorisch)
JSON-Objekt zur Anfrage:
 
  • parameter (ParameterValue) – zu aktualisierender Parameter als JSON-Objekt (obligatorisch)
Anfrage-Header:
Antwort-Headers:
 
Statuscodes:
  • 200 OK – Erfolgreiche Verarbeitung (Rückgabe: Parameter)
  • 400 Bad Request – Ungültiger Parameterwert
  • 403 Forbidden – Aktualisierung des Parameters verboten, z.B. weil er aufgrund einer laufenden GigE Vision-Anwendung gesperrt ist oder keine valide Lizenz für dieses Modul vorliegt.
  • 404 Not Found – Modul oder Parameter nicht gefunden
Referenzierte Datenmodelle:
 
GET /nodes/{node}/services

Abruf von Beschreibungen aller von einem Modul angebotenen Services.

Musteranfrage

GET /api/v1/nodes/<node>/services HTTP/1.1

Musterantwort

HTTP/1.1 200 OK
Content-Type: application/json

[
  {
    "args": {},
    "description": "Restarts the component.",
    "name": "restart",
    "response": {
      "accepted": "bool",
      "current_state": "string"
    }
  },
  {
    "args": {},
    "description": "Starts the component.",
    "name": "start",
    "response": {
      "accepted": "bool",
      "current_state": "string"
    }
  },
  {
    "args": {},
    "description": "Stops the component.",
    "name": "stop",
    "response": {
      "accepted": "bool",
      "current_state": "string"
    }
  }
]
Parameter:
  • node (string) – Modulname (obligatorisch)
Antwort-Headers:
 
Statuscodes:
  • 200 OK – Erfolgreiche Verarbeitung (Rückgabe: Service-Array)
  • 404 Not Found – Modul nicht gefunden
Referenzierte Datenmodelle:
 
GET /nodes/{node}/services/{service}

Abruf der Beschreibung eines modulspezifischen Services.

Musteranfrage

GET /api/v1/nodes/<node>/services/<service> HTTP/1.1

Musterantwort

HTTP/1.1 200 OK
Content-Type: application/json

{
  "args": {
    "pose": {
      "orientation": {
        "w": "float64",
        "x": "float64",
        "y": "float64",
        "z": "float64"
      },
      "position": {
        "x": "float64",
        "y": "float64",
        "z": "float64"
      }
    },
    "slot": "int32"
  },
  "description": "Save a pose (grid or gripper) for later calibration.",
  "name": "set_pose",
  "response": {
    "message": "string",
    "status": "int32",
    "success": "bool"
  }
}
Parameter:
  • node (string) – Modulname (obligatorisch)
  • service (string) – Name des Service (obligatorisch)
Antwort-Headers:
 
Statuscodes:
  • 200 OK – Erfolgreiche Verarbeitung (Rückgabe: Funktion)
  • 404 Not Found – Modul oder Service nicht gefunden
Referenzierte Datenmodelle:
 
PUT /nodes/{node}/services/{service}

Aufruf des Services eines Moduls: Die benötigten Argumente und die zugehörige Antwort hängt vom Modul und vom Service ab.

Musteranfrage

PUT /api/v1/nodes/<node>/services/<service> HTTP/1.1
Accept: application/json

{
  "args": {}
}

Musterantwort

HTTP/1.1 200 OK
Content-Type: application/json

{
  "name": "set_pose",
  "response": {
    "message": "Grid detected, pose stored.",
    "status": 1,
    "success": true
  }
}
Parameter:
  • node (string) – Modulname (obligatorisch)
  • service (string) – Name des Service (obligatorisch)
JSON-Objekt zur Anfrage:
 
  • service args (Service) – Beispielargumente (obligatorisch)
Anfrage-Header:
Antwort-Headers:
 
Statuscodes:
  • 200 OK – Serviceaufruf erledigt (returns Service)
  • 403 Forbidden – Service-Aufruf verboten, z.B. weil keine valide Lizenz für dieses Modul vorliegt.
  • 404 Not Found – Modul oder Service nicht gefunden
Referenzierte Datenmodelle:
 
GET /nodes/{node}/status

Abruf des Status eines Moduls.

Musteranfrage

GET /api/v1/nodes/<node>/status HTTP/1.1

Musterantwort

HTTP/1.1 200 OK
Content-Type: application/json

{
  "status": "running",
  "timestamp": 1503075030.2335997,
  "values": {
    "baseline": "0.0650542",
    "color": "0",
    "exp": "0.00426667",
    "focal": "0.844893",
    "fps": "25.1352",
    "gain": "12.0412",
    "height": "960",
    "temp_left": "39.6",
    "temp_right": "38.2",
    "time": "0.00406513",
    "width": "1280"
  }
}
Parameter:
  • node (string) – Modulname (obligatorisch)
Antwort-Headers:
 
Statuscodes:
  • 200 OK – Erfolgreiche Verarbeitung (Rückgabe: NodeStatus)
  • 404 Not Found – Modul nicht gefunden
Referenzierte Datenmodelle: