HELLA Aglaia APS-90 User manual

HELLA Aglaia People Sensing Technologies
people-sensing.com
HAGL-120-00082
Version 1.18.0
Reference manual REST
APS-90, APS-180 and
APS-90-Outdoor-PoE
Advanced People
Sensor
Original document

2 / 48
The reproduction, distribution and utilization of this document as well as the communication of its contents to others without
express authorization is prohibited. Offenders will be held liable for the payment of damages.
All rights reserved in the event of the grant of patent, utility model or design.
14.04.2020
Version 1.18.0
HELLA Aglaia Mobile Vision GmbH, Berlin
HELLA Aglaia Mobile Vision GmbH
Ullsteinstraße 140
12109 Berlin
Germany
phone:: [phone]
fax:: [phone]
mail:: [email protected]
www.people-sensing.com
© 2020

3 / 48
The reproduction, distribution and utilization of this document as well as the communication of its contents to others without
express authorization is prohibited. Offenders will be held liable for the payment of damages.
All rights reserved in the event of the grant of patent, utility model or design.
14.04.2020
Version 1.18.0
Supplemental directives
REST
Supplemental directives
Copyright information
© 2020 HELLA Aglaia Mobile Vision GmbH. All rights reserved. This manual is protected by copyright. It may not be
reproduced in whole or in part or transmitted in any form, electronic or mechanical, including photocopying and recor-
ding, without the prior written permission of HELLA Aglaia Mobile Vision GmbH. Violations are subject to the criminal
provisions of copyright law.
HELLA Aglaia Mobile Vision GmbH reserves the right to revise or replace this manual at any time and without prior notice.
Make sure that you have the appropriate version of this manual for the installed firmware version of the device. If you
have any questions, please contact HELLA Aglaia Mobile Vision GmbH.
HELLA Aglaia Mobile Vision GmbH does not guarantee the completeness, accuracy, or timeliness of the laws, guidelines,
or regulations referred to or quoted, whether directly or indirectly, in this manual. It is the responsibility of the user to
become familiar with the current laws, guidelines, and regulations that apply to their work.
HELLA Aglaia Mobile Vision GmbH reserves the right to modify the described devices (including the respective soware)
without prior notice, irrespective of the content of this manual. Unless expressly agreed upon in writing, HELLA Aglaia
Mobile Vision GmbH is not obligated to notify the owner or user of the devices described in this manual (including the
respective soware) of any revisions, updates, or modifications without further request.
With regard to the APS-90, APS-180 and APS-90-Outdoor-PoE, HELLA Aglaia Mobile Vision GmbH‘s liability is limited to
the terms and conditions of purchase. The information provided in this manual is not a warranty or guarantee of any kind.
Stipulations concerning the devices described in this manual are only deemed warranties if they are expressly referred to
as such in writing and contain a description of the warranty’s scope and the product covered by the warranty.
The product and company names mentioned in this manual may be protected trademarks of other manufacturers.
The information contained in this manual has been prepared by HELLA Aglaia Mobile Vision GmbH with great care using
sources available to HELLA Aglaia Mobile Vision GmbH. However, HELLA Aglaia Mobile Vision GmbH shall not be respon-
sible for any errors, incorrect or incorrectly compiled data, and any consequences resulting therefrom, irrespective of the
legal basis, provided that HELLA Aglaia Mobile Vision GmbH‘s conduct amounts to no more than ordinary negligence.
The aforementioned exclusion of liability does not apply to damages resulting from injury to life, body, or health or to
damages that are caused intentionally, by gross negligence on the part of HELLA Aglaia Mobile Vision GmbH, or by the
violation of due diligence requirements in connection with the development, manufacture, and distribution of the products
described in this manual.
This does not affect the liability regardless of negligence or fault pursuant to legal regulations such as the Product Liabi-
lity Act.

4 / 48
The reproduction, distribution and utilization of this document as well as the communication of its contents to others without
express authorization is prohibited. Offenders will be held liable for the payment of damages.
All rights reserved in the event of the grant of patent, utility model or design.
14.04.2020
Version 1.18.0
Supplemental directives
REST
Document history
Version Modification
1.18.0 Chapter 5
■New classes "Group" and "Cart" for counting with the ObjectClassification-License.
■New class "Cart" for zone monitoring with the ObjectClassification-License.
■Wireless tracking for WiFi and Bluetooth with the WirelessServices-License and the USB
WiFi Bluetooth Adapter.
1.16.0 New layout
1.15.1 Chapter 3
■Removed hint for token update by GET method (still not included today).
Chapter 5
■New subsection Zone object list - all zones
■New subsection Zone object list - single zones
1.14.0 Chapter 5
■New subsection Zone statistics - all zones
■New subsection Zone statistics - single zones
■New subsection System information moved from Chapter 6
Chapter 6 changed to Examples
■New subsection Integrated python script moved from subsection 2.5
■New subsection Tool Insomnia
1.12.0 No change of REST protocol
1.10.1 Correction of testClient.py help
1.10.0 First version of document

5 / 48
The reproduction, distribution and utilization of this document as well as the communication of its contents to others without
express authorization is prohibited. Offenders will be held liable for the payment of damages.
All rights reserved in the event of the grant of patent, utility model or design.
14.04.2020
Version 1.18.0
Table of contents
REST
Table of contents
1 Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7
2 General information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8
2.1 User and access rights . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8
2.2 Data security . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8
2.3 Versioning . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8
2.4 Base path . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9
2.5 Licenses . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9
3 Authorisation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10
3.1 Token information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10
3.2 Auth . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10
3.3 Example for initial token request . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11
3.4 Using tokens . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11
4 Update . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13
5 Sensor data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15
5.1 Sensor Data - all available data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15
5.2 Count Results - all counting lines . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18
5.3 Count Results - single counting line . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20
5.4 Fill level - all zones . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23
5.5 Fill level - single zone . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25
5.6 Zone statistics - all zones . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27
5.7 Zone statistics - single zone . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29
5.8 Zone object list - all zones . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31
5.9 Zone object list - single zone . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33
5.10 Wireless information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35
5.11 System information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36
6 Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37
6.1 Integrated python script . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37
6.2 Tool Insomnia . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38

6 / 48
The reproduction, distribution and utilization of this document as well as the communication of its contents to others without
express authorization is prohibited. Offenders will be held liable for the payment of damages.
All rights reserved in the event of the grant of patent, utility model or design.
14.04.2020
Version 1.18.0
Table of contents
REST
7 Appendix . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44
7.1 HTTP error codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44
8 Glossary and abbreviations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45
9 Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47

7 / 48
The reproduction, distribution and utilization of this document as well as the communication of its contents to others without
express authorization is prohibited. Offenders will be held liable for the payment of damages.
All rights reserved in the event of the grant of patent, utility model or design.
14.04.2020
Version 1.18.0
Introduction
REST
1 Introduction
The APS is a high precision people sensing device which generates people counts, occupancy information or wifi logging.
Usually the generated data is sent to a central server in a remote location. This server will then perform data analytics and
maintenance evaluations. As it is usually not possible to pull the data from a device in an in-store network, we established a
push interface using SOAP-XML.
Lately, we've received requests from customers, that already have servers or gateways in the in-store network and would
prefer a pull interface. In order to fulfil this requirement, we've started to implement a REST API. This document describes
the initial implementation of the REST API.
This interface will be available with firmware version 1.10. In the first implementation the interface will only give access to
basic information of the device. It will be extended in the following firmware versions.
This specification is preliminary and may change during implementation. It shall give an overview of the basic concept and
the available data.
Support
Service requests can be sent to the following e-mail address:
[email protected]
The general contact information is shown on page 2.

8 / 48
The reproduction, distribution and utilization of this document as well as the communication of its contents to others without
express authorization is prohibited. Offenders will be held liable for the payment of damages.
All rights reserved in the event of the grant of patent, utility model or design.
14.04.2020
Version 1.18.0
General information
REST
2 General information
2.1 User and access rights
The REST API will have the same users as the web interface. Currently only two predefined users exist. The user manage-
ment will be reworked in the upcoming firmware versions allowing individual users with distinct access rights.
user-role-view
Access rights:
■Request data (all GET operations)
■Reset count results
user-role-edit
Access rights:
■Same as user-role-view
■Perform firmware update
2.2 Data security
The REST API will only be available for communication via https.
Default a self-signed certificate will be used. For details, see "APS-Customizing.pdf" at chapter "5.5. SSL certificate".
2.3 Versioning
The version is part of the URL using apiv1. A new version will only be created, if changes are not backward compatible.
Adding new requests to the API will not lead to a new version.

9 / 48
The reproduction, distribution and utilization of this document as well as the communication of its contents to others without
express authorization is prohibited. Offenders will be held liable for the payment of damages.
All rights reserved in the event of the grant of patent, utility model or design.
14.04.2020
Version 1.18.0
General information
REST
2.4 Base path
The base path URL of the REST API is:
https://[deviceIP]:[restPort]/apiv1/
Example
Path to request the bearer token for authentification
https://192.168.100.10:8091/auth
Example
This example is only the path – the call request itself needs bearer token returned from the authentification
https://192.168.100.10:8091/apiv1/sensorData
2.5 Licenses
There are some optional licenses for the APS, that have effects in the availability of data.
License Effect Comments
Object Classification usage of data With this license data is seperated in the classes adult,
child, cart and group.
Without this license the data at adult contains the sum of
adult and child and child is always 0.
Zone Monitoring availability of data path Only with this license the data path fillLevel, zoneS-
tatistics and zoneObjectList are available with
data.
Wireless Services availability of data path Only with this license the data path wirelessLogging
is available with data.

10 / 48
The reproduction, distribution and utilization of this document as well as the communication of its contents to others without
express authorization is prohibited. Offenders will be held liable for the payment of damages.
All rights reserved in the event of the grant of patent, utility model or design.
14.04.2020
Version 1.18.0
Authorisation
REST
3 Authorisation
Authorisation is performed via JWT tokens. Username and password are required to receive the initial token. A token is
valid for 1 hour.
3.1 Token information
Part Content Comment
HEADER "typ": "JWT",
"alg": "HS256"
Token type → JsonWebToken
Signature type → HMAC-SHA256
PAYLOAD "iat": 1492765233,
"exp": 1492768833,
"nbf": 1492765233,
"identity": 2
Time of creation
Valid until
Valid from
User (2→ user-role-edit)
VERIFY SIGNATURE HMACSHA256( base64UrlEncod
e(header) + "." +
base64UrlEncode(payload),
secretKey )
3.2 Auth
Name auth
URL https://[deviceIP]:[restPort]/auth
Availability APS-RS firmware 1.10
Method Data Result HTTP Status Comments
GET — not supported 405 - Method Not Allowed
POST User / Passwort Token in JWT format 200 - OK on success
400 - Bad Request on internal
error → additional information in
JSON error payload
PUT — not supported 405 - Method Not Allowed

11 / 48
The reproduction, distribution and utilization of this document as well as the communication of its contents to others without
express authorization is prohibited. Offenders will be held liable for the payment of damages.
All rights reserved in the event of the grant of patent, utility model or design.
14.04.2020
Version 1.18.0
Authorisation
REST
3.3 Example for initial token request
Request
POST /auth HTTP/1.1
Host: 192.168.100.10
Connection: keep-alive
Content-Length: 48
Origin: http://192.168.100.10
Content-Type: application/json;charset=UTF-8
Referer: http://192.168.100.10/
{
"username":"user-role-edit",
"password":"admin"
}
Response
HTTP/1.1 200 OK
Content-Length: 192
Content-Type: application/json
Server: TornadoServer/4.4.3
{
"access_token":
"eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJleHAiOjE0OTI3ODIyODgsIm5iZiI6MTQ5Mjc
3ODY4OCwiaWRlbnRpdHkiOjIsImlhdCI6MTQ5Mjc3ODY4OH0.aYEc3YNgkGDYEIXXVb5BPKyDTWrR
zx100zxOuqOngco"
}
3.4 Using tokens
All requests except for auth/POST require the keyword Bearer and the token in the Authorization field of the header.

12 / 48
The reproduction, distribution and utilization of this document as well as the communication of its contents to others without
express authorization is prohibited. Offenders will be held liable for the payment of damages.
All rights reserved in the event of the grant of patent, utility model or design.
14.04.2020
Version 1.18.0
Authorisation
REST
Example for a request using a token
GET /apiv1/sensorData/counts HTTP/1.1
Host: 192.168.100.10
Connection: keep-alive
Authorization: Bearer
eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJleHAiOjE0OTI3ODIyODgsIm5iZiI6MTQ5Mjc3ODY
4OCwiaWRlbnRpdHkiOjIsImlhdCI6MTQ5Mjc3ODY4OH0.aYEc3YNgkGDYEIXXVb5BPKyDTWrRzx100zx
OuqOngco
Referer: http://192.168.100.10/

13 / 48
The reproduction, distribution and utilization of this document as well as the communication of its contents to others without
express authorization is prohibited. Offenders will be held liable for the payment of damages.
All rights reserved in the event of the grant of patent, utility model or design.
14.04.2020
Version 1.18.0
Update
REST
4 Update
To perform a firmware update post the URL to the update .tar file to the device.
Request
Name update
URL https://[deviceIP]:[restPort]/apiv1/update
Availability APS-RS firmware 1.10
Method Data Result HTTP Status Comments
GET — not supported 403 - Forbidden
POST JSON Container
with update
information
NONE 200 - OK on success
400 - Bad Request on internal
error → additional information in
JSON error payload
401 - Unauthorized – The request
requires an user authentication
PUT — not supported 405 - Method Not Allowed
DELETE — not supported 405 - Method Not Allowed
Contents of an update request
■Update_type
●Enumeration specifying the type of update
●Currently only "UPDATE_FIRMWARE" is supported
■Packet_url
●String, maxLen: 255 characters
●URL to the update file
■Validity
●Unsigned integer
●Min: 1h, max: 168 h (one week), default: 48h
●Specifies the time period, in which the device shall perform retries in case an update fails

14 / 48
The reproduction, distribution and utilization of this document as well as the communication of its contents to others without
express authorization is prohibited. Offenders will be held liable for the payment of damages.
All rights reserved in the event of the grant of patent, utility model or design.
14.04.2020
Version 1.18.0
Update
REST
Example
"requestData":
{ "update_type": "UPDATE_FIRMWARE",
"packet_url": "http://firmwareUpdateSite.org/firmwareUpdate.tar",
"validity": 1
}

15 / 48
The reproduction, distribution and utilization of this document as well as the communication of its contents to others without
express authorization is prohibited. Offenders will be held liable for the payment of damages.
All rights reserved in the event of the grant of patent, utility model or design.
14.04.2020
Version 1.18.0
Sensor data
REST
5 Sensor data
5.1 Sensor Data - all available data
On this request the sensor returns all available data. Zone monitoring data and wireless logging data will only be trans-
ferred if the required license is installed on the device.
Requests
Name sensorData
URL https://[deviceIP]:[restPort]/apiv1/sensorData
Availability APS-RS firmware 1.10
Method Data Result HTTP Status Comments
GET NONE JSON container with
sensor data
200 - OK on success
400 - Bad Request on internal
error → additional information in
JSON error payload
401 - Unauthorized – The request
requires an user authentication
Returns all avai-
lable sensor data
POST — not supported 405 - Method Not Allowed
PUT — not supported 405 - Method Not Allowed
DELETE — not supported 405 - Method Not Allowed

16 / 48
The reproduction, distribution and utilization of this document as well as the communication of its contents to others without
express authorization is prohibited. Offenders will be held liable for the payment of damages.
All rights reserved in the event of the grant of patent, utility model or design.
14.04.2020
Version 1.18.0
Sensor data
REST
Response
"sensorData":
{ "counts":
[ { "name": "MyLine0",
"data":
[ { "class": "Adult",
"in": 42,
"out": 23
},
{ "class": "Child",
"in": 7,
"out": 5
}
{ "class": "Group",
"in": 15,
"out": 10
}
{ "class": "Cart",
"in": 7,
"out": 5
}
]
},
{ "name": "MyLine1",
"data":
[ { "class": "Adult",
"in": 19,
"out": 2
},
{ "class": "Child",
"in": 0,
"out": 1
}
]
}
]
},
{ "fillLevel":
[ { "name": "MyZone0",
"data":
[ { "class": "Adult",
"level": 2,
"avgDwell": 6,
"maxDwell": 8
},
{ "class": "Child",
"level": 1,
"avgDwell": 5,
"maxDwell": 5

17 / 48
The reproduction, distribution and utilization of this document as well as the communication of its contents to others without
express authorization is prohibited. Offenders will be held liable for the payment of damages.
All rights reserved in the event of the grant of patent, utility model or design.
14.04.2020
Version 1.18.0
Sensor data
REST
}
{ "class": "Cart",
"level": 2,
"avgDwell": 6,
"maxDwell" :8
}
]
},
{ "name": "MyZone1",
"data":
[ { "class": "Adult",
"level": 3,
"avgDwell": 7,
"maxDwell": 11
},
{ "class": "Child",
"level": 0,
"avgDwell": 0,
"maxDwell": 0
}
]
}
]
},
{"zoneStatistics":
[ { "name":"MyZone0",
"data":
[ { "class": "Adult",
"count": 0,
"maxDwell": 0,
"max_fill_level": 0,
"meanDwell": 0
},
{ "class": "Child",
"count": 0,
"maxDwell": 0,
"max_fill_level": 0,
"meanDwell": 0
},
{ "class": "Cart",
"count": 0,
"maxDwell": 0,
"max_fill_level": 0,
"meanDwell": 0
}
],
},
{ "name":"MyZone1"
"data":
[ { "class": "Adult",
"count": 0,

18 / 48
The reproduction, distribution and utilization of this document as well as the communication of its contents to others without
express authorization is prohibited. Offenders will be held liable for the payment of damages.
All rights reserved in the event of the grant of patent, utility model or design.
14.04.2020
Version 1.18.0
Sensor data
REST
"maxDwell": 0,
"max_fill_level": 0,
"meanDwell": 0
},
{ "class": "Child",
"count": 0,
"maxDwell": 0,
"max_fill_level": 0,
"meanDwell": 0
}
],
}
]
},
{"wirelessLogging":
{ "timeStamp": "2020-04-01T12:04:38.025271+01:00",
"stations":
[ { "MAC": "D8:E0:E1:33:C7:EF",
"Type": "BLUETOOTH",
"Signal": -76,
"Time": "2020-04-01T11:30:06.075467+00:00"
},
{ "MAC": "FF:FF:C2:07:BA:66",
"Type": "BLUETOOTH",
"Signal": -58,
"Time": "2020-04-01T11:30:06.929436+00:00"
},
{ "MAC": "BC:8C:CD:98:E4:6A",
"Type": "WIFI"
"Signal": -75
},
{ "MAC": "F0:27:65:62:35:64",
"Type": "WIFI"
"Signal": -57
}
]
}
}
5.2 Count Results - all counting lines
Request or reset the counting data of all counting lines.

19 / 48
The reproduction, distribution and utilization of this document as well as the communication of its contents to others without
express authorization is prohibited. Offenders will be held liable for the payment of damages.
All rights reserved in the event of the grant of patent, utility model or design.
14.04.2020
Version 1.18.0
Sensor data
REST
Request
Name counts
URL https://[deviceIP]:[restPort]/apiv1/sensorData/counts
Availability APS-RS firmware 1.10
Method Data Result HTTP Status Comments
GET NONE JSON container with
count results
200 - OK on success
400 - Bad Request on internal
error → additional information in
JSON error payload
401 - Unauthorized – The request
requires an user authentication
Returns accumu-
lated count
results of all
counting lines
POST — not supported 405 - Method Not Allowed
PUT NONE NONE 200 - OK on success
400 - Bad Request on internal
error → additional information in
JSON error payload
401 - Unauthorized – The request
requires an user authentication
All count results
will be set to zero
(but only for the
Rest interface)

20 / 48
The reproduction, distribution and utilization of this document as well as the communication of its contents to others without
express authorization is prohibited. Offenders will be held liable for the payment of damages.
All rights reserved in the event of the grant of patent, utility model or design.
14.04.2020
Version 1.18.0
Sensor data
REST
Response
"counts":
[ { "name": "MyLine0",
" data":
[ { "class": "Adult",
"in": 42,
"out": 23
},
{ "class": "Child",
"in": 7,
"out": 5
},
{ "class": "Group",
"in": 15,
"out": 10
},
{ "class": "Cart",
"in": 4,
"out": 3
}
]
},
{ "name": "MyLine1",
"data":
[ { "class": "Adult",
"in": 19,
"out": 2
},
{ "class": "Child",
"in": 0,
"out": 1
}
]
}
]
5.3 Count Results - single counting line
Request or reset the counting data of a single counting line.