Axis 2N Indoor Touch 2.0 User manual

www.2n.cz
2N Indoor Touch 2.0
®
API guide
Firmware: 4.2.2
Version: 4.2.2

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 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 (if enclosed) or our
website at www.2n.cz.
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.

2N TELEKOMUNIKACE a.s., www.2n.cz 3/94
Content:
1. Purpose of Document
2. HTTP API
3. WEB API
4. Supplementary Information

2N TELEKOMUNIKACE a.s., www.2n.cz 4/94
1. Purpose of Document
HTTP API 2N Indoor Touch 2.0
®provides third party applications a possibility to
configure and control selected system parts and the calling application.2N IP Mobile
®
Caution
The HTTP API service is licensed under the 91378395 2N Indoor Touch
.HTTP API license

2N TELEKOMUNIKACE a.s., www.2n.cz 5/94
2. HTTP API
2.1 Interface
2.1.1 Authentication
2.1.2 Requests
2.1.3 Responses to Requests
2.1.4 Cautions
2.2 Commands
2.2.1 Session Control
2.2.1.1 Login
2.2.1.2 Logout
2.2.2 GPIO
2.2.2.1 GPIO List Getting
2.2.2.2 GPIO Value Setting
2.2.3 2N® IP Mobile Control
2.2.3.1 Call Setup
2.2.3.2 Call Termination
2.2.3.3 Call State
2.2.3.4 2N IP Intercom List Getting
2.2.3.5 Change of Items in Added 2N IP Intercom List
2.2.3.6 2N® IP Mobile Minimization
2.2.3.7 2N® IP Mobile State Info
2.2.3.8 2N® IP Mobile Restart
2.2.4 System
2.2.4.1 System Info and Status
2.2.4.2 2N® Indoor Touch Restart

2N TELEKOMUNIKACE a.s., www.2n.cz 6/94
2.1 Interface
Communication is made via the HTTPS protocol, which runs on standardized port 443.
Authentication requires login and password data to be transmitted in the first
connection. Subsequently, the server returns the client a cookie with a session key for
further requests. Having failed to send more requests within a timeout (20 minutes at
present), the client will be logged out automatically. The next requests will thus return
the HTTP return code 401 (Not authorized). Then the client has to log in again.
2.1.1 Authentication
2.1.2 Requests
2.1.3 Responses to Requests
2.1.4 Cautions
2.1.1 Authentication
2N Indoor Touch 2.0
® supports the following two types of authentication:
Basic – Basic authentication is required according to . The service RFC 2617
requires a password, which, however, is sent in an open format.
Digest – Digest authentication is required according to .RFC 2617
2.1.2 Requests
The client-server communication is used. The client sends a data/command execution
request and the server sends a response. The request consists of URL and optional
data in the following format:
https://<IP>/api/v1/<subsystem>?<parameters>
IP is the device IP address
<subsystem> designates the system part to be controlled
<parameters> includes request details
For example:
https://192.168.254.228/api/v1/gpio?
action=set&name=io2&type=direction&value=out
means that the client wants to switch the GPIO pin to output in the GPIO subsystem.

2N TELEKOMUNIKACE a.s., www.2n.cz 7/94
If the data to be transferred is rather extensive, store the data in the JSON format in
the HTTP request body (Content-Type: application/json; charset=UTF-8).
Refer to the list of command parameters for these exceptions.
The HTTP method GET is used for the requests that do not transmit data. The PUT
method is used for the requests that include data.
2.1.3 Responses to Requests
A response to a request always includes JSON data in the following format:
{
"data": {
"success": true,
"array": [
{
"serial_number": "54-0562-0293"
}
]
}
}
Make sure that the cover-all container and the nested boolean are always data success
included. Success is always true if the command has been (or is expected to have
been) executed successfully. Nevertheless, it cannot be guaranteed for the time being
that the success=true value really means success for all commands. For example, there
may be no information on successful execution of the commands that 2N IP Mobile
®
resends to the 2N IP intercoms and so the value cannot be reported. Such commands
include the PUT method and the commands that do not return values: calls, opening
doors, etc. Thus, the user has to use another request (call/status, e.g.) to know the
command's success.
The false value is returned for many reasons. At present, the HTTP API cannot
distinguish errors and specific error messages will be implemented in the next versions
if necessary. The short list of potential errors is as follows:
Request entering error – invalid argument values, missing arguments, non-
existent subsystem, wrong JSON data format, incorrect HTTP method, etc.
A command is entered but the application is not running. 2N IP Mobile
®
Therefore, make sure that the application has been started before sending a 2N
®
command.IP Mobile
The container can include more items whose names and contents depend on the data
request to be sent. Our example includes an array of serial numbers.

2N TELEKOMUNIKACE a.s., www.2n.cz 8/94
2.1.4 Cautions
Currently, API is used for both providing data to the web interface (REST) and user
HTTP API requirements. Thus, the data that can be viewed and configured via the web
can be available in API despite not being documented.
API now supports just one web interface login at a time. Hence, if a web interface is
open and the user logs into another one, API will log the user out of the first one. This
will become obvious when the user enters another request via the web and is
forwarded to the login dialogue. This means that the web is used by another user and
data might be overwritten.
HTTP API has no such limitation. This means that more users may be authenticated,
but mutual data overwriting is not checked and has to be solved by the developer.

2N TELEKOMUNIKACE a.s., www.2n.cz 9/94
2.2 Commands
2.2.1 Session Control
2.2.2 GPIO
2.2.3 2N® IP Mobile Control
2.2.4 System
2.2.1 Session Control
2.2.1.1 Login
2.2.1.2 Logout
2.2.1.1 Login
The login helps you get access to the selected HTTPS session using a username and
password. The login is Admin by default and the password is identical with the device
web interface access password.
URL: https://<IP>/api/v1/login
HTTP method: PUT
Request body: {"login":"<username>","password":"<password>"}
Response code: 200 if everything is OK, otherwise 401, 405,...
Note
Response code 403 in the case of default password and its necessary change.
2.2.1.2 Logout
The logout helps you log out the currently logged-in session.
URL: http://<IP>/api/v1/logout
HTTP method: PUT
Response code: 200 if everything is OK, otherwise 401, 405,...
2.2.2 GPIO

2N TELEKOMUNIKACE a.s., www.2n.cz 10/94
2.2.2 GPIO
2.2.2.1 GPIO List Getting
2.2.2.2 GPIO Value Setting
2.2.2.1 GPIO List Getting
The list of GPIOs stored in the array container is returned. Name {in1, in2, out1, out2,
io1, io2, relay1, relay2} is the input identifier that is subsequently used for GPIO
identification in the HTTP API communication too. Direction takes the values {in, out,
io}.
URL: https://<IP> /api/v1/gpio
HTTP method: GET
Response code: Standard HTTP response code, treating syntactic errors

2N TELEKOMUNIKACE a.s., www.2n.cz 11/94
Response data:
{
"data": {
"pins": [
{
"id": 0,
"name": "In1",
"value": 1
},
{
"id": 1,
"name": "In2",
"value": 1
},
{
"id": 2,
"name": "Out1",
"value": -7
},
{
"id": 3,
"name": "Out2",
"value": -7
},
{
"id": 4,
"name": "IO1",
"value": 1
},
{
"id": 5,
"name": "IO2",
"value": 1
},
{
"id": 6,
"name": "Relay1",
"value": 0
},
{
"id": 7,
"name": "Relay2",
"value": 0
}
]
}
}

2N TELEKOMUNIKACE a.s., www.2n.cz 12/94
2.2.2.2 GPIO Value Setting
Set the output value, switchable IO direction or relay status change.
Parameters
Name – GPIO name, refer to 2.2.2.1 Getting List of GPIO Inputs and Outputs
– can be {0, 1}Value
Caution
The request body must include valid json with one GPIO at least.
URL: {{ip_addr}} https:// /api/v1/gpio
HTTP method: PATCH
Request body:
{
"pins": [
{
"name":
"In1",
"id": 0
,
"value"
: 1
},
{
"name":
"In2",
"id": 1
,
"value"
: 1
},
{
"name":
"Out1",
"id": 2
,
"value"
: -7
},
{

2N TELEKOMUNIKACE a.s., www.2n.cz 13/94
"name":
"Out2",
"id": 3
,
"value"
: -7
},
{
"name":
"IO1",
"id": 4
,
"value"
: 1
},
{
"name":
"IO2",
"id": 5
,
"value"
: 1
},
{
"name":
"Relay1",
"id": 6
,
"value"
: 0
},
{
"name":
"Relay2",
"id": 7
,
"value"
: 0
}
]
}
Response code:
Standard HTTP response.

2N TELEKOMUNIKACE a.s., www.2n.cz 14/94
Response data:
{
"data": {
"pins": [
{
"id": 0
,
"name":
"In1",
"value"
: 1
},
{
"id": 1
,
"name":
"In2",
"value"
: 1
},
{
"id": 2
,
"name":
"Out1",
"value"
: -7
},
{
"id": 3
,
"name":
"Out2",
"value"
: -7
},
{
"id": 4
,
"name":
"IO1",
"value"
: 1
},
{
"id": 5
,
"name":
"IO2",

2N TELEKOMUNIKACE a.s., www.2n.cz 15/94
"value"
: 1
},
{
"id": 6
,
"name":
"Relay1",
"value"
: 0
},
{
"id": 7
,
"name":
"Relay2",
"value"
: 0
}
]
}
}

2N TELEKOMUNIKACE a.s., www.2n.cz 16/94
2.2.3 2N® IP Mobile Control
2.2.3.1 Call Setup
2.2.3.2 Call Termination
2.2.3.3 Call State
2.2.3.4 2N IP Intercom List Getting
2.2.3.5 Change of Items in Added 2N IP Intercom List
2.2.3.6 2N® IP Mobile Minimization
2.2.3.7 2N® IP Mobile State Info
2.2.3.8 2N® IP Mobile Restart
2.2.3.1 Call Setup
Set up a call.
URL: {{ip_addr}} <sip_address>https:// /api/v1/hipm/call/dial?number=
HTTP method: PUT
Response code: Standard HTTP response code, treating syntactic errors.
Response data:
{
"data": {
"state": "Ringing"
}
}

2N TELEKOMUNIKACE a.s., www.2n.cz 17/94
2.2.3.2 Call Termination
Terminates the active call.
URL: {{ip_addr}} https:// /api/v1/hipm/call/hangup
HTTP method: PUT
Response code: Standard HTTP response code, treating syntactic errors.
Response data:
{
"data": {
"state": "IncomingReceived"
}
}
2.2.3.3 Call State
Get the current state of the call processing layer as one of the strings below:
{Idle, IncomingReceived, OutgoingInit, OutgoingProgress,
OutgoingRinging, OutgoingEarlyMedia, Connected, StreamsRunning,
Pausing, Paused, Resuming, Refered, Error, CallEnd, PausedByRemote,
UpdatedByRemote, IncomingEarlyMedia, Updating, Released,
EarlyUpdatedByRemote, EarlyUpdating}
Refer to for more information.http://www.linphone.org
URL: {{ip_addr}} https:// /api/v1/hipm/call
HTTP method: GET
Response code: Standard HTTP response code, treating syntactic errors.
Response data:
{
"data": {
"state": "Released"
}
}

2N TELEKOMUNIKACE a.s., www.2n.cz 18/94
2.2.3.4 2N IP Intercom List Getting
Get the list of the that are registered with and can be 2N IP intercoms 2N IP Mobile
®
displayed and edited in the device list.
NNURL: {{ip_addr}} https:// /api/v1/hipm/devices
HTTP method: GET
Response code: Standard HTTP response code, treating syntactic errors.
Response data:
{
"data": {
"devices": [
{
"id": 255,
"ip": "10.0.24.55",
"isActive": false,
"name": "2N IP Verso",
"serialNumber": "54-0776-
0059"
},
{
"id": 256,
"ip": "10.0.24.135",
"isActive": false,
"name": "2N IP Verso",
"serialNumber": "54-1921-
5022"
}
]
}
}
2.2.3.5 Change of Items in Added 2N IP Intercom List
Modify the list of added 2N IP intercoms.
Parameters
isActive – true or false
id – get the 2N IP intercom ID from the list, refer to 2.2.3.5 Getting List of Available 2N
IP Intercoms

2N TELEKOMUNIKACE a.s., www.2n.cz 19/94
URL: {{ip_addr}} https:// /api/v1/hipm/devices
HTTP method: PATCH
Request body:
{
"devices": [
{
"isActive": true,
"id": 255
}
]
}
Response code: Standard HTTP response code, treating syntactic errors.
Response data:
{
"data": {
"devices": [
{
"id": 255,
"isActive": true
}
]
}
}
2.2.3.6 2N® IP Mobile Minimization
Send the application to the background (displaying the 2N IP Mobile
®2N Indoor ®
launcher).Touch 2.0
URL: https://<IP>/ api/v1/hipm/minimize
HTTP method: PUT
Request body: N/A
Response code: Standard HTTP response code, treating syntactic errors.

2N TELEKOMUNIKACE a.s., www.2n.cz 20/94
2.2.3.7 2N® IP Mobile State Info
Returns the information that the application is running and capable of processing
communication.
URL: https://<IP>/ api/v1/hipm
HTTP method: GET
Request body: N/A
Response code: Standard HTTP response code, treating syntactic errors.
Response data:
{
"data": {
"isRunning": true
}
}
2.2.3.8 2N® IP Mobile Restart
Restart if running and start if not running.2N IP Mobile
®2N IP Mobile ®
URL: https://<IP>/api/ v1/hipm/reset
HTTP method: PUT
Request body: N/A
Response code: Standard HTTP response code, treating syntactic errors.
2.2.4 System
2.2.4.1 System Info and Status
2.2.4.2 2N® Indoor Touch Restart
2.2.4.1 System Info and Status
As this is a WEB API function, the success value is not included in the response.
Information on the system and its state is returned.