Aps Push Service Via Soap v1.8 en

Reference manual
Push Service via SOAP

Automatic People Sensor APS
HAGL-120-00076, 2017-03, SW 1.8
HAGL-120-00076, 2017-03, SW 1.8

Hella KGaA Hueck & Co.
Rixbecker Strasse 75
59552 Lippstadt
Germany
Hella Aglaia Mobile Vision GmbH

Treskowstrasse 14
13089 Berlin
Germany
Telephone: +49 30 200 04 29 140
Fax: +49 30 200 04 29 149
Email: peoplecounter@hella.com
Internet: www.hella.de/peoplecounter
© 2017 Hella KGaA Hueck & Co., Lippstadt (hereinafter called 'Hella')
This document has to be treated confidentially. Its contents are not to be passed on, duplicated, exploited or
23.03.2017 disclosed without our express permission. All rights reserved, especially the right to apply for protective rights.
2
Table of contents
Table of contents
1 Introduction.......................................................................................................................................... 5
2 Basic Concept...................................................................................................................................... 6
3 Task Messages.................................................................................................................................... 7
3.1 Introduction.................................................................................................................................. 7
3.2 Startup and standard tasks......................................................................................................... 7
3.3 Adding, deleting, and changing tasks.......................................................................................... 8
3.4 Buffering APS messages in case of network interruption........................................................... 8
3.5 Persistent tasks beyond reboots............................................................................................... 10
3.6 Request alive notifications......................................................................................................... 10
3.7 Requesting feature infos........................................................................................................... 11
3.8 Requesting all counting gates values........................................................................................ 11
3.9 Requesting first counting gate values....................................................................................... 12
3.10 Requesting all monitored zone values...................................................................................... 13
3.11 Requesting a current object list................................................................................................. 13
3.12 Requesting a historic object list................................................................................................. 14
3.13 Requesting wireless tracking..................................................................................................... 14
3.14 Requesting image snapshots.................................................................................................... 15
3.15 Set date and time...................................................................................................................... 15
3.16 Requesting a firmware update.................................................................................................. 16
3.17 Requesting deletion of all Task................................................................................................. 16
3.18 Requesting deletion of all notifications...................................................................................... 17
4 Task Messages and trigger.............................................................................................................. 18
4.1 Time-based triggers.................................................................................................................. 18
4.1.1 Date element.............................................................................................................. 18
4.1.2 Start element.............................................................................................................. 19
4.1.3 Cycle element............................................................................................................ 19
4.1.4 Random offset element.............................................................................................. 19
4.2 Event-based trigger................................................................................................................... 20
4.2.1 Feature changed event.............................................................................................. 20
4.2.2 Count channels event................................................................................................ 21
4.2.3 Count event................................................................................................................ 22
4.2.4 Zone channels event.................................................................................................. 22
4.2.5 Current object list event............................................................................................. 23
4.2.6 Wireless tracking event.............................................................................................. 23
4.2.7 Optical self diagnosis event....................................................................................... 23
4.2.8 One-time event........................................................................................................... 24
4.2.9 Startup event.............................................................................................................. 24
5 Server answer messages.................................................................................................................. 25
6 APS notification messages.............................................................................................................. 27
3
Table of contents
6.1 Startup....................................................................................................................................... 28
6.2 Alive........................................................................................................................................... 29
6.3 Features info............................................................................................................................. 29
6.4 Count channels......................................................................................................................... 31
6.5 Count......................................................................................................................................... 31
6.6 Zone channels........................................................................................................................... 32
6.7 Current object list...................................................................................................................... 34
6.8 Historic object list...................................................................................................................... 36
6.9 Wireless tracking....................................................................................................................... 38
6.10 Image snapshots....................................................................................................................... 39
6.11 APS error message................................................................................................................... 40
7 Examples............................................................................................................................................ 42
7.1 Startup with invocation of tasks................................................................................................. 42
7.2 Persistent tasks stored inside the APS..................................................................................... 48
8 Tools................................................................................................................................................... 49
8.1 WSDL........................................................................................................................................ 49
8.2 APS........................................................................................................................................... 49
9 Appendix............................................................................................................................................ 51
9.1 OSD status codes..................................................................................................................... 51
9.2 APS error codes........................................................................................................................ 51
9.3 Server error codes..................................................................................................................... 52
9.4 Syslog error codes.................................................................................................................... 52
9.4.1 SOAP error codes...................................................................................................... 53
9.4.2 http error codes.......................................................................................................... 55
10 Support............................................................................................................................................... 57
11 Glossary and abbreviations............................................................................................................. 58
4
Introduction
1 Introduction
The APS can be configured so that data do not have to be
requested but be sent automatically from the APS to a server. This
so-called Push Service is based on the XML-based Simple Object
Access Protocol (SOAP). When the connection is established, the
server informs the APS of the required data and transmission
times. The APS then sends them accordingly. This allows commu-
nication with APS behind routers and firewalls.
This document is intended as an introduction and reference
manual for customers using the Push Service via SOAP on the
Hella Automatic People Sensor (APS). This include all variants of
APS-90, APS-180 and APS-90-Outdoor for retail, building and sta-
tionary applications.
Our sensors for bus and train applications use another firmware
with other features and partly different Push Service protocol - that
is not included in this document.
For developers there are additional examples of the backend
implementation. These examples are usable as try out or as a ref-
erence implementation of the communication. Hella provide only
the APS sensors with protocols - no backend or database systems.
References Link/Name Description

1 APS Push Service via SOAP Hella Push Service
Examples (HAGL-120-00058) example for .NET
2 Installation and configuration Instruction manual for con-
manual Automatic People figuring an APS using the
Sensor APS (HAGL-120-00077) HMI web interface
7 http://www.w3.org/TR/soap/ W3C: SOAP Specifica-
tions
8 http://www.cs.fsu.edu/~engelen/ gSOAP Toolkit
soap.html
Do not use the files of the example

"BaSS_SOAPd.wsdl" and "BaSS_SOAPd.xsd" as ref-
erence - instead of this document. These files include
also not implemented parts to be compatible between
sensor and server in long term.
Support
Service requests regarding the Automatic People
Sensor and Push Services via SOAP can be sent to
the following e-mail address:
– people.counter.support@hella.com
5
Basic Concept
2 Basic Concept
APS server communication The basic concept of the APS Push Service is to use a manage-
able server in the network. All the APSs can send data to that
known server using customizable tasks. The server response to
the connection established by the APSs can contain newly invoked
tasks that are addressed to the APS as task messages. This
method is commonly referred to as "inversion of control" similar to
the "don't call us, we'll call you" concept.
pushed data
by previous
requested
task
SOAP
acknowledge
for
pushed data
invocation of
new tasks
n * APS 1 * Server
► communication establishing ►
Intranet Internet
Fig. 1: APS server communication via SOAP
Notifications The APS sends notification messages with possible pushed data.
The server returns an Answer Message that contains a simple
acknowledgment of the APS notification message and an optional
list of new task messages.
Tasks Customizable tasks can be triggered once, at regular intervals or

on event. Some tasks are intended for maintenance purposes
without contacting the server and others are intended for transfer-
ring the customizable data like counting values to the server.
Transport protocol The transport protocol is TCP/IP. The protocol is encapsulated in

http or encrypted with https. The session layer and presentations
layer are managed by SOAP. This document describes the
behavior of an APS at the SOAP interface (WSDL). The Hella APS
product portfolio does not include the SOAP server.
6
Task Messages
Startup and standard tasks
3 Task Messages
3.1 Introduction
The server can acknowledge notification messages from the APS
and optionally invoke new tasks by means of task messages,
which are described in this chapter. There are two types of tasks:
n Immediate tasks, e.g. to force setting of time.
n Data requests including triggers, e.g. to force multiple postings
of counting data.
Data requests do not need to be repeatedly requested by the
server. These tasks can use a customizable trigger for multiple
postings ( Ä Chapter 4 ‘Task Messages and trigger’ on page 18).
Both task messages are described in a <task_message> con-
tainer including the type of task, task ID, and other required values.
The following task causes the APS to send an Alive Message to
the server every 5 minutes:
Example
<task_subscribe_alive
task_type="TASK_ALIVE"
serverTask_ID="42"
activity_state="true">
<trigger>
<time_trigger>
<date kind="DATE_DONT_CARE"/>
<start hours="0" minutes="0"
seconds="0"/>

<cycle>PT5M</cycle>
<random_offset>PT0S</random_offset>
</time_trigger>
</trigger>
</task_subscribe_alive>
3.2 Startup and standard tasks

If Push Services enabled, every reboot triggers a startup notifica-
tion message to the server, by default. The server can respond to
this message and invoke new tasks for sending data. The APS
retries to send this startup notification until the connection to the
server is established and the server response with a
SOAP_SERVER_OK acknowledge.
In addition to the startup notification, the APS sends an alive notifi-
cation as an heart beat cyclically every 3 hours plus a random
offset time of 0 to up to 5 minutes for maintenance purposes.
All other tasks previously to a reboot sent to the APS are not per-
sistent and deleted.
7
Task Messages
Buffering APS messages in case of network interruption
3.3 Adding, deleting, and changing tasks

Availability: APS firmware 1.0
Adding a new task To add a new task simply send a task message with a new
serverTask_ID to the APS. The APS supports 10 tasks - in addi-
tion to the two standard tasks for the startup message and the
cyclic Alive Message.
Deleting tasks To delete a single task send the task with the same
serverTask_ID to the APS, but set the activity state to false:
activity_state="false". (Sending the trigger is optional.)
Example
serverTask_ID="42"
activity_state="false">
Deleting all tasks Beside deleting tasks step by step, there is a special task to delete
all current tasks (see below TASK_DELETE_ALL_TASKS,
Ä Chapter 3.17 ‘Requesting deletion of all Task’ on page 16).
Use it in combination of new tasks in your task list.
Changing tasks To change a task first delete it and add a new one with the
changed settings.
Please avoid the same serverTask_ID in the case of sending
deletion and renew in the same task list of a server answer. If a
message is pending in the current queue, the renew with the same
id could be blocked.
3.4 Buffering APS messages in case of network interruption

Availability: APS firmware 1.0 (buf- For some tasks, optional buffering is available in case of network
fering beyond reboots starting from interruption. The interruption is detected by the APS, if no server
version 1.2.0) answer message is returned after sending an APS notification
message. Optional buffering is available for the following tasks:
n Request all counting gates values ( Ä Chapter 3.8 ‘Requesting
all counting gates values’ on page 11)
n Request first counting gate values ( Ä Chapter 3.9 ‘Requesting
first counting gate values’ on page 12)
By default, buffering is disabled for transmission errors. To enable
buffering set the store_on_transmission_error parameter to
true (see example below).
8
Task Messages
Buffering APS messages in case of network interruption
Example
<task_subscribe_count_channels
task_type="TASK_COUNT_CHANNELS"
serverTask_ID="123"
activity_state="true"
store_on_transmission_error="true">
<trigger>
<time_trigger>
<date kind="DATE_DONT_CARE" />
seconds="0" />

<cycle>PT1M</cycle>
</time_trigger>
</trigger>
</task_subscribe_count_channels>
The maximum time for bridging a network interruption depends on

the message volume to be sent and if an APS version without or
with addional memory is used. Using more buffered tasks or
shorter time frames, or both, will reduce the bridging time.
The APS-180 could store 4095 messages. The APS-180-8GB
could store 65535 messages.
4000 single buffered count messages could bridge a time of 2
weeks of network interruption with messages scheduled every 5
minutes. Using a longer interval, e.g. 15 minutes, extends the
bridging time to 6 weeks.
Power fail
Note that the message queues will only be saved in
the persistent memory, if the APS detects network
problems. In the case of a power fail with a preceding
network interruption of some seconds or minutes, it is
possible that the network connection did not time out
yet, and some messages may get lost.
Buffer overflow
If the buffer is completely filled, the APS deletes the
oldest message to free memory capacity for a new
message. The push service does not provide a fall-
back option for this worst case scenario.
Buffer deletion
To delete the content of the buffer in case of unneces-
sary data use:
– TASK_DELETE_ALL_NOTIFICATIONS (see
below)
– the Factory Reset
9
Task Messages
Request alive notifications
3.5 Persistent tasks beyond reboots

Availability: APS firmware 1.2 Standard behaviour is, that after reboot the APS dropped all it
tasks, send a startup notification message to the server, that tell
the APS what to do with a task list. If there is a network shortage at
startup, this cause lost of possible recording count data in buffers.
To invoke tasks persistent beyond reboots there is an optional
attributestore_task="true".
After reboot they are alive and could send or buffer data, without
interaction to the server.
These task could be deleted as all other tasks.
Example
serverTask_ID="123"
store_task="true"
<trigger>
<time_trigger>
seconds="0" />
<cycle>PT1M</cycle>
</time_trigger>
</trigger>
Preparing standard tasks

The persistent tasks are stored as single xml files
inside the sensor.
To prepare a sensor to use allways standard tasks at
startup without interaction with a server it is possible to
change these files. Prepare and test them before and
you will find them as single xml files
task_[index].xml inside the sensor at
– APS without addional memory as APS-180:
/CustomData/HAGL/SOAP/tasks/
– APS with addional memory as APS-180-8GB:
/media/sdcard/HAGL/SOAP/tasks/
/CustomData/HAGL/SOAP/tasks
3.6 Request alive notifications

Availability: APS firmware 1.0 This task forces the APS to post something like an heart beat. It
sends repetitively alive notification messages to the server for
maintenance and to invoke new tasks at the APS as a result of the
server response to the Alive Message.
10
Task Messages
Requesting all counting gates values
Example
serverTask_ID="1" activity_state="true">
<trigger>
<time_trigger>
<date kind="DATE_DONT_CARE"></date>
seconds="0"/>

<cycle>PT5M10S</cycle>
</time_trigger>
</trigger>
3.7 Requesting feature infos

Availability: APS firmware 1.0 This task forces the APS to post informations about used features
as e.g. the names of active counting gates or monitored zones.
This could be useful to synchonize database and incoming data.
Example
<task_subscribe_features_info
task_type="TASK_FEATURES_INFO"
serverTask_ID="2"
<trigger>
<event_trigger>

<feature_changed_event />
</event_trigger>
</trigger>
</task_subscribe_features_info>
3.8 Requesting all counting gates values

Availability: APS firmware 1.0 This task forces the APS to post data of all counting gates to the
server.
If no buffering in case of network interruption is requested and an
error occurs when sending a Count Message to the server, the
counts are summed up and sent in the next Count Message. Ena-
bling buffering for transmission errors saves every single Count
Message result with time stamp in case of network interruption. In
case of a network interruption or a new buffering message, the
APS attempts to send the oldest message every 60 seconds. If the
message was transferred successfully, all buffered messages will
be sent to the server.
11
Task Messages
Requesting first counting gate values
Example
serverTask_ID="3"
<trigger>
<time_trigger>
seconds="0" />

<cycle>PT5M</cycle>
</time_trigger>
</trigger>
3.9 Requesting first counting gate values

Availability: APS firmware 1.0 This task is deprecated. It is available because of compatibility to
the older APC models. Please use if possible the
TASK_COUNT_CHANNELS.
This task forces the APS to post the data of the first active counting
gate to the server.
If no buffering in case of network interruption is requested and an
error occurs when sending a Count Message to the server, the
counts are summed up and sent in the next Count Message. Ena-
bling buffering for transmission errors saves every single Count
Message result with time stamp in case of network interruption. In
case of a network interruption or a new buffering message, the
APS attempts to send the oldest message every 60 seconds. If the
message was transferred successfully, all buffered messages will
be sent to the server.
Example
<task_subscribe_counting
task_type="TASK_COUNT"
serverTask_ID="4"
<trigger>

<event_trigger>
<count_event count_event_type=
"COUNT_EVENT_DELTA_SUM_IN_OUT"
delta="10"/>
</event_trigger>
</trigger>

<counting_gate_id id="0"/>
</task_subscribe_counting>
12
Task Messages
Requesting a current object list
3.10 Requesting all monitored zone values

Availability: APS firmware 1.2 This task forces the APS to post data of all monitored zones to the
server.
Enabling buffering for transmission errors saves every single Zone
Channel Message result with time stamp in case of network inter-
ruption. In case of a network interruption or a new buffering mes-
sage, the APC attempts to send the oldest message every 60 sec-
onds. If the message was transferred successfully, all buffered
messages will be sent to the server.
Example
<task_subscribe_zone_channels
task_type="TASK_ZONE_CHANNELS"
serverTask_ID="5"
<trigger>
<event_trigger>
<zone_channels_event />
</event_trigger>
</trigger>
</task_subscribe_zone_channels>
3.11 Requesting a current object list

Availability: APS firmware 1.0 This task forces the APS to post a data list of all the objects that
are currently located in the area of interest to the server. A special
current_object_list_event trigger could be used to force
the transmission only if the list contents have changed. Other
event- or time-based triggers are also available.
The prerequisite for the use of object lists is a license

file defined for this function, which is either pre-
installed on delivery or which can be later uploaded to
the APS.
Additional activate the object list feature in the HMI.
Example
<task_subscribe_objlist
task_type="TASK_CURRENT_OBJECT_LIST"
serverTask_ID="6"
transfer_type="TRANSFER_INLINE">
<trigger>
<event_trigger>
<current_object_list_event />
</event_trigger>
</trigger>
</task_subscribe_objlist>
13
Task Messages
Requesting wireless tracking
3.12 Requesting a historic object list

Availability: APS firmware 1.0 This task forces the APS to post a data list of all the objects that
have left the area of interest to the server. Object data that have
already been sent will not be resent.

file defined for this function, which is either pre-
installed on delivery or which can be later uploaded to
the APS.
Example
<task_subscribe_objlist
task_type="TASK_HISTORIC_OBJECT_LIST"
serverTask_ID="7" activity_state="true"
transfer_type="TRANSFER_INLINE">
<trigger>
<time_trigger>
<date kind="DATE_DONT_CARE"></date>
seconds="0"/>
<cycle>PT1M</cycle>
</time_trigger>
</trigger>
</task_subscribe_objlist>
3.13 Requesting wireless tracking

Availability: APS firmware 1.6 This task forces the APS to post a data list of all wireless devices
detected actually.
The prerequisite for the use of wireless tracking is an

addional wireless USB adapter and the associated
license file, which is either pre-installed on delivery or
which can be later attached and uploaded to the APS.
Additional activate the wireless tracking feature in the
HMI.
14
Task Messages
Set date and time
Example
<task_subscribe_wireless_tracking
task_type="TASK_WIRELESS_TRACKING"
serverTask_ID="12"
store_task="false">
<trigger>
<event_trigger>
<wireless_tracking_event />
</event_trigger>
</trigger>
</task_subscribe_wireless_tracking>
3.14 Requesting image snapshots

Availability: APS firmware 1.8 This task forces the APS to post camera images.
The size of the included images is not optimized and

include lossless PNG files. Therefore the message
size is ~ 1MB. Use it for maintenance e.g. once per
day or week or sensor startup, but not as video
streaming e.g. multiple times a minute.
Example
<task_subscribe_image_snapshots
task_type="TASK_IMAGE_SNAPSHOTS"
serverTask_ID="14"
store_task="false">
<trigger>
<time_trigger>
seconds="0" />

<cycle>P1D</cycle>
</time_trigger>
</trigger>
</task_subscribe_image_snapshots>
3.15 Set date and time

Availability: APS firmware 1.0 This task immediately forces the APS to set the internal clock. It
does not include any trigger.
This method is only to be used if no NTP server (Net-

work Time Protocol) is accessible. It is recommended
to use the NTP setup at the APS communication set-
tings.
15
Task Messages
Requesting deletion of all Task
Example
<task_set_date_time
task_type="TASK_SET_DATE_TIME"
serverTask_ID="8"
time_to_set="2013-08-01T10:00:00+02:00">
</task_set_date_time>
3.16 Requesting a firmware update

Availability: APS firmware 1.0 This task immediately forces the APS to download and install a
firmware. It does not include any trigger.
The APS try to download the firmware serveral times until the val-
idity time (hours) expired. A validity value of 0 is interpreted as
default 48 hours. The maximum is 168 hours (one week).
If the firmware update is successful the APS restarts and the
server get a startup notification including the new firmware version
identfication.
Download status and warnings and errors are not sent to the
server!
The URL contains the protocol (e.g. http or ftp),

optional username and password, the host, an optional
IP port, an optional path and the filename - e.g.:
http://example.com/updatefile.tar
http://username:password@example.com:
8080/path/ updatefile.tar
ftp://username:password@example.com/
path/updatefile.tar
Example
<task_request_update
task_type="TASK_UPDATE"
serverTask_ID="9"
update_type="UPDATE_FIRMWARE"
packet_url=
"ftp://username:password
@ftp.hella-aglaia.de/
temp/updatefile.tar"
validity="12">
</task_request_update>
3.17 Requesting deletion of all Task

Availability: APS firmware 1.2 This task immediately forces the APS to delete all task. If persis-
tent beyond reboots by store_task="true" or even if not - it
delte all tasks. It does not include any trigger.
16
Task Messages
Requesting deletion of all notifications
Use it in combination of new tasks in your task list to

keep in contact with the APS.
Example
<task_delete_all_tasks
task_type="TASK_DELETE_ALL_TASKS"
serverTask_ID="10" />
3.18 Requesting deletion of all notifications

Availability: APS firmware 1.2 This task immediately forces the APS to delete all buffered notifica-
tions. It does not include any trigger.
Use this carefully, if you do not the data anymore.
Example
<task_delete_all_notifications
task_type="TASK_DELETE_ALL_NOTIFICATIONS"
serverTask_ID="11" />
17
Task Messages and trigger
Time-based triggers > Date element
4 Task Messages and trigger

Task triggers can be time- or event-based.
4.1 Time-based triggers

Availability: APS firmware 1.0 Time-based triggers are defined by a start time and a repeat rate.
Example
<trigger>

<time_trigger>
<date kind="DATE_DONT_CARE"/>
<start hours="0" minutes="0" seconds="0"/>
<cycle>PT15M</cycle>
</time_trigger>
</trigger>
4.1.1 Date element

The kind attribute of the optional date element can have the fol-
lowing values:
DATE_DONT_CARE date not relevant

DATE_DAY_OF_WEEK weekly
DATE_DAY_OF_MONTH monthly
If no date is specified or kind="DATE_DONT_CARE", a trigger is

set irrespective of the date.
For kind="DATE_DAY_OF_WEEK", an additional day_of_week

attribute is required, which can have the following possible values:
MONDAY
TUESDAY
WEDNESDAY
THURSDAY
FRIDAY
SATURDAY
SUNDAY
18
Time-based triggers > Random offset element
For kind="DATE_DAY_OF_MONTH", an additional

day_of_month attribute is required for the day of the month
(1...31). In months with fewer days, a day attribute setting between
[29-31] fires the trigger on the last day of the month.
4.1.2 Start element

The start element specifies a relative delay time. In case of
DATE_DONT_CARE, the delay time is added to the current real time
of the APS to obtain the trigger time. In case of
DATE_DAY_OF_WEEK or DATE_DAY_OF_MONTH, the time of the
APS is set to 00:00:00 h plus the start time.
Cycle times are added to this start value, e.g. for a start time of
15:05:30 with a cycle time every 2 hours the trigger will fire at
15:05:30, 17:05:30, 19:05:30, 21:05:30, 23:05:30, 01:05:30 etc.
The start element uses APS local time depending to the time zone
setup of the APS.
Example
<start hours="15" minutes="0" seconds="0"/>
4.1.3 Cycle element

The cycle element specifies the repeat rate for firing the trigger.
This duration value is ISO 8601 conform (P = period designator, D
= day, T = time designator, H = hour, M = minute, S = second).
Example

<cycle>PT5M</cycle>

<cycle>P1D</cycle>
4.1.4 Random offset element

The random_offset element allows to spread out high-volume
data transfers to a server that services an APS fleet for improved
load balancing on the server.
The maximum offset can be specified using an xsd:duration value.
This duration value is ISO 8601 conform.
This random offset time is added to the start and cycle time
when these are fired. However, the next cycle time is not added to
the random offset time. With a start time of 12:00:00 and a cycle
time of one day, a random offset of one hour could result in the fol-
lowing trigger times once a day: 12:59:59, 12:00:00; 12:12:34,
12:43:21, etc.
19
Event-based trigger > Feature changed event
Example

<random_offset>PT30M</random_offset>
4.2 Event-based trigger

Availability: APS firmware 1.0 In addition to scheduled triggering, events and logical comparisons
of values with customizable constants can be used for firing trig-
gers.
Example
<trigger>
<event_trigger>

<count_channels_event />
</event_trigger>
</trigger>
The event_trigger element contains exactly one element from

the following list:
feature_changed_event fired if settings changed

e.g. a name of a counting
gate
count_channels_event fired if someone counted
at any counting gate
count_event fired only at counts of the
first counting gate
zone_channels_event fired if someone enter or
leave a monitored zone
one_time_event one-time only event for
immediate execution
current_object_list_event fired at object list
changes e.g. a moving
person
4.2.1 Feature changed event

Availability: APS firmware 1.0 The feature_changed_event trigger fires when the configura-
tion changed e.g. the name of a counting gate or monitored zone.
This could be useful to synchonize database and incoming data.
20
Event-based trigger > Count channels event
Example
<trigger>
<event_trigger>

</event_trigger>
</trigger>
4.2.2 Count channels event

Availability: APS firmware 1.0 The count_channels_event trigger fires when someone
counted at any of the active counting gates.
Example
<trigger>
<event_trigger>
<count_channels_event />
</event_trigger>
</trigger>
21
Event-based trigger > Zone channels event
4.2.3 Count event

Availability: APS firmware 1.0 This event is deprecated. It is available because of compatibility to
count_channels_event above.
This event only handle changes of the first active counting gate.
The count event trigger has the following two mandatory attributes:
count_event_type:
COUNT_EVENT_ALWAYS on any count event

COUNT_EVENT_DELTA_IN on counting delta change for IN direction
COUNT_EVENT_DELTA_OUT on counting delta change for OUT direc-
tion
COUNT_EVENT_DELTA_SUM_IN_OUT on counting delta change of the sum for
IN and OUT direction
COUNT_EVENT_DELTA_MAX_IN_OUT on counting delta change of the maximum
for IN and OUT direction
delta: the value of change for the above count event types
Example
<trigger>
<event_trigger>
<count_event

count_event_type=
"COUNT_EVENT_DELTA_SUM_IN_OUT"
delta="10"/>
</event_trigger>
</trigger>
4.2.4 Zone channels event

Availability: APS firmware 1.2 The zone_channels_event trigger fires when someone enter or
leave any of the active monitored zones.
Example
<trigger>
<event_trigger>
<zone_channels_event />
</event_trigger>
</trigger>
22
Event-based trigger > Optical self diagnosis event
4.2.5 Current object list event

Availability: APS firmware 1.0 The current_object_list_event trigger fires when the cur-
rent object list is changed. This occurs when objects such as
people are moving within the area of interest or people are entering
or leaving this area.
An recommended but optional skip attribute with a milliseconds
value could be used as data reduction option. Valid values for
skip are 1 to 1000 milliseconds - recommended values are about
250 to 500 ms. If all the people have left the area within the skip
time interval, an empty list will be sent immediately.

file defined for this function.
Example
<trigger>
<event_trigger>

<current_object_list_event skip="1000" />
</event_trigger>
</trigger>
4.2.6 Wireless tracking event

Availability: APS firmware 1.6 The wireless_tracking_event trigger fires when the wireless
tracking services refresh the data list e.g. after a scanning of all
channels.
Example
<trigger>
<event_trigger>

<wireless_tracking_event />
</event_trigger>
</trigger>
4.2.7 Optical self diagnosis event

Availability: APS firmware 1.8 The osd_event trigger fires when the Optical Self Diagnosis
(OSD) status changes.
The APS could check its visible range by the Optical Self Diag-
nosis (OSD):
n OSD_STATE_OK
normal state
n OSD_ERROR_COVERED
e.g. by a sticker, also only to one of the two camera sensors
23
Event-based trigger > Startup event
n OSD_ERROR_TOO_DARK
illumination is less than ~7 lux
n OSD_ERROR_TOO_BRIGHT
more hypothetical,
because direct sunlight and reflexions from sunlight do not
cause "too bright"
The sensor did not stop counting in case of these errors. These
values could help in maintenance issues and is also available in
protocols to validate data.
Example
<trigger>
<event_trigger>

<osd_event />
</event_trigger>
</trigger>
4.2.8 One-time event

Availability: APS firmware 1.0 The one_time_event trigger fires once immediately.
4.2.9 Startup event

Availability: APS firmware 1.0 This trigger fires at the APS startup sequence. For APS with ena-
bled push service at the HMI, a startup notification message is fired
by this trigger, by default.
24
Server answer messages
5 Server answer messages

Availability: APS firmware 1.0 The server responds to APS notification messages with a
(added "server down" starting from answer_message container including the acknowledgement of
version 1.8) incoming APS messages and optionally a list invoking new tasks
as described in Ä Chapter 3 ‘Task Messages’ on page 7.
It starts with a SOAP envelope and namespace definitions. The
answer_message element itself has the following mandatory
attributes:
n referenced_notification_ID: reference to the ID used in
the message from the APS
n server_response_type: status information with possible
values according to the following table.
SOAP_SERVER_OK APS message pro-

cessed without error
SOAP_ERROR_UNKNOWN_RESPONSE mapping error
SOAP_ERROR_UNKNOWN_MESSAGE unknown unpro-
cessed message
SOAP_ERROR_UNKNOWN_DEVICE unknown APS
SOAP_ERROR_SERVER_DOWN the server can not
acknoledge the
message, please
send again.
All server_response_type values are used as acknoledge and

stop sending a message - exept the SOAP_ERROR_SERVER_DOWN
that signal the APS to resend a message.
25
Server answer messages
Example
<?xml version="1.0" encoding="utf-8"?>
<soap:Envelope
xmlns:soap=
"http://www.w3.org/2003/05/soap-envelope"
xmlns:xsi=
"http://www.w3.org/2001/XMLSchema-instance"
xmlns:xsd=
"http://www.w3.org/2001/XMLSchema">
<soap:Body>
<answer_message
referenced_notification_ID="8"
server_response_type="SOAP_SERVER_OK"
xmlns="http://www.aglaia-gmbh.de/xml/
2013/05/17/BaSS_SOAPd.xsd">
<task_subscribe_features_info
serverTask_ID="1"
<trigger>
<event_trigger>
</event_trigger>
</trigger>
</task_subscribe_features_info>
serverTask_ID="2"
<trigger>
<time_trigger>
seconds="0" />
<cycle>PT5M</cycle>
</time_trigger>
</trigger>
</answer_message>
</soap:Body>
</soap:Envelope>
26
APS notification messages
6 APS notification messages

Availability: APS firmware 1.0 The APS posts notification messages to the server in the
(added OSD status other than OK notification_message container format. This notification
and hardware model starting from includes the pushed data invoked by tasks.
version 1.8)
It starts with a SOAP envelope and namespace definitions. The
notification_message within the SOAP body is only a con-
tainer without specific parameters.
Example
<?xml version="1.0" encoding="UTF-8"?>
<SOAP-ENV:Envelope
xmlns:SOAP-ENV=
xmlns:SOAP-ENC=
"http://www.w3.org/2003/05/soap-encoding"
xmlns:xsi=
xmlns:xsd=
"http://www.w3.org/2001/XMLSchema"
xmlns:sde1=
"http://www.aglaia-gmbh.de/xml/BaSS_SOAPd/"
xmlns:sde2=
"http://www.aglaia-gmbh.de/xml/
<SOAP-ENV:Body>
<sde2:notification_message>
<sde2:alive_notification
timestamp=
"2016-02-05T12:04:38.025271+01:00"
callerType_ID="SERVER"
serverTask_ID="2"
notification_ID="6"
customer_ID="SENSOR01ABCD"
mac_address="00:0B:91:80:AB:CD"
osd_state="OSD_STATE_OK"
customer_version="unsupported feature"
model="APS-90-8GB"
firmware_version="1.8.0.3"
ip_address="192.168.100.10">
</sde2:alive_notification>
</sde2:notification_message>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>
In the following notification messages examples, XML

header, SOAP envelope and body header, name-
spaces and notification message container are omitted
for better readability.
All time stamp informations using the ISO 8601 format. It includes
the date as YYYY-MM-DD (year-month-day), the time seperator T,
the time as hh:mm:ss.fffff (hour:mintute:second.fraction) and time
zone information +01:00 (+/-hh:mm) or Z as UTC time.
27
Startup
To devide sensors to special APS variants the start, alive and error
messages include starting with firmware 1.8 a model information
(e.g. APS-90 or APS-180-IO-8GB).
model memor digital outdoor height

y IOs
APS-90 - - - 2.0 - 3.50 m
APS-90-8GB yes - - 2.0 - 3.50 m
APS-90-IO-8GB yes yes - 2.0 - 3.50 m
APS-180 - - - 3.0 - 6.0 m
APS-180-8GB yes - - 3.0 - 6.0 m
APS-180-IO - yes - 3.0 - 6.0 m
APS-180-IO-8GB yes yes - 3.0 - 6.0 m
APS-90-Outdoor- yes yes yes 2.0 - 4.0 m
PoE
The status of the Optical Self Diagnosis (OSD) osd_state is

included in all messages that contain optically determined values
and additional in start, alive and error messages. The osd_state
contains one of the following values:
OSD_STATE_OK normal operation, no errors.

OSD_ERROR_COVERED e.g. by a sticker, also only to
one of the two camera sensors
OSD_ERROR_TOO_DARK illumination is less than ~7 lux
OSD_ERROR_TOO_BRIGHT more hypothetical,
because direct sunlight and
reflexions from sunlight do not
cause "too bright"
OSD_ERROR general OSD error
The sensor did not stop counting in case of OSD errors. These
values could help in maintenance issues and is also available in
protocols to validate data.
6.1 Startup
Availability: APS firmware 1.0 The startup notification is fired at the startup process of the APS.
This message with the respective trigger is predefined and cannot
be disabled. The time is send with the time zone offset configured
in the APS settings.
28
Features info
Example
<startup_notification
xml_version=
2015/05/17/BaSS_SOAPd.xsd"
reboot_type="SOAP_REBOOT_POWERON"
timestamp="2017-03-15T10:03:55.934850+01:00"
callerType_ID="SELF"
serverTask_ID="0"
notification_ID="1"
task_type="TASK_STARTUP"
model="APS-90-8GB"
ip_address="192.168.100.10">
</startup_notification>
6.2 Alive
Availability: APS firmware 1.0 Alive notifications should be used to stay in contact with the APS,
to invoke new tasks and for maintenance purposes.
For general maintenance, a standard task sends an alive notifica-
tion cyclically every 3 hours plus a random offset time of 0 to up to
5 minutes. This task and the notification with the respective trigger
are predefined and cannot be disabled. It can be identified by a
serverTask_ID="0" and callerType_ID="SELF".
Example
<alive_notification
timestamp="2017-03-15T10:05:00.642243+02:00"
serverTask_ID="2"
notification_ID="5"
osd_state="OSD_STATE_WARNING_DARK"
model="APS-90-8GB"
ip_address="192.168.100.10">
</alive_notification>
6.3 Features info

Availability: APS firmware 1.0 The features info notification helps to synchronize APS settings
and data storage. E.g. the database table columns and the names
of counting gates and monitored zones in the HMI of the APS.
29
Features info
If your are using the Object Classification feature, than addional

entities for every class are posted including the class type as e.g.
objClass="Adult".
Example
<features_info_notification
ip_address="192.168.100.10"
timestamp="2017-03-15T10:39:10.791321Z"
serverTask_ID="18"
notification_ID="21"
mac_address="00:0B:91:80:AB:CD">
<active_count_channels>
<count_channel
objClass="Adult"
name="Gate-A-left">
</count_channel>
<count_channel
objClass="Child"
name="Gate-A-left">
</count_channel>
<count_channel
objClass="Adult"
name="Gate-B-right">
</count_channel>
<count_channel
objClass="Child"
name="Gate-B-right">
</count_channel>
</active_count_channels>
<active_zone_channels>
<zone_channel
objClass="Adult"
name="Zone-Entrance">
</zone_channel>
<zone_channel
objClass="Child"
name="Zone-Entrance">
</zone_channel>
<zone_channel
objClass="Adult"
name="Zone-Exit">
</zone_channel>
<zone_channel
objClass="Child"
name="Zone-Exit">
</zone_channel>
</active_zone_channels>
</features_info_notification>
30
Count
6.4 Count channels

Availability: APS firmware 1.0 The Hella Advanced People Sensor is used for counting people.
This notification is designed for all its counting gates (as opposed
to count_notification for a single counting gate). The trigger
can be time- or event-based, e.g. when anybody at a counting line
is counted.
The most important values of this count channel message are
given in count_in and count_out – the people that were
counted crossing the counting gate in either direction.
objClass="Adult".
Example
<count_channels_notification
timestamp="2017-03-15T10:47:11.964335Z"
serverTask_ID="11"
<count_channel
count_out="2"
count_in="1"
objClass="Adult"
channel_name="Gate-A-left">
</count_channel>
<count_channel
count_out="0"
count_in="1"
objClass="Child"
channel_name="Gate-A-left">
</count_channel>
<count_channel
count_out="2"
count_in="1"
objClass="Adult"
channel_name="Gate-B-right">
</count_channel>
<count_channel
count_out="1"
count_in="2"
objClass="Child"
channel_name="Gate-B-right">
</count_channel>
</count_channels_notification>
6.5 Count
Availability: APS firmware 1.0 This task is deprecated. It is available because of compatibility to
TASK_COUNT_CHANNELS.
31
Zone channels
This notification is designed for a single counting gate (as opposed

to count channels notification for multiple counting gates). The
trigger can be time- or event-based, e.g. when a predefined
number of people has been counted.
The most important values of this count notification are given in
count_in and count_out – the people that were counted
crossing the counting gate in either direction.
Example
<count_notification
count_out="123"
count_in="111"
timestamp="2017-03-15T10:45:00.854691+02:00"
serverTask_ID="1"
task_type="TASK_COUNT"
osd_state="OSD_STATE_OK">
<counting_gate_id id="0">
</counting_gate_id>
</count_notification>
6.6 Zone channels

Availability: APS firmware 1.2 The APS detect the amount of people inspecified minitored zones.
The most important values of this zone channel message are given
in fill_level – the amount of people that are detected in a
zone.
objClass="Adult".
32
Zone channels
Example
<zone_channels_notification
timestamp="2017-03-15T15:53:16.054250+02:00"
serverTask_ID="2"
notification_ID="5"
task_type="TASK_ZONE_CHANNELS"
<zone_channel
fill_level="3"
objClass="Adult"
zone_name="Zone-Entrance">
</zone_channel>
<zone_channel
fill_level="0"
objClass="Child"
zone_name="Zone-Entrance">
</zone_channel>
<zone_channel
fill_level="2"
objClass="Adult"
zone_name="Zone-Exit">
</zone_channel>
<zone_channel
fill_level="1"
objClass="Child"
zone_name="Zone-Exit">
</zone_channel>
</zone_channels_notification>
33
Current object list
6.7 Current object list

Availability: APS firmware 1.0 The APS detects objects and people that are currently located in
the customizable area of interest. The trigger can be time-based or
event-based.
The current object list notification contains a list of objects that are
currently detected in the configured floor area. To signal that all
people left the area it will send an empty list.
objClass="Adult".
The most important values of single detected objects in this list are:
id General identifier of an
object across mes-
sages.
dwell Length of stay of an
object in the AOI. Unit of
measurement in sec-
onds with milliseconds
in the fractional part.
entry AOI entry coordinate
described by x and y at
ground level and with
the height z. Unit of
measurement is cm.
pos Current coordinate
measurement is cm.
mov Motion vector described
by x and y at ground
level. Unit of measure-
ment is cm/s.
objClass Current object classifica-
tion for this object as
Adult, Child or
Unknown.
34
Current object list
Example
<curr_objlist_notification
timestamp="2017-03-15T10:50:27.276103+02:00"
serverTask_ID="1003"
task_type="TASK_CURRENT_OBJECT_LIST"
<obj
dwell="0.850"
zone="00000"
objClass="Child"
id="9">
<entry z="120" y="-68" x="6">
</entry>
<pos z="125" y="-4" x="19">
</pos>
<mov y="-12" x="6">
</mov>
</obj>
<obj
dwell="1.650"
zone="00000"
objClass="Adult"
id="13">
<entry z="182" y="-69" x="-26">
</entry>
<pos z="185" y="93" x="91">
</pos>
<mov y="14" x="29">
</mov>
</obj>
</curr_objlist_notification>
35
Historic object list
6.8 Historic object list

Availability: APS firmware 1.0 The APS detects objects and people that are leaving the customiz-
able area of interest. The trigger can be time-based or event-
based.
The historic object list message contains a list of detected objects
that are leaving the configured floor area.
objClass="Adult".
The most important values of the detected objects are:
id General identifier of an
object across mes-
sages.
dwell Length of stay of an
object in the AOI. Unit of
measurement in sec-
onds with milliseconds
in the fractional part.
exit_time Time stamp when the
object leaves the AOI.
You can calculate the
entry time to the AOI
using the exit time and
the length of stay.
entry AOI entry coordinate
measurement is cm.
exit AOI exit coordinate
measurement is cm.
height Average of all height
measurements. Unit of
measurement is cm.
objClass Current object classifica-
tion for this object as
Adult, Child or
Unknown.
36
Historic object list
Example
<hist_objlist_notification
lost_count="0"
timestamp="2017-03-15T10:50:27.313766+02:00"
serverTask_ID="1004"
task_type="TASK_HISTORIC_OBJECT_LIST"
<obj
height="184"
exit_time=
"2012-11-01T12:50:27.310350+02:00"
dwell="1.650"
zone="00000"
objClass="Adult"
id="13">
<entry z="182" y="-69" x="-26">
</entry>
<exit z="185" y="-18" x="21">
</exit>
</obj>
</hist_objlist_notification>
37
Wireless tracking
6.9 Wireless tracking

Availability: APS firmware 1.6 (MAC The APS detects wireless devices as smartphones by an addional
address base type changed to wireless USB adapter. The trigger can be time-based or event-
string starting of firmware 1.8) based.
The wireless tracking message contains beside of the time stramp
of the last tracking itself a list of maximum 256 detected devices.
The most important values of the detected devices are:
mac_address The MAC address of the

detected device as iden-
tification.
(in future releases this
may be an encrypted
string instead of a
standard MAC)
wireless_type The type of wireless
detection as WIFI,
BLUETOOTH or
UNKNOWN.
signal_strength The signal strength of
WiFi is between 0 to
-100. The higher the
value, the better the
signal strength (a zero
value is good, and a
-100 is a bad signal
strength).
Following firmware ver-
sions with Bluetooth
signal strength values
will be in a -128 to 127
range.
38
Image snapshots
Example
<wireless_tracking_notification
timestamp="2017-03-15T10:33:05.009113+02:00"
serverTask_ID="12"
task_type="TASK_WIRELESS_TRACKING"
customer_ID="host"
<wireless_tracking_results
timestamp="2016-11-03T10:33:05.008234+02:00">
<wireless_tracking_result
signal_strength="-60"
wireless_type="WIFI"
mac_address="AB:CD:EF:01:23:45" />
<wireless_tracking_-result
signal_strength="-42"
wireless_type="BLUETOOTH"
mac_address="FE:DC:BA:98:76:54" />
</wireless_tracking_results>
</wireless_tracking_notification>
6.10 Image snapshots

Availability: APS firmware 1.8 This APS notification is designed for maintenance issues. The APS
post camera images.
These three camera images posted as Base64 encoded archive
file Snapshots_[MAC]_[DATE]_[TIME].tar.gz (e.g.
Snapshots_000B91900045_2017-03-16_11-15-04.tar.gz)
:
n snapshot_dispmap.png
include stereo image informations
n snapshot_original_left.png
unrectified original left camera image
n snapshot_rectified_right.png
rectified right camera image
The size of the included images is not optimized and

include lossless PNG files. Therefore the message
size is ~ 1MB. Use it for maintenance e.g. once per
day or week or sensor startup, but not as video
streaming e.g. multiple times a minute.
39
APS error message
Example
<image_snapshots_notification
mac_address="00:0B:91:90:00:45"
customer_ID="APS900045"
notification_ID="7" serverTask_ID="4"
timestamp="2017-03-16T11:15:04.671328Z"
<snapshots>
<bin_data>

</bin_data>
</snapshots>
</image_snapshots_notification>
6.11 APS error message

Availability: APS firmware 1.0 If the server sends an invalid answer message, the APS returns an
(added -NO_LICENSE and - error_message.
TASK_EXECUTION starting from
version 1.8) This error message is structured like a notification message and
contains the error_reason attribute with one of the following values:
SOAP_DEVICE_OK no error, task accepted

SOAP_ERROR_UNKNOWN_TASK task unknown or not implemented
SOAP_ERROR_UNKNOWN_PARAM task parameter unknown or not implemented
SOAP_ERROR_UNKNOWN_OUT_OF_RESSOURCES problems with the memory capacity of the APS
SOAP_ERROR_NO_LICENSE task initiated without licence for an add-on feature
SOAP_ERROR_TASK_EXECUTION execution of a task immediately stopped because of
errors
40
APS error message
Example

<SOAP-ENV:Envelope
xmlns:SOAP-ENV=
xmlns:SOAP-ENC=
"http://www.w3.org/2003/05/soap-encoding"
xmlns:xsi=
xmlns:xsd=
"http://www.w3.org/2001/XMLSchema"
xmlns:sde1=
"http://www.aglaia-gmbh.de/xml/BaSS_SOAPd/"
xmlns:sde2=
<SOAP-ENV:Body>
<sde2:error_message
error_text=
"src... error: Trigger not implemented
(cancel)."
error_reason="SOAP_ERROR_UNKNOWN_PARAM"
timestamp=
"2017-03-15T17:27:41.608587+02:00"
serverTask_ID="3"
notification_ID="2"
task_type="TASK_FILL_LEVEL"
model="APS-90-8GB"
ip_address="192.168.100.10"
</sde2:error_message>
</SOAP-ENV:Body>
<SOAP-ENV:Envelope>
41
Examples
Startup with invocation of tasks
7 Examples
Some short examples to understand the typical communication.
7.1 Startup with invocation of tasks

Below the communication of the following scenario:
n at startup the APS send the startup notification to the server
n the server acknowledge it inluding 2 new tasks:
a) sending counting data every minute
b) sending camera images for maintenance all 15 minutes
n the APS send its counting data at the next time slot of every
minute as requested
n the server acknowledge this counting data (otherwise it will be
stored and resend)
n the APS send its next counting data at the next time slot of
every minute as requested
stored and resend)
n the APS send its camera images at the next time slot of every
15 minutes as requested
(the big binary data encoded as Base64 is not included in the
example below)
n the server acknowledge this camera data
n the APS send its next counting data at the next time slot of
every minute as requested
stored and resend)
n and so on...
42
Examples
Example
APS -> Server 16.03.2017 12:13:23

---------------------------------
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://
www.w3.org/2003/05/soap-envelope" xmlns:SOAP-
ENC="http://www.w3.org/2003/05/soap-encoding"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-
instance" xmlns:xsd="http://www.w3.org/2001/
XMLSchema" xmlns:sde1="http://www.aglaia-
gmbh.de/xml/BaSS_SOAPd/" xmlns:sde2="http://
www.aglaia-gmbh.de/xml/2013/05/17/
BaSS_SOAPd.xsd">
<SOAP-ENV:Body>
<sde2:startup_notification
xml_version="http://www.aglaia-gmbh.de/xml/
2013/05/17/BaSS_SOAPd.xsd"
reboot_type="SOAP_REBOOT_POWERON"
model="APS-90-8GB"
ip_address="192.168.100.48"
timestamp="2017-03-16T11:13:22.194122+00:00"
callerType_ID="SELF" serverTask_ID="0"
notification_ID="1" task_type="TASK_STARTUP"
customer_ID="APS900045" mac_address="00:0B:
91:90:00:45">
</sde2:startup_notification>
</SOAP-ENV:Body>
Server -> APS 16.03.2017 12:13:23

----------------------------------
<soap:Envelope xmlns:soap="http://www.w3.org/
2003/05/soap-envelope" xmlns:xsi="http://
www.w3.org/2001/XMLSchema-instance"
xmlns:xsd="http://www.w3.org/2001/XMLSchema">
<soap:Body>
<answer_message
store_task="false"
<trigger>
<time_trigger>
seconds="0" />
<cycle>PT1M</cycle>
</time_trigger>
43
Examples
</trigger>
<task_subscribe_image_snapshots
store_task="false">
<trigger>
<time_trigger>
seconds="0" />
<cycle>PT15M</cycle>
</time_trigger>
</trigger>
</task_subscribe_image_snapshots>
</answer_message>
</soap:Body>
</soap:Envelope>
APS -> Server 16.03.2017 12:14:00

---------------------------------
BaSS_SOAPd.xsd">
<SOAP-ENV:Body>
<sde2:count_channels_notification
timestamp="2017-03-16T11:14:00.008034+00:00"
callerType_ID="SERVER" serverTask_ID="2"
notification_ID="4"
91:90:00:45">
<sde2:count_channel count_out="0"
count_in="0" objClass="Adult"
channel_name="Polyline0">
</sde2:count_channel>
count_in="0" objClass="Child"
</sde2:count_channels_notification>
</SOAP-ENV:Body>
Server -> APS 16.03.2017 12:14:00

----------------------------------
44
Examples
<soap:Body>
<answer_message
2013/05/17/BaSS_SOAPd.xsd" />
</soap:Body>
</soap:Envelope>
APS -> Server 16.03.2017 12:15:00

---------------------------------
BaSS_SOAPd.xsd">
<SOAP-ENV:Body>
timestamp="2017-03-16T11:15:00.024958+00:00"
notification_ID="6"
91:90:00:45">
</SOAP-ENV:Body>
Server -> APS 16.03.2017 12:15:00

----------------------------------
<soap:Body>
<answer_message
</soap:Body>
</soap:Envelope>
APS -> Server 16.03.2017 12:15:05

---------------------------------
45
Examples

BaSS_SOAPd.xsd">
<SOAP-ENV:Body>
<sde2:image_snapshots_notification
timestamp="2017-03-16T11:15:04.671328+00:00"
notification_ID="7"
91:90:00:45">
<sde2:snapshots>
<sde2:bin_data></sde2:bin_data>
</sde2:snapshots>
</sde2:image_snapshots_notification>
</SOAP-ENV:Body>
Server -> APS 16.03.2017 12:15:05

----------------------------------
<soap:Body>
<answer_message
</soap:Body>
</soap:Envelope>
APS -> Server 16.03.2017 12:16:00

---------------------------------
BaSS_SOAPd.xsd">
<SOAP-ENV:Body>
timestamp="2017-03-16T11:16:00.028168+00:00"
46
Examples
notification_ID="9"
91:90:00:45">
</SOAP-ENV:Body>
Server -> APS 16.03.2017 12:16:00

----------------------------------
<soap:Body>
<answer_message
</soap:Body>
</soap:Envelope>
...
47
Examples
Persistent tasks stored inside the APS
7.2 Persistent tasks stored inside the APS

Task stored in RAM by default and will be deleted at reboot of the
APS. Using persistent tasks require using store_task="true"
as attribute or by placing task files inside the APS (see Ä Chapter
3.5 ‘Persistent tasks beyond reboots’ on page 10).
These task files will look like the following two example tasks:
Example task_01.xml
<sde2:task_subscribe_count_channels xmlns:SOAP-
ENV="http://www.w3.org/2003/05/soap-envelope"
xmlns:SOAP-ENC="http://www.w3.org/2003/05/soap-
encoding" xmlns:xsi="http://www.w3.org/2001/
XMLSchema-instance" xmlns:xsd="http://
www.w3.org/2001/XMLSchema" xmlns:sde1="http://
www.aglaia-gmbh.de/xml/BaSS_SOAPd/"
xmlns:sde2="http://www.aglaia-gmbh.de/xml/
2013/05/17/BaSS_SOAPd.xsd" SOAP-
ENV:encodingStyle="http://www.w3.org/2003/05/
soap-encoding"
store_on_transmission_error="true"
store_task="true" activity_state="true"
serverTask_ID="2"
task_type="TASK_COUNT_CHANNELS"><sde2:trigger><
sde2:time_trigger><sde2:date
kind="DATE_DONT_CARE"></sde2:date><sde2:start
seconds="0" minutes="0" hours="0"></
sde2:start><sde2:cycle>PT0H1M0S</
sde2:cycle><sde2:random_offset>PT0S</
sde2:random_offset></sde2:time_trigger></
sde2:trigger></
sde2:task_subscribe_count_channels>
Example task_02.xml
<sde2:task_subscribe_image_snapshots
xmlns:SOAP-ENV="http://www.w3.org/2003/05/soap-
envelope" xmlns:SOAP-ENC="http://www.w3.org/
2003/05/soap-encoding" xmlns:xsi="http://
xmlns:xsd="http://www.w3.org/2001/XMLSchema"
xmlns:sde1="http://www.aglaia-gmbh.de/xml/
BaSS_SOAPd/" xmlns:sde2="http://www.aglaia-
gmbh.de/xml/2013/05/17/BaSS_SOAPd.xsd" SOAP-
ENV:encodingStyle="http://www.w3.org/2003/05/
soap-encoding" store_task="true"
activity_state="true" serverTask_ID="3"
task_type="TASK_IMAGE_SNAPSHOTS"><sde2:trigger>
<sde2:time_trigger><sde2:date
kind="DATE_DONT_CARE"></sde2:date><sde2:start
seconds="0" minutes="0" hours="0"></
sde2:start><sde2:cycle>PT0H15M0S</
sde2:cycle><sde2:random_offset>PT0S</
sde2:random_offset></sde2:time_trigger></
sde2:trigger></
sde2:task_subscribe_image_snapshots>
48
Tools
APS
8 Tools
8.1 WSDL
Availability: APS firmware 1.0 Both the APS and the server use the same WSDL file defining the
SOAP interface.
This WSDL file can be translated with different SOAP toolkits to
communication stubs in C, C++, .NET, JAVA, php etc. The main
WSDL file is named BASS_SOAPd.wsdl. It includes the XML
schema definition BaSS_SOAPd.xsd.
Feel free not to use such a toolkit. It is also possible to build your
code from scretch by using string comparison or XML libraries.
8.2 APS
Availability: APS firmware 1.0 The APS contains a push service for data transfer via SOAP.
Use the web HMI to enable the push service, configure the pro-
tocol (HTTP or HTTPS), server IP address or the fully qualified
domain name of the server, IP port and possibly the HTTP proxy
settings for connecting to the server ( Ä ‘Availability: APS firmware
1.0’ on page 49).
Fig. 2: Push service
If enabled, every reboot triggers a startup notification message to

the server, by default. The server can respond to this message and
invoke new tasks for sending data.
49
Tools
APS
The APS retries to send the startup message until the connection
to the server is established. In addition to this startup message, the
APS sends an Alive Message cyclically every 3 hours plus a
random offset time of 0 to up to 5 minutes for maintenance pur-
poses.
The SOAP interfaces defined by WSDL are transformed using a
toolkit called gSOAP version 2.7. to generate C/C++ stubs. Use
this gSOAP as reference implementation, if you use different tool-
kits or you create your own code.
The following command generates a "SOAPd.h" C header file

from the WSDL:
>wsdl2h -c SOAPd.wsdl
To generate client-side C source code files from this header file:
>soAPSpp2 -c -C -x SOAPd.h
This command generates the files "soapStub.h", "soapH.h",
"soAPS.c", "soAPSlient.c", and "soAPSlientLib.c"
(Fig. 3), that you can use for further development.
Fig. 3: File generation
50
Appendix
APS error codes
9 Appendix
9.1 OSD status codes
Availability: APS firmware 1.0 The status of the Optical Self Diagnosis (OSD) osd_state is
(added -COVERED, -TOO_DARK, - included in all messages that contain optically determined values
TOO_BRIGHT starting from version and additional in start, alive and error messages. The osd_state
1.8) contains one of the following values:
OSD_STATE_OK normal operation, no errors.

OSD_ERROR_COVERED e.g. by a sticker, also only to
one of the two camera sensors
OSD_ERROR_TOO_DARK illumination is less than ~7 lux
OSD_ERROR_TOO_BRIGHT more hypothetical,
because direct sunlight and
reflexions from sunlight do not
cause "too bright"
OSD_ERROR more hypothetical,
general OSD error
9.2 APS error codes

Availability: APS firmware 1.0 If the server sends an invalid answer message, the APS returns an
(added -NO_LICENSE and - error_message.
TASK_EXECUTION starting from
version 1.8) This error message is structured like a notification message and
contains the error_reason attribute with one of the following values:
Error Description
SOAP_DEVICE_OK no error, task accepted
SOAP_ERROR_UNKNOWN_TASK task unknown or not implemented
SOAP_ERROR_UNKNOWN_PARAM task parameter unknown or not implemented
SOAP_ERROR_UNKNOWN_OUT_OF_RESSOURCES problems with the memory capacity of the APS
SOAP_ERROR_NO_LICENSE task initiated without licence for an add-on feature
SOAP_ERROR_TASK_EXECUTION execution of a task immediately stopped because of
errors
51
Appendix
Syslog error codes
9.3 Server error codes

Availability: APS firmware 1.0 The server responds to APS messages with a
(added <answer_message> container. This includes the acknowledge-
SOAP_ERROR_SERVER_DOWN ment of incoming APS messages by the
starting from version 1.8) server_response_type status information:
Error Description
SOAP_SERVER_OK APS message processed without error
SOAP_ERROR_UNKNOWN_RESPONSE mapping error
SOAP_ERROR_UNKNOWN_MESSAGE unknown unprocessed message
SOAP_ERROR_UNKNOWN_DEVICE unknown APS
SOAP_ERROR_SERVER_DOWN the server can not acknoledge the message, please
send again.
9.4 Syslog error codes

Availability: APS firmware 1.0 The APS use typical system log files that could contain some log-
ging of error cases of the Push Services. The logfiles are available
in the HMI at the menu entry "Service Tools", "Get Diagnosis
Data’". Inside this compressed package of text files search for the
file "messages" (current log file) - and if existing "messages.0" and
"messages.1" (old log files).
An example of a log entry of a failure to open a connection by the
APS to the Push Service server e.g. by network interuption:
Example
Jan 8 05:04:38 (none) user.warn soap: SOAPd
Error: Failed to send Count Notification.
(error code: 28)
The error code depends to SOAP library (-1 ... 49) or the http layer
used below (200 ... 505).
52
Appendix
Syslog error codes > SOAP error codes
9.4.1 SOAP error codes

Availability: APS firmware 1.0 The SOAP error code is one of the following error types:
Error Code Description

SOAP_EOF -1 Unexpected end of (file) response by server, no response or
timeout (20 sec) receiving data
SOAP_ERR -1 for internal use, alias for SOAP_EOF
SOAP_OK 0 No error
SOAP_CLI_FAULT 1 The service returned a client fault (SOAP 1.2 Sender fault)
SOAP_SVR_FAULT 2 The service returned a server fault (SOAP 1.2 Receiver fault)
SOAP_TAG_MISMATCH 3 An XML element didn't correspond to anything expected
SOAP_TYPE 4 An XML Schema type mismatch
SOAP_SYNTAX_ERROR 5 An XML syntax error occurred on the input
SOAP_NO_TAG 6 Begin of an element expected, but not found
SOAP_IOB 7 Array index out of bounds
SOAP_MUSTUNDERSTAND 8 An element needs to be ignored that need to be understood
SOAP_NAMESPACE 9 Namespace name mismatch (validation error)
SOAP_USER_ERROR 10 User error (reserved for soap.user usage)
SOAP_FATAL_ERROR 11 Internal error
SOAP_FAULT 12 An exception raised by the service
SOAP_NO_METHOD 13 The dispatcher did not find a matching operation for a request
SOAP_NO_DATA 14 No data in HTTP message
SOAP_GET_METHOD 15 HTTP GET operation not handled
SOAP_PUT_METHOD 16 Standard error code by unimplemented callback method
SOAP_DEL_METHOD 17 Standard error code by unimplemented callback method
SOAP_HEAD_METHOD 18 Standard error code by unimplemented callback method
SOAP_HTTP_METHOD 19 Standard error code by unimplemented callback method
SOAP_EOM 20 Out of memory
SOAP_MOE 21 Memory overflow/corruption error (DEBUG mode)
SOAP_HDR 22 SOAP Header error
SOAP_NULL 23 An element was null, while it is not supposed to be null
SOAP_DUPLICATE_ID 24 Element's ID duplicated (multi-ref encoding)
SOAP_MISSING_ID 25 Element ID missing for an href/ref (multi-ref encoding)
SOAP_HREF 26 Reference to object is incompatible with the object refered to
SOAP_UDP_ERROR 27 Message too large to store in UDP packet
SOAP_TCP_ERROR 28 A connection error occured, no connection to server available -
e.g. by network interruption
53
Appendix
Syslog error codes > SOAP error codes

SOAP_HTTP_ERROR 29 An HTTP error occured
SOAP_SSL_ERROR 30 An SSL error occured
SOAP_ZLIB_ERROR 31 A Zlib error occured
SOAP_DIME_ERROR 32 DIME formatting error or DIME size exceeds SOAP_MAXDIME-
SIZE
SOAP_DIME_HREF 33 DIME attachment has no href from SOAP body
SOAP_DIME_MISMATCH 34 DIME version/transmission error
SOAP_DIME_END 35 End of DIME attachments protocol error
SOAP_MIME_ERROR 36 MIME parsing error
SOAP_MIME_HREF 37 MIME attachment has no href from SOAP body error
SOAP_MIME_END 38 End of MIME attachments protocol error
SOAP_VERSIONMISMATCH 39 SOAP version mismatch or no SOAP message
SOAP_PLUGIN_ERROR 40 Failed to register plugin
SOAP_DATAENCODINGUNKN 41 SOAP 1.2 DataEncodingUnknown fault
OWN
SOAP_REQUIRED 42 Attributed required validation error
SOAP_PROHIBITED 43 Attributed prohibited validation error
SOAP_OCCURS 44 Element minOccurs/maxOccurs validation error
SOAP_LENGTH 45 Element length validation error
SOAP_PATTERN 46
SOAP_FD_EXCEEDED 47 Too many file descriptors / open sockets
SOAP_UTF_ERROR 48 Unicode Transformation Format text error
SOAP_NTLM_ERROR 49 NTLM proxy server authentication error
54
Appendix
Syslog error codes > http error codes
9.4.2 http error codes

Beside this SOAP errors there may occur some errors from the
lower http layer. Most of these error messages are not APS
internal - these are answers of the requested server:

200 OK
201 Created
202 Accepted
203 Non-Authoritative Information
204 No Content
205 Reset Content
206 Partial Content
300 Multiple Choices
301 Moved Permanently
302 Found
303 See Other
304 Not Modified
305 Use Proxy
307 Temporary Redirect
400 Bad Request
401 Unauthorized
402 Payment Required
403 Forbidden
404 Not Found
405 Method Not Allowed
406 Not Acceptable
407 Proxy Authentication Required
408 Request Time-out
409 Conflict
410 Gone
411 Length Required
412 Precondition Failed
413 Request Entity Too Large
414 Request-URI Too Large
415 Unsupported Media Type
416 Requested range not satisfiable
55
Appendix
Syslog error codes > http error codes

417 Expectation Failed
500 Internal Server Error
501 Not Implemented
502 Bad Gateway
503 Service Unavailable
504 Gateway Time-out
505 HTTP Version not supported
56
Support
10 Support
Service requests regarding the Advanced People Sensor and Push
Services via SOAP can be sent to the following e-mail address:
n people.counter.support@hella.com
The general contact information is provided on page 2.
57
Glossary and abbreviations
11 Glossary and abbreviations

APC Automatic People Counter
First generation people counter manufactured by the com-
pany Hella
APS Automatic People Semnsor
Second generation people sensor, successor of the APC
models
ASCII American Standard Code for Information Interchange
Coding for character sets
Availability Marks the first firmware version, which includes a feature or
attribute - newer versions include this feature or attribute too,
if not marked as deprecated
Base64 Binary-to-text encoding by translating it into a radix-64 repre-
sentation
BIKE Backend Integration Kit including Examples
Java example implementation of Push Services backend for
developers.
DNS Domain Name System
Resolves queries for FQDN names into IP addresses
FQDN Fully Qualified Domain Name
Address of a device or server using DNS instead of an IP
address
HAGL Hella Aglaia
Identification for IBIS protocol extensions developed by Hella
for the API message interface
HMI Human Machine Interface
Web-based configuration interface for the APS
HTTP Hypertext Transfer Protocol
Application protocol for data transmissions in networks.
HTTP is the basis for data communications in the World
Wide Web.
HTTPS Hypertext Transfer Protocol Secure
Application protocol for secure communication in networks,
with particularly wide deployment on the World Wide Web.
IIS Microsoft Internet Information Services
Web server application and set of feature extension modules
created by Microsoft for use with Microsoft Windows
IP address Internet Protocol address
Manually or dynamically assigned in the network
ISO 8601 International standard of representation of dates, times and
durations
JAR Java Archive
JAVA Trademark of Sun Microsystems, Inc.; object-oriented pro-
gramming language
JDK Java Development Kit
58
Glossary and abbreviations
JVM Java Virtual Machine

MAC address Media Access Control address
Unique hardware address of a network device
NAT Network Address Translation
Process of modifying IP address information during transit
across a traffic routing device
NTLM NT LAN Manager
Security protocol for authentification at http proxy
NTP Network Time Protocol
Protocol for the synchronization of time and date settings
between computer systems
OBU On-Board Unit
OSD Optical Self Diagnosis
Software function for checking the visual range
POM Project Object Model (Maven)
Push service Sending data from the APS to a data server (the connection
is established by the APS)
SOAP Simple Object Access Protocol
Network protocol for exchanging data between systems and
implementing remote procedure calls
TCP Transmission Control Protocol
One of the core data transfer protocols of the Internet Pro-
tocol suite and with ordered data transfer
UTC Universal Time Coordinated
Coordinated Universal Time (UTC) is the main time standard
by which the world regulates clocks and time.
Web service Method of communication between two electronic devices
over the web (Internet)
Wi-Fi or WiFi Wireless-Fidelity
Commercial name for wireless LAN (WLAN)
WLAN Wireless Local Area Network
Wireless network typical at 2.4 or 5 gigahertz radio bands.
WSDL Web Services Description Language
XML-based language that is used for describing the func-
tionality offered by a web service.
XML Extensible Markup Language
Defines a set of rules for encoding documents in a format
that is both human-readable and machine-readable. XML
has been employed as the base language for communica-
tion protocols.
XSD XML Schema Document
A document written in the XML schema language
59
Germany
59552 Lippstadt
Rixbecker Strasse 75
Hella KGaA Hueck & Co.
© 2017 Hella KGaA Hueck & Co., Lippstadt, HAGL-120-00076, 2017-03, SW 1.8

Aps Push Service Via Soap v1.8 en

Încărcat de

Informații document

Titlu original

Drepturi de autor

Formate disponibile

Partajați acest document

Partajați sau inserați document

Opțiuni de partajare

Vi se pare util acest document?

Este necorespunzător acest conținut?

Drepturi de autor:

Formate disponibile

Aps Push Service Via Soap v1.8 en

Încărcat de

Drepturi de autor:

Formate disponibile

Reference manual

Push Service via SOAP

HAGL-120-00076, 2017-03, SW 1.8

Hella Aglaia Mobile Vision GmbH

References Link/Name Description

Do not use the files of the example

Fig. 1: APS server communication via SOAP

Tasks Customizable tasks can be triggered once, at regular intervals or

Transport protocol The transport protocol is TCP/IP. The protocol is encapsulated in

3.2 Startup and standard tasks

3.3 Adding, deleting, and changing tasks

3.4 Buffering APS messages in case of network interruption

The maximum time for bridging a network interruption depends on

3.5 Persistent tasks beyond reboots

Preparing standard tasks

3.6 Request alive notifications

3.7 Requesting feature infos

3.8 Requesting all counting gates values

3.9 Requesting first counting gate values

3.10 Requesting all monitored zone values

3.11 Requesting a current object list

The prerequisite for the use of object lists is a license

3.12 Requesting a historic object list

The prerequisite for the use of object lists is a license

3.13 Requesting wireless tracking

The prerequisite for the use of wireless tracking is an

3.14 Requesting image snapshots

The size of the included images is not optimized and

3.15 Set date and time

This method is only to be used if no NTP server (Net-

3.16 Requesting a firmware update

The URL contains the protocol (e.g. http or ftp),

3.17 Requesting deletion of all Task

Use it in combination of new tasks in your task list to

3.18 Requesting deletion of all notifications

4 Task Messages and trigger

4.1 Time-based triggers

4.1.1 Date element

DATE_DONT_CARE date not relevant

If no date is specified or kind="DATE_DONT_CARE", a trigger is

For kind="DATE_DAY_OF_WEEK", an additional day_of_week

For kind="DATE_DAY_OF_MONTH", an additional

4.1.2 Start element

4.1.3 Cycle element

4.1.4 Random offset element

4.2 Event-based trigger

The event_trigger element contains exactly one element from

feature_changed_event fired if settings changed

4.2.1 Feature changed event

4.2.2 Count channels event

4.2.3 Count event

COUNT_EVENT_ALWAYS on any count event

4.2.4 Zone channels event

4.2.5 Current object list event

The prerequisite for the use of object lists is a license

4.2.6 Wireless tracking event

4.2.7 Optical self diagnosis event

4.2.8 One-time event

4.2.9 Startup event

5 Server answer messages

SOAP_SERVER_OK APS message pro-

All server_response_type values are used as acknoledge and

6 APS notification messages