The Dragonfly App exposes a RESTful web API that can be used to access and manipulate the Dragonfly Application. The list of resources and the supported methods is summarized in the following table:
| Purpose | URI | Available HTTP Methods |
|---|---|---|
| Get the status, location and orientation | /api/v1/utils/status | GET |
| Send a configuration | /api/v1/utils/config | PUT |
| Start the positioning | /api/v1/positioning/start | PUT |
| Stop the positioning | /api/v1/positioning/stop | PUT |
| Load a specific map | /api/v1/maps/{map_name} | PUT |
| Reset the current map | /api/v1/manage/maps/reset | PUT |
| Take a snapshot from the camera | /api/v1/utils/snapshot | GET |
Type: GET
Function: get the status of the Dragonfly 3 application along with the exact X,Y,Z coordinates and orientation of the camera.
Request:
- Path parameters: no information is passed along with the request.
- Headers: empty
- Body: empty
- Authorization: none
Response:
- Status: 200 OK.
- Headers:
- Content-type: application/json
- Body: the status of the Dragonfly 3 application as a JSON data structure with these fields:
- “timestamp”: long, the response timestamp
- “isStarted”: boolean, true if the App is started
- “currentMapName”: string, the name of the map loaded in DF3
- “state”: string, the slam state: Navigation, Lost, Mapping, etc.
- “x”: double, current x coordinate of the device
- “y”: double, current y coordinate of the device
- “z”: double, current z coordinate of the device
- “roll”: short, current roll of the device’s camera
- “pitch”: short, current pitch of the device’s camera
- “yaw”: short, current yaw of the device’s camera
- “fps”: double, current fps
- “version”: string, DF3 app version
- “siteId”: string, siteId in which DF3 app is working
- “clientId”: string, clientId in which DF3 app is working
- “deviceId”: string, MAC id of the device in which the DF3 app is running
Example:
Query the status of a Dragonfly instance running locally:
curl http://localhost:5000/api/v1/utils/status
The response is:
{
"clientId":"1",
"currentMapName":"TEST",
"deviceId":"315293C004686CA8",
"fps":9.746588693957115,
"isStarted":true,
"pitch":0,
"roll":0,
"siteId":"0",
"state":4,
"timestamp":1677186214315,
"version":"3.0.0.56",
"x":0.004322106200452303,
"y":0.07388238901420131,
"yaw":0,
"z":0.4808906190837896
}
Type: PUT
Function: configure some of the Dragonfly 3 application parameters
Request:
- Path parameters: no information is passed along with the request.
- Headers: empty
- Body:
- “webserver_port”: unsigned int, the new web port on which DF3 must listen
- “cam_fov”: int, the FOV to be set on the camera image
- “cam_source”: int, the port in which the camera is plugged
- “camera_calibration_file”: string, the local path of the camera calibration file
- “video_recording_enabled”: boolean, enable or disable the video recording
- “position_upload_store”: boolean, enable or disable the upload of the device position to the cloud
- Authorization: none
Response:
- Status: 200 OK.
- Headers:
- Content-type: application/json
- Body: null
Example 1:
Set the camera field of view to 120:
curl -X PUT http://localhost:5000/api/v1/utils/config -d {\"cam_fov\":120}
The response is: null
Example 2:
Set the cam source to 3 and the webserver port to 5001:
curl -X PUT http://localhost:5000/api/v1/utils/config -d {\"cam_source\":3,\"webserver_port\":5001}
The response is: null
Type: PUT
Function: starts the SLAM algorithm for positioning
Request:
- Path parameters: no information is passed along with the request.
- Headers: empty
- Body: empty
- Authorization: none
Response:
- Status: 200 OK.
- Headers:
- Content-type: application/json
- Body: null
Example:
Start the positioning engine:
curl -X PUT http://localhost:5000/api/v1/positioning/start -d ""
The response is: null
Type: PUT
Function: stops the SLAM algorithm for positioning
Request:
- Path parameters: no information is passed along with the request.
- Headers: empty
- Body: empty
- Authorization: none
Response:
- Status: 200 OK.
- Headers:
- Content-type: application/json
- Body: null
Example:
Stop the positioning engine:
curl -X PUT http://localhost:5000/api/v1/positioning/stop -d ""
The response is: null
Type: PUT
Function: load a specific map by its name
Request:
- Path parameters:
- “map_name”: string, name of the map that needs to be loaded
- Header: empty
- Body: empty
- Authorization: none
Response:
- Status: 200 OK.
- Headers:
- Content-type: application/json
- Body: null
Example:
Load map with name “test”:
curl -X PUT http://localhost:5000/api/v1/maps/test
The response is: null
UNDER DEVELOPMENT – UNDER DEVELOPMENT – UNDER DEVELOPMENT – UNDER DEVELOPMENT –
Type: PUT
Function: reset the current map
Request:
- Path parameters: no information is passed along with the request.
- Header: empty
- Body: empty
- Authorization: none
Response:
- Status: 200 OK.
Example:
Reset the current map:
curl -X PUT http://localhost:5000/api/v1/maps/reset
The response is: null
/api/v1/utils/snapshot/snapshot
Type: GET
Function: takes and return a snapshot from the camera used by the Dragonfly 3 application
Request:
- Path parameters: no information is passed along with the request.
- Headers: empty
- Body: empty
- Authorization: none
Response:
- Status: 200 OK.
- Headers:
- Content-type: image/jpeg
- Body: image file
Example:
Collect the current snapshot of the camera:
curl http://localhost:5000/api/v1/utils/snapshot/snapshot
The response is: image file