JSON
JSON API provides a way to access and control Skycharge charging pads through the cloud server (broker server) sending and receiving HTTP requests and responses. This means that a charging pad needs Internet access.
In order to access charging pad devices firstly you need to get a list of them. Each HTTP request should contain a 'user-uuid' parameter, a key which identifies a user. There is a special user UUID dedicated for testing purposes: 00000000-0000-0000-0000-000000000000. This UUID always has a dummy device, which can be accessed and controlled through the API for the testing sake.
Each response is a JSON object containing mandatory 'errno' field, which describes the status of the operation. The 'errno' field takes the 'SUCCESS' value if operation succeeded, or one of the error names specified by POSIX.1 standard.
Each request to the charging device can be timed out after 10 seconds, if there is a connection problem between the device and Skycharge broker server and no response is received. In that case any request ends with JSON response with 'errno' field set to 'ETIMEDOUT' error status.
A request rate-limit is set for each user and by default, the limit is equal to 3 requests per second. If you need higher rate, please write to [email protected]. If rate-limit is exceeded, "Too Many Requests" (429) HTTP status code will be returned.
Get the charging devices list
GET /v1/devs-list
Returns JSON list of charging pads devices dedicated to the specified user (customer), where 'device-uuid' is a UUID of the charging device which should be used as a HTTP key-value parameter for all further device requests.
curl 'https://api.skycharge.de/v1/devs-list?user-uuid=00000000-0000-0000-0000-000000000000'
{
"errno": "SUCCESS",
"devices": [
{
"device-uuid": "92c647d5-7ecf-4612-b987-0786a3d815e5",
"device-name": "testtesttest"
}
]
}
Get the charging device state
GET /v1/charging-state
Returns JSON object, charging state. The returned structure can have the following fields:
{
"errno": string representation of POSIX.1 errors, 'SUCCESS' in case of success
"charging-state": {
"state": current state of the charge source.
For the detailed state description
please see the corresponding manual page:
https://support.skycharge.de/docs/system-states
"reason": the reason why charging was stopped.
For the detailed reasons description
please see the corresponding manual page:
https://support.skycharge.de/docs/system-states
"voltage-mV": output voltage of the charger in mV
"current-mA": output current of the charger in mA
"charging-time-sec": overall charging time in seconds
"state-of-charge-perc": SoC in percentage (if BMS is used)
"until-full-charge-time-sec": time in seconds until full charge
(if BMS is used)
"source-temperature-C": temperature on the charge source (MUX)
"sink-temperature-C": temperature on the sink (PLC mode only)
"energy-mWh": transferred energy in mWh
"charge-mAh": transferred charge in mAh
"tx-bytes": transmitted bytes counter (PLC mode only)
"tx-packets": transmitted packets counter (PLC mode only)
"tx-err-bytes": transmitted error bytes counter (PLC mode only)
"tx-err-packets": transmitted error packets counter (PLC mode only)
"rx-bytes": received bytes counter (PLC mode only)
"rx-packets": received packets counter (PLC mode only)
"rx-err-bytes": received error bytes counter (PLC mode only)
"rx-err-packets": received error packets counter (PLC mode only)
}
}
The charging-state request and response example:
curl 'https://api.skycharge.de/v1/charging-state?user-uuid=00000000-0000-0000-0000-000000000000&device-uuid=92c647d5-7ecf-4612-b987-0786a3d815e5'
{
"errno": "SUCCESS",
"charging-state": {
"state": "SCANNING".
"reason": "UNKNOWN",
"voltage-mV": 12005,
"current-mA": 0,
"charging-time-sec": 0,
"state-of-charge-perc": 0,
"until-full-charge-time-sec": 0,
"source-temperature-C": 25,
"sink-temperature-C": 0,
"energy-mWh": 0,
"charge-mAh": 0,
"tx-bytes": 0,
"tx-packets": 0,
"tx-err-bytes": 0,
"tx-err-packets": 0,
"rx-bytes": 0,
"rx-packets": 0,
"rx-err-bytes": 0,
"rx-err-packets": 0
}
}
Get the charging device parameters
GET /v1/charging-params
Returns JSON object, charging parameters.
curl 'https://api.skycharge.de/v1/charging-params?user-uuid=00000000-0000-0000-0000-000000000000&device-uuid=92c647d5-7ecf-4612-b987-0786a3d815e5'
{
"errno": "SUCCESS",
"params": {
"psu-type": "RSP-750-48",
"detect-mode": "CAPACITY",
"psu-fixed-voltage-mv": "20000",
"psu-fixed-current-ma": "10000",
"psu-use-fixed-v-i": "true",
"nr-bad-heartbeats": "5",
"ignore-inval-charging-settings": "false",
"ignore-low-batt-voltage": "true",
"error-indication-timeout-secs": "5",
"keep-silence": "false",
"ignore-voltage-on-output": "true",
"min-sense-current-ma": "50",
"repeat-charge-after-mins": "10",
"sense-voltage-calib-point1-mv": "10000:10000",
"sense-voltage-calib-point2-mv": "20000:20000",
"sense-current-calib-point1-ma": "0:0",
"sense-current-calib-point2-ma": "5000:5000",
"psu-voltage-calib-point1-mv": "10000:10000",
"psu-voltage-calib-point2-mv": "20000:20000",
"psu-current-calib-point1-ma": "1000:1000",
"psu-current-calib-point2-ma": "5000:5000"
}
}
Set charging parameters of the charge source board
PUT /v1/charging-params
Returns JSON object containing the error code of the operation.
In the following example two configuration parameters are updated: "psu-type" is set to "RSP-750-48" and "detect-mode" is set to "capacity":
curl -X PUT 'https://api.skycharge.de/v1/charging-params?psu-type=RSP-750-48&detect-mode=capacity&user-uuid=00000000-0000-0000-0000-000000000000&device-uuid=92c647d5-7ecf-4612-b987-0786a3d815e5'
{
"errno": "SUCCESS"
}
Get sink charging parameters
GET /v1/sink-charging-params
Returns JSON object, sink charging parameters.
curl 'https://api.skycharge.de/v1/sink-charging-params?user-uuid=00000000-0000-0000-0000-000000000000&device-uuid=92c647d5-7ecf-4612-b987-0786a3d815e5'
{
"errno": "SUCCESS",
"params": {
"capabilities": "NIL",
"batt-type": "Li-Po",
"batt-capacity-mah": "5000",
"batt-min-voltage-mv": "9000",
"batt-max-voltage-mv": "12600",
"charging-max-current-ma": "1000",
"cutoff-min-current-ma": "500",
"cutoff-timeout-ms": "1000",
"precharge-current-ma": "1000",
"precharge-delay-secs": "0",
"precharge-secs": "30",
"total-charge-secs": "3600",
"user-uart-config": "0-8-N-1",
"user-data1": "0x00000000",
"user-data2": "0x00000000",
"user-data3": "0x00000000",
"user-data4": "0x00000000"
}
}
Set charging device parameters of the sink board
PUT /v1/sink-charging-params
Returns JSON object containing the error code of the operation.
In the following example two configuration parameters are updated: "batt-capacity-mah" is set to "1000" mAh and "charging-max-current-ma" is set to "2000" mA.
curl -X PUT 'https://api.skycharge.de/v1/sink-charging-params?batt-capacity-mah=1000&charging-max-current-ma=2000&user-uuid=00000000-0000-0000-0000-000000000000&device-uuid=92c647d5-7ecf-4612-b987-0786a3d815e5'
{
"errno": "SUCCESS"
}
Get the GPS data
NOTE: Sky charging device is equipped by the GPS module upon request.
GET /v1/gps-data
Returns JSON object, GPS data. The returned structure can be described as the following:
"gps-data": {
"status": string, GPS status, possible statuses:
SKY_GPS_STATUS_NO_FIX,
SKY_GPS_STATUS_FIX
SKY_GPS_STATUS_DGPS_FIX
"satellites-used": interger, number of satellites used in the solution
"dop": { Dilution of precision factors
"xdop": numeric as string,
"ydop": numeric as string,
"pdop": numeric as string,
"hdop": numeric as string,
"vdop": numeric as string,
"tdop": numeric as string,
"gdop": numeric as string,
},
"fix": {
"mode": string, mode of fix, possible modes:
SKY_GPS_MODE_NOT_SEEN
SKY_GPS_MODE_NO_FIX
SKY_GPS_MODE_2D
SKY_GPS_MODE_3D
"time": numeric as string, time of update, unix time in sec with fractional part
"latitude": numeric as string, latitude in degrees (valid if mode is 2D or 3D)
"longitude": numeric as string, longitude in degrees (valid if mode is 2D or 3D)
"altitude": numeric as string, altitude in meters (valid if mode is 3D)
}
}
NOTE: type "numeric as string" is a numeric in quotes. Why? In the JSON RFC numeric values that cannot be represented as sequences of digits (such as Infinity and NaN) are not permitted. So in order not to confuse the JSON parser these values represented as strings. Please be careful while parsing such a numeric and expect "nan", "-nan", "inf", "-inf" strings.
For detailed description of the meaning of each field please see the GPSd manual, the GPSd daemon is used internally by the sky charging device.
curl 'https://api.skycharge.de/v1/gps-data?user-uuid=00000000-0000-0000-0000-000000000000&device-uuid=92c647d5-7ecf-4612-b987-0786a3d815e5'
{
"errno": "SUCCESS",
"gps-data": {
"status": "SKY_GPS_STATUS_DGPS_FIX",
"satellites-used": 42,
"dop": {
"xdop": "0.000000",
"ydop": "0.000000",
"pdop": "12.210000",
"hdop": "21.120000",
"vdop": "23.320000",
"tdop": "34.430000",
"gdop": "54.430000"
},
"fix": {
"mode": "SKY_GPS_MODE_3D",
"time": "1616164288.543180",
"latitude": "12345.543210",
"longitude": "54321.123450",
"altitude": "nan"
}
}
}
Resume scan
Skycharge charging pad works in automatic mode and charge starts immediately after drone lands on the charging platform. But scan can be stopped by the corresponding 'scan-stop' request (see description below). When scan is stopped it needs to be resumed again by the 'scan-resume' request.
GET /v1/scan-resume
Returns JSON object with only one 'errno' field indicating the status of the operation.
curl 'https://api.skycharge.de/v1/scan-resume?user-uuid=00000000-0000-0000-0000-000000000000&device-uuid=92c647d5-7ecf-4612-b987-0786a3d815e5'
{
"errno": "SUCCESS"
}
Stop scan
Skycharge charging pad works in automatic mode and charge starts immediately after drone lands on the charging platform. But scan can be stopped by the corresponding 'scan-stop' request. When scan is stopped it needs to be resumed again by the corresponding 'scan-resume' request (see description above).
GET /v1/scan-stop
Returns JSON object with only one 'errno' field indicating the status of the operation.
curl 'https://api.skycharge.de/v1/scan-stop?user-uuid=00000000-0000-0000-0000-000000000000&device-uuid=92c647d5-7ecf-4612-b987-0786a3d815e5'
{
"errno": "SUCCESS"
}
Drone Port
Skycharge charging pad can be equipped by the drone port, the cover, which opens when drone lands and closes when charging starts. In order to control the drone port 'droneport-open', 'droneport-close' and 'droneport-state' API requests are implemented.
Open Drone Port
GET /v1/droneport-open
Returns JSON object with only one 'errno' field indicating the status of the operation. If the charging pad device is not equipped with the drone port 'errno' field contains 'EOPNOTSUPP' error status.
curl 'https://api.skycharge.de/v1/droneport-open?user-uuid=00000000-0000-0000-0000-000000000000&device-uuid=92c647d5-7ecf-4612-b987-0786a3d815e5'
{
"errno": "EOPNOTSUPP"
}
Close Drone Port
GET /v1/droneport-close
Returns JSON object with only one 'errno' field indicating the status of the operation, which is set to 'SUCCESS' indicating success or the error name, which is specified by POSIX.1 standard. If the charging pad device is not equipped with the drone port 'errno' field contains 'EOPNOTSUPP' error status.
curl 'https://api.skycharge.de/v1/droneport-close?user-uuid=00000000-0000-0000-0000-000000000000&device-uuid=92c647d5-7ecf-4612-b987-0786a3d815e5'
{
"errno": "EOPNOTSUPP"
}
State of the Drone Port
GET /v1/droneport-state
Returns JSON object which describes state of the drone port. Drone port can be ready, opened, closed, in progress (opening or closing) or landing error can happen.
curl 'https://api.skycharge.de/v1/droneport-state?user-uuid=00000000-0000-0000-0000-000000000000&device-uuid=92c647d5-7ecf-4612-b987-0786a3d815e5'
{
"errno": "SUCCESS",
"droneport-state": {
"is-ready": true,
"is-opened": false,
"is-closed": true,
"in-progress": false,
"landing-err": false
}
}
Updated over 2 years ago