2N® Helios IP HTTP API
IP Intercom
Configuration Manual
Firmware |
2.8 |
|
Version |
2.8 |
www.2n.cz |
The 2N TELEKOMUNIKACE a.s. is a Czech manufacturer and supplier of telecommunications equipment.
The product family developed by 2N TELEKOMUNIKACE a.s. includes GSM gateways, private branch exchanges (PBX), and door and lift communicators. 2N TELEKOMUNIKACE a.s. has been ranked among the Czech top companies for years and represented a symbol of stability and prosperity on the telecommunications market for almost two decades. At present, we export our products into over 120 countries worldwide and have exclusive distributors on all continents.
2N® is a registered trademark of 2N TELEKOMUNIKACE a.s. Any product and/or other names mentioned herein are registered trademarks and/or trademarks or brands protected by law.
2N TELEKOMUNIKACE a.s. administers the FAQ database to help you quickly find information and to answer your questions about 2N products and services. On www.faq.2n.cz you can find information regarding products adjustment and instructions for optimum use and procedures „What to do if...“.
2N TELEKOMUNIKACE a.s. hereby declares that the 2N® Helios IP HTTP API product complies with all basic requirements and other relevant provisions of the 1999/5/EC directive. For the full wording of the Declaration of Conformity see the CD-ROM enclosed or our website at www.2n.cz.
This device complies with part 15 of the FCC Rules. Operation is subject to the following two conditions: (1) This device may not cause harmful interference, and (2) this device must accept any interference received, including interference that may cause undesired operation.
The 2N TELEKOMUNIKACE a.s. is the holder of the ISO 9001:2009 certificate. All development, production and distribution processes of the company are managed by this standard and guarantee a high quality, technical level and professional aspect of all our products.
Content |
|
1. Terms and Symbols . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . |
4 |
2. HTTP API General Description . . . . . . . . . . . . . . . . . . . . . . . |
5 |
3. Event Logging . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8
4. HTTP API Message List . . . . . . . . . . . . . . . . . . . . . . . . . . . . . |
12 |
5. Logged Events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . |
24 |
6. Format of Selected Parameters . . . . . . . . . . . . . . . . . . . . . . . 28
1. Terms and Symbols
The following symbols and pictograms are used in the manual:
Safety
Always abide by this information to prevent persons from injury.
Warning
Always abide by this information to prevent damage to the device.
Caution
Important information for system functionality.
Tip
Useful information for quick and efficient functionality.
Note
Routines or advice for efficient use of the device.
2N® TELEKOMUNIKACE a.s., www.2n.cz |
4 |
2. HTTP API General
Description
2N® Helios IP HTTP API (Application Programming Interface) is an interface designed for 2N® Helios IP remote control, configuration and data retrieval via third party
applications. 2N® Helios IP API enables 2N intercoms to be integrated in extensive user infrastructures (home automation, attendance control systems, etc.).
2N® Helios IP HTTP API provides a simple interface based on standard protocols (SOAP/HTTP), which helps read out state or statistic information.
2N® Helios IP HTTP API is defined through a web service available at:
http://helios_ip_address/automation - 2N® Helios IP control commands; 
http://helios_ip_address/notification - log data retrieval commands.
Send an HTTP request including a properly formatted SOAP/XML data to one of the
above mentioned addresses. 2N® Helios IP executes the requested operation and sends back a SOAP/XML response.
The general structure of the HTTP request is as follows:
2N® TELEKOMUNIKACE a.s., www.2n.cz |
5 |
POST /… HTTP/1.1
Host: …
Content-Type: application/soap+xml
Content-Length: …
<?xml version="1.0" encoding="utf-8"?>
<s:Envelope xmlns:s="http://schemas.xmlsoap.org/soap/envelope/">
<s:Header>
additional control information of request </s:Header>
<s:Body>
request parameters </s:Body>
</s:Envelope>
If the request is processed successfully, 2N® Helios IP sends the following HTTP response:
HTTP/1.1 200 OK
Content-Type: application/soap+xml
Content-Length: nnn
<?xml version="1.0" encoding="utf-8"?>
<s:Envelope xmlns:s="http://schemas.xmlsoap.org/soap/envelope/">
<s:Header>
additional control information of response </s:Header>
<s:Body>
Response parameters </s:Body>
</s:Envelope>
If the request cannot be processed or an error occurs during processing, 2N® Helios IP sends the 400 Bad Request reply including SOAP/XML data with error identification.
2N® TELEKOMUNIKACE a.s., www.2n.cz |
6 |
HTTP/1.1 400 Bad Request Content-Length: …
Content-Type: application/soap+xml <?xml version="1.0" encoding="UTF-8"?> <s:Envelope
xmlns:s="http://www.w3.org/2003/05/soap-envelope" xmlns:ter="http://www.onvif.org/ver10/error"> <s:Body>
<s:Fault>
<s:Code>
<s:Value> error code </s:Value> <s:Subcode>
<s:Value> error subcode </s:Value> </s:Subcode>
</s:Code>
<s:Reason>
<s:Text xml:lang="en"> error cause details </s:Text> </s:Reason>
<s:Detail>
<s:Text> additional error details </s:Text> </s:Detail>
</s:Fault>
</s:Body>
</s:Envelope>
2N® TELEKOMUNIKACE a.s., www.2n.cz |
7 |
3. Event Logging
2N® Helios IP implements an internal event log, which records events arising in the device – such as KeyPressed, CodeEntered, CardEntered, CallStateChanged and so on.
The log capacity is 500 events. When the log fills up, any new event deletes the oldest record. Events are arranged according to date and time (TimeStamp) in the log. The maximum time resolution is 1s. Also, each event is assigned a unique 16-bit RecordId, which is automatically incremented by 1s with every new event. The RecordId code helps distinguish between records of the same date and time.
The 2N® Helios IP event logs can be arranged in a table:
|
TimeStamp |
RecordID |
Event Type |
Event Data |
1 |
13/06/01 12:05:01 |
65533 |
CardEntered |
Card=… |
2 |
13/06/01 17:30:23 |
65534 |
CardEntered |
Card=… |
3 |
14/06/01 08:10:23 |
65535 |
KeyPressed |
Key=… |
4 |
14/06/01 08:10:23 |
0 |
KeyPressed |
Key=.. |
|
… |
… |
… |
… |
500 |
27/06/01 17:05:01 |
496 |
CardEntered |
Card=… |
The first table row represents the oldest record (log beginning). The last row represents the most recent record (log end). Being a 16-bit number, the RecordID automatically overflows from 65535 to 0.
2N® Helios IP defines several types of events to be logged.
Event |
Popis |
KeyPressed |
Keystroke |
CallStateChanged |
Call state change |
CodeEntered |
Numerical code entering |
CardEntered |
RFID card detection |
DeviceState |
Device state change |
The 2N® Helios IP event log readout is based on the WS-BaseNotification standard.
There are two 2N® Helios IP log event retrieval modes – Subscription and PullPoint
.
2N® TELEKOMUNIKACE a.s., www.2n.cz |
8 |
In the Subscription mode, 2N® Helios IP sends events to the subscriber in the form of Notify messages.
In the PullPoint mode, the client sends the GetMessages request to retrieve the log data.
Data Retrieval in Subscription Mode
To retrieve events from 2N® Helios IP in the Subscription mode, subscribe via the Subscribe command, specifying the type of events to be retrieved, the HTTP sending address and the subscription time.
If the subscription is successful, 2N® Helios IP sends the SubscribeResponse includi ng the Subscription Id for subsequent communication with 2N® Helios IP.
Now 2N® Helios IP starts sending Notify messages to the specified HTTP address. Events are sent at the moment of rise without delay. In your Subscribe request, you can specify the maximum count of events to be sent within one Notify message.
The subscription time is limited (as specified in the Subscribe request). When the subscription time expires, you will be unsubscribed automatically. To extend the
subscription time, send the Renew request before expiry. 2N® Helios IP will reply with the RenewResponse message.
Send the Unsubscribe request to unsubscribe explicitly. 2N® Helios IP will reply with the UnsubscribeResponse message.
If there is a firewall or NAT between you and 2N® Helios IP, the Subscription mode may not be convenient. The Notify messages are delivered only if the network elements are properly configured.
The figure below shows the status diagram and typical client - 2N® Helios IP message sequence.
2N® TELEKOMUNIKACE a.s., www.2n.cz |
9 |
Loading...