Skip to content

API Reference

Jump to bottom
Ana Cristina Franco da Silva edited this page Jul 16, 2019 · 23 revisions

The MBP provides an API for the management of devices, operators, sensors and actuators. Furthermore, an interface to trigger the binding of sensors and actuator is as well provided. Sensor and actuator values sent to the MBP can be retrieved.

Management of Devices
Management of Sensor and Actuator Operators
Management of Sensors
Management of Actuators
Management of Application Settings

Management of Devices

  • Registering a new device. To register an IoT device (e.g., a Raspberry Pi) in the MBP, use the following request. The id of the registered device is returned in the response as the header location and in the response body (json-formatted).
POST /api/devices/ HTTP/1.1  
Content-Type: application/json  
accept: application/json

{
  "name": "Raspberry Pi",
  "macAddress": "123456789067",
  "ipAddress": "192.168.0.34",
  "formattedMacAddress": "12-34-56-78-90-67",
  "username": "pi",
  "rsaKey": "-----BEGIN RSA PRIVATE KEY-----\nMIIEogIBAAKC...\n-----END RSA PRIVATE KEY-----"
}
HTTP/1.1 201 Created  
location: http://localhost:8080/MBP/api/devices/5a033094c27074e37bbb198b  
Content-Type:
application/json;charset=UTF-8

{
  "id": "5a033094c27074e37bbb198b",
  "name": "Raspberry Pi",
  "macAddress": "123456789067",
  "ipAddress": "192.168.0.34",
  "username": "pi",
  "date": null,
  ...
}
  • Retrieving all registered devices. To receive a list of all registered devices in the MBP, use the following request.
GET /api/devices/ HTTP/1.1  
HTTP/1.1 200 OK

[
  {
    "macAddress": "123456789067",
    "ipAddress": "192.168.0.34",
    "name": "Raspberry Pi",
    "id": "596c7a7d4f0c58688e5aa6b1",
    "date": null,
  }, ...
]
  • Retrieving a device. To retrieve the information about a device (e.g., with registered id 596c7), use the following request.
GET /api/devices/596c7 HTTP/1.1
HTTP/1.1 200 OK

{
  "macAddress": "123456789067",
  "ipAddress": "192.168.0.34",
  "name": "Raspberry Pi",
  "id": "596c7",
  "date": null,
  "username": "pi",
}
  • Updating device information. To update the information of a device (e.g., with registered id 596c7), use the following request.
PUT /api/devices/596c7 HTTP/1.1

{
  "name": "Raspberry Pi",
  "macAddress": "127556789067",
  "ipAddress": "192.168.0.75",
  "formattedMacAddress": "12-75-56-78-90-67",
  "username": "pi",
  "rsaKey": "-----BEGIN RSA PRIVATE KEY-----\nMIIEogIBAAKC...\n-----END RSA PRIVATE KEY-----"
}
HTTP/1.1 204 No Content
  • Removing a device. To unregister a device (e.g., with registered id 596c7), use the following request.
DELETE /api/devices/596c7 HTTP/1.1
HTTP/1.1 204 No Content

Management of Sensor and Actuator operators

An extraction/control operator is the required software (e.g., python script) to bind sensors and actuators to the MBP. Examples to such operators can be found in MBP Operators Repository. Each operator shall be composed of at least the files install.sh and start.sh. Furthermore, by including the files running.sh and stop.sh in the operator, it allows the MBP to check if the operator is currently running and to stop it.

  • Creating a new operator. To create a new operator for a sensor or an actuator, use the following request. The id of the newly created operator is returned in the response as the header location and in the response body (json-formatted).
POST /api/adapters/ HTTP/1.1
Content-Type: application/json  
accept: application/json  

{
  "name": "TemperatureSensorAdapter",
  "description": "An adapter for the LK temperature sensor",
  "service": {
    "name": "service-stub.conf",
    "content": "stub conf"
  },
  "routines": [{
    "name": "service-stub.py",
    "content": "service code"
  }]
}
HTTP/1.1 201 Created  
location: http://localhost:8080/MBP/api/adapters/5a0336ba972ca8734022d67c
Content-Type: application/json;charset=UTF-8

{
  "id": "5a0336ba972ca8734022d67c",
  "name": "TemperatureSensorAdapter",
  "description": "An adapter for the LK temperature sensor",
  ...
}
  • Retrieving all operators. To get a list of all existing operators, use the following request.
GET /api/adapters/ HTTP/1.1
HTTP/1.1 200 OK

[
  {
    "name": "TemperatureSensorAdapter",
    "id": "596c7c344f0c58688e5aa6b3",
    "description": "An adapter for the LK temperature sensor"
  }, ...
]
  • Retrieving an operator. To retrieve an existing operator (e.g., with id 596c7), use the following request.
GET /api/adapters/596c7 HTTP/1.1
HTTP/1.1 200 OK

{
  "name": "TemperatureSensorAdapter",
  "id": "596c7",
  "description": "An adapter for the LK temperature sensor"
}
  • Updating an operator. To update an operator (e.g., with id 596c7), use the following request.
PUT /api/adapters/596c7 HTTP/1.1

{
  "name": "TemperatureSensorAdapter",
  "description": "An adapter for the LK temperature sensor",
  "service": {
    "name": "service-stub.conf",
    "content": "..."
  },
  "routines": [{
    "name": "service-stub.py",
    "content": "..."
  }]
}
HTTP/1.1 204 No Content
  • Deleting an operator. To delete an operator (e.g., with id 596c7), use the following request.
DELETE /api/adapters/596c7 HTTP/1.1
HTTP/1.1 204 No Content

Management of Sensors

To register a sensor, it is necessary to register first:
(i) the device to which the sensor is connected to, and
(ii) the extraction operator, i.e., the required software (e.g., python script) to bind the sensor to the MBP.

  • Registering a new sensor. The following example uses the previously registered operator (id = 596c7) and device (id = 596c7). The id of the newly created sensor can be parsed from the response header location or from the response body, which is in json format.
POST /api/sensors/ HTTP/1.1  
Content-Type: application/json  
accept: application/json  

{
  "name": "Temperature Sensor",
  "adapter": "<URL>/api/adapters/596c7",
  "device": "<URL>/api/devices/596c7",
}
HTTP/1.1 201 Created  
location: http://localhost:8080/MBP/api/sensors/596c7  
Content-Type: application/json;charset=UTF-8

{
  "id": "596c7",
  "name": "test_sensor",
  ...
}
  • Retrieving all sensors. To get a list of all registered sensors, use the following request.
GET /api/sensors/ HTTP/1.1
HTTP/1.1 200 OK

[
  {
    "id": "596c7a974f0c58688e5aa6b2",
    "name": "test_sensor",
    "_embedded": {
      "device": {
        "macAddress": "111111111111",
        "ipAddress": null,
        "name": "Test_Device",
        "id": "596c7a7d4f0c58688e5aa6b1",
        "date": null
      }
    }
  }, ...
]
  • Retrieving a sensor. To retrieve information about a registered sensor (e.g., with id 596c7), use the following request.
GET /api/sensors/596c7 HTTP/1.1
HTTP/1.1 200 OK

{
  "id": "596c7",
  "name": "test_sensor",
  "_embedded": {
    "device": {
      "macAddress": "111111111111",
      "ipAddress": null,
      "name": "Test_Device",
      "id": "596c7a7d4f0c58688e5aa6b1",
      "date": null
    }
  }
}
  • Updating sensor information. To update the information about a sensor (e.g., with registered id 596c7), use the following request.
PUT /api/sensors/596c7 HTTP/1.1

{
  "name": "Temperature Sensor",
  "adapter": "<URL>/api/adapters/596c7c344f0c58688e5aa6b3",
  "device": "<URL>/api/devices/596c7a7d4f0c58688e5aa6b1",
}
HTTP/1.1 204 No Content
  • Removing a sensor. To remove a registered sensor (e.g., with id 596c7), use the following request.
DELETE /api/sensors/596c7 HTTP/1.1
HTTP/1.1 204 No Content
  • Deploying the extraction operator for a sensor. To deploy the extraction operator for a registered sensor (e.g., with id 596c7) onto the device, to which this sensor is connect, use the following request. Once the deployment is done, the sensor values are sent to the MBP and can be visualized in the sensor dashboard.
POST /api/deploy/sensor/596c7 HTTP/1.1
HTTP/1.1 201 Created
  • Retrieving all sensor values. To get a list of all sensor values sent to the MBP of a registered sensor (e.g., with id 5b068), use the following request.
GET /api/valueLogs/search/findAllByIdref?idref=5b068 HTTP/1.1
HTTP/1.1 200 OK

{
  "_embedded" : {
    "valueLogs" : [ {
      "qos" : 0,
      "topic" : "sensor/5b068",
      "message" : "{\"component\": \"SENSOR\", \"id\": \"5b068\", \"value\": \"42\"}",
      "date" : "2018-05-30 10:48:41",
      "idref" : "5b068",
      "component" : "SENSOR",
      "value" : "42",
      "_links" : {
        "self" : {
          "href" : "http://192.168.209.189:8080/MBP/api/valueLogs/5b0e81898315295d360367b0"
        },
        "valueLog" : {
          "href" : "http://192.168.209.189:8080/MBP/api/valueLogs/5b0e81898315295d360367b0"
        },
        "sensorRef" : {
          "href" : "http://192.168.209.189:8080/MBP/api/valueLogs/5b0e81898315295d360367b0/sensorRef"
        },
        "actuatorRef" : {
          "href" : "http://192.168.209.189:8080/MBP/api/valueLogs/5b0e81898315295d360367b0/actuatorRef"
        }
      }
    }, {...}
  }
}

To retrieve sensor values so that they are ordered by date, where the first value was the last value received, use:

/api/valueLogs/search/findAllByIdref?idref=5b068&sort=date,desc

To retrieve only the last sensor value, use:

/api/valueLogs/search/findAllByIdref?idref=5b068&page=0&size=1&sort=date,desc
  • Undeploying extraction operator of a sensor. To undeploy the extraction operator of a registered sensor (e.g., with id 596c7), which is running in the corresponding device, use the following request. Once the undeployment is done, the sensor values will not be sent to the MBP anymore and the operator scripts will be deleted from the device.
DELETE /api/deploy/sensor/596c7 HTTP/1.1
HTTP/1.1 204 No Content

Management of Actuators

see management requests for sensors, replace /sensors with /actuators

Management of Application Settings

There are some application-wide settings that can be changed by the user during runtime. This can be done with the following requests.

  • Retrieving application settings.
GET /api/settings HTTP/1.1
HTTP/1.1 200 OK

{
  "brokerLocation": "REMOTE",
  "brokerIPAddress": "129.69.185.190"
}
  • Changing application settings.
POST /api/settings HTTP/1.1
Content-Type: application/json
accept: application/json

{
  "brokerLocation": "REMOTE",
  "brokerIPAddress": "129.69.185.190"
}
HTTP/1.1 200 OK

Universität Stuttgart - MBP Team 🔧

MBP logo

Clone this wiki locally