2N Indoor Touch User manual

www.2n.cz
Indoor Touch API
API guide
Version: 3.4.x

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/42
Content:
1. Upgrade
2. Purpose of Document
3. API
3.1 Architecture and Function
3.2 Hardware
3.3 API Functions
3.4 Installation
4. HTTP API
4.1 Interface
4.2 Commands
5. Supplementary Information
5.1 Directives, Laws and Regulation - General Instructions and Cautions

2N TELEKOMUNIKACE a.s., www.2n.cz 4/42
1. Upgrade
Date Version Changes
01/04/2015 1.0 First version
04/05/2015 1.1 Hardware section added
08/03/2016 2.0.x HTTP API section added

2N TELEKOMUNIKACE a.s., www.2n.cz 5/42
2. Purpose of Document
2N IndoorTouch
® is used for isolating the specific API (IA) 2N IndoorTouch ®
functionality and helps share it with third party applications or can be used by a
customer launcher.
2N IndoorTouch HTTP API (HA)
® 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 licence

2N TELEKOMUNIKACE a.s., www.2n.cz 6/42
3. API
3.1 Architecture and Function
3.2 Hardware
3.2.1 Inputs and Outputs
3.3 API Functions
3.3.1 LEDs
3.3.2 GPIO
3.3.3 System
3.3.4 Licence
3.3.5 Ethernet
3.4 Installation

2N TELEKOMUNIKACE a.s., www.2n.cz 7/42
3.1 Architecture and Function
2N IndoorTouch
® is based on a daemon written in C, which forms a layer above API
the OS Linux core. It periodically executes such necessary actions as network
configuration check, licence validity check, LED control, etc. and provides a function
interface via the C library. It communicates with the library via the Unix socket. This
library can be used by other C programs (for update and recovery modes, e.g.) too.
The library is also included in Android API, where a Java interface android.hardware.
IndoorTouch is created that makes it possible to call the library functions via the JNI.
The interface in Java is the android.hardware.IndoorTouch class.

2N TELEKOMUNIKACE a.s., www.2n.cz 8/42
3.2 Hardware
3.2.1 Inputs and Outputs
3.2.1 Inputs and Outputs
3.2.1.1 HW v4-00-00
3.2.1.1 HW v4-00-00
ID Mark Name Restriction
AIN0/1 ANALOG IN 1/2 Analogue Input 0–5 V DC 1,5 M Ω
GP_OUT1/2 OUTPUT 1/2 Digital Output Voh = 3,3 V DC 0,33 mA
GP_IN1/2 INPUT 1/2 Digital Input Vihmax = 5 V DC 100 k Ω
GP_IO1/2 IN (OUT) 1/2 Digital Input/Output Vihmax = 3,3 V DC
(100 serial resistor),Ω
Voh = 3,3 V DC
4 mA (100 serial resistor)Ω
Relay0/1 REL1/2 Relay contact data: max 30 V DC 2 A.
DC 12 V +/- IN = power input:
Vinmax = 12 V DC Imax = 1 A.
DC 12 V + OUT = power output:
Vout = 12 V DC Imax = 100 mA
 DC12V+ OUT + 12V output Imax = 300 mA
 DC12V+ IN + 12V input Imin = 1000 mA
 GND Ground 

2N TELEKOMUNIKACE a.s., www.2n.cz 9/42
3.3 API Functions
The API functions are encased in the Java class android.hardware.IndoorTouch. All the
methods are static and require no class instance. API is divided into:
3.3.1 LEDs
3.3.2 GPIO
3.3.3 System
3.3.4 Licence
3.3.5 Ethernet
3.3.1 LEDs
The LED notification interface has been designed both for GPIO and PWM LED
control. Notifications are executed by so-called effects. The effect is a vector of
brightness transitions for each defined LED colour with a defined transition time. With
GPIO LEDs, intensity is thresholded for the on/off value. The library contains some pre-
defined effects and the user can define additional effects of its own.
3.3.1.1 Effect Adding
3.3.1.2 Effect Removing
3.3.1.3 Effect Activation
3.3.1.4 Effect Deactivation
3.3.1.5 Effect Existence
3.3.1.6 Effect Enable
3.3.1.7 Display Backlight Notification
3.3.1.1 Effect Adding
int IndoorTouch.LedsAddEffect(String effectName, int continuity, String
transitions, int effectLedMask, int usedLedMask);
1. The argument specifies the effect name. If the effect exists, RC_ERR_EXIST is
returned.
2. The argument can have the following values:
LED_EFFECT_CONTINUITY_SINGLE, LED_EFFECT_CONTINUITY_REPEATING,
LED_EFFECT_CONTINUITY_KEEP. These values define what happens when the
transition vector ends. With SINGLE, the effect is terminated and removed from
the active effect database. With REPEATING, the effect starts from the
beginning again. With KEEP, the effect remains active displaying the last final
transition value.

2N TELEKOMUNIKACE a.s., www.2n.cz 10/42
3. Transitions means a string of transitions in the following format: <initial
brightness>,<target brightness>,<transition time in ms>, … . The count of
numbers in the string must be divisible by 3 and contain one transition at least.
4. Mask of used LEDs for the effect itself. These LEDs are affected by the
transition defined.
5. Mask of used LEDs. It contains all bits from the argument 4 mask plus others
in which the brightness value is 0. The other LEDs are not affected by the effect
and can use other effects that use a set of LEDs disjunctive with this effect. The
following LEDs are available for effects at present:
LED_RED = 0x01;
LED_GREEN = 0x02
LED_BLUE = 0x04;
LED_NFC = 0x08;
Example of effect definition for red LED blinking:
IndoorTouch.LedsAddEffect("test-r", LED_EFFECT_CONTINUITY_REPEATING,"0,2
55,1000,255,0,1000", LED_RED, LED_RED | LED_GREEN | LED_BLUE));
The library includes a pre-defined effect "red-blink-missedcalls“ for red blinking.
The return value is as follows:
IndoorTouch.RC_OK = 0;
IndoorTouch.RC_ERR_CONN = -1; API daemon connection error
IndoorTouch.RC_ERR_EXIST = -3; the effect name already exists
IndoorTouch.RC_ERR_INVALID = -5; invalid function arguments
IndoorTouch.RC_ERR_MAXREACHED = -10; maximum count of defined effects
exceeded
3.3.1.2 Effect Removing
int IndoorTouch.LedsRemoveEffect(String effectName);
Removes an effect from the list of defined effects. If the so-defined effect is active, it
is not affected by the call.
The return value is as follows:
IndoorTouch.RC_OK = 0;
IndoorTouch.RC_ERR_CONN = -1; API daemon connection error
IndoorTouch.RC_ERR_NOTEXIST = -4; the effect name does not exist
3.3.1.3 Effect Activation

2N TELEKOMUNIKACE a.s., www.2n.cz 11/42
3.3.1.3 Effect Activation
int LedsActivateEffect(String effectName, int priority);
Activates an effect with a pre-defined priority: LED_PRIORITY_INFO=10,
LED_PRIORITY_WARNING=20 or LED_PRIORITY_CRITICAL=30. A higher priority
overrides a lower one. This means that if an effect with a higher priority is activated
while an effect with a lower priority is active, the higher priority effect will be
preferred. If the lower priority effect still remains after the higher priority effect ends,
it will be activated again. Thus, the application does not have to be concerned with
sharing LEDs with other applications - effect activation with an adequate priority is
enough. By default, the blue LED backlight notification is activated automatically with
priority 9.
The return value is as follows:
IndoorTouch.RC_OK = 0;
IndoorTouch.RC_ERR_CONN = -1; API daemon connection error
IndoorTouch.RC_ERR_NOTEXIST = -4; the effect name does not exist
IndoorTouch.RC_ERR_DENIED = -7; notifications are disabled
IndoorTouch.RC_ERR_MAXREACHED = -10; maximum count of defined effects
exceeded
IndoorTouch.RC_ERR_PRIORITY = -11; an effect with the same LED mask and
identical priority has been started
3.3.1.4 Effect Deactivation
int IndoorTouch.LedsEffectDisable(String effectName);
Removes an active effect immediately. The LED brightness values remain on the level
that was valid at the time of effect removal. If a lower priority effect is active
controlling similar LEDs, the values will be reset immediately. As backlight notification
is active in the RGB LEDs by default, the value is reset to black or blue after
notification end.
The return value is as follows:
IndoorTouch.RC_OK = 0;
IndoorTouch.RC_ERR_CONN = -1; API daemon connection error
IndoorTouch.RC_ERR_NOTEXIST = -4; the effect name does not exist

2N TELEKOMUNIKACE a.s., www.2n.cz 12/42
3.3.1.5 Effect Existence
int IndoorTouch.LedsEffectExists(String effectName, int existence);
Returns the effect existence effectName in the selected existence database:
LED_EFFECT_EXISTENCE_ACTIVE: active effects
LED_EFFECT_EXISTENCE_DEFINED: defined effect vectors
The return value is as follows:
IndoorTouch.RC_OK = 0;
IndoorTouch.RC_ERR_CONN = -1; API daemon connection error
IndoorTouch.RC_ERR_NOTEXIST = -4; the effect name does not exist in the
selected database
3.3.1.6 Effect Enable
int IndoorTouch.LedsEffectsEnable(boolean enable);
Effects are enabled by default. If disabled, effect activation is ignored and all the
effects are switched off except for display backlight notification.
The return value is as follows:
IndoorTouch.RC_OK = 0;
IndoorTouch.RC_ERR_CONN = -1; API daemon connection error
3.3.1.7 Display Backlight Notification
int IndoorTouch.LedsEnableBacklightNotification(boolean enable);
If enabled, the blue LED is displayed when the display is switched off (switched into
the sleep mode).
The return value is as follows:
IndoorTouch.RC_OK = 0;
IndoorTouch.RC_ERR_CONN = -1; API daemon connection error

2N TELEKOMUNIKACE a.s., www.2n.cz 13/42
3.3.2 GPIO
3.3.2.1 GPIO Pin Reading
3.3.2.2 GPIO Pin Setting
3.3.2.3 GPIO Pin Locking
3.3.2.4 GPIO Pin Unlocking
3.3.2.5 Switchable GPIO Direction Getting
3.3.2.6 Switchable GPIO Direction Setting
3.3.2.7 Active Low Pin Value Setting
3.3.2.8 GPIO Input Value Change Detection
3.3.2.1 GPIO Pin Reading
int IndoorTouch.GPIOGet(int pin);
Reads the current GPIO register value. Pin is one of the options:
IndoorTouch.GPIO_PIN_IN1 = 0x01;
IndoorTouch.GPIO_PIN_IN2 = 0x02;
IndoorTouch.GPIO_PIN_OUT1 = 0x04;
IndoorTouch.GPIO_PIN_OUT2 = 0x08;
IndoorTouch.GPIO_PIN_IO1 = 0x10;
IndoorTouch.GPIO_PIN_IO2 = 0x20;
IndoorTouch.GPIO_PIN_RELAY1 = 0x40;
IndoorTouch.GPIO_PIN_RELAY2 = 0x80;
The return value is {0,1} or
IndoorTouch.RC_ERR_CONN = -1; API daemon connection error
IndoorTouch.RC_ERR_SYS = -6; system error (the value cannot be read, etc.)
IndoorTouch.RC_ERR_DENIED = -7; system error (GPIO does not exist)
3.3.2.2 GPIO Pin Setting
int IndoorTouch.GPIOSet(int pin, int value);
Pin is the PIN index, refer to , and value is {0,1}.3.3.2.1 GPIO Pin Reading
The return value is as follows:

2N TELEKOMUNIKACE a.s., www.2n.cz 14/42
IndoorTouch.RC_OK = 0;
IndoorTouch.RC_ERR_CONN = -1; API daemon connection error
IndoorTouch.RC_ERR_SYS = -6; system error (the value cannot be written, etc.)
IndoorTouch.RC_ERR_DENIED = -7; GPIO does not exist or is unwriteable
IndoorTouch.RC_ERR_LOCKED = -8; locked by another process via GPIOLock
3.3.2.3 GPIO Pin Locking
int IndoorTouch.GPIOLock(int pin);
Pin is the PIN index, refer to . Locks the PIN against use with 3.3.2.1 GPIO Pin Reading
the active process. Another process can read the value but the setting ends with
RC_ERR_LOCKED.
The return value is as follows:
IndoorTouch.RC_OK = 0;
IndoorTouch.RC_ERR_CONN = -1; API daemon connection error
IndoorTouch.RC_ERR_LOCKED = -8; already locked by another process via
GPIOLock
3.3.2.4 GPIO Pin Unlocking
int IndoorTouch.GPIOUnlock(int pin);
Pin is the PIN index, refer to . Unlocks the selected PIN that 3.3.2.1 GPIO Pin Reading
was locked via GPIOLock.
The return value is as follows:
IndoorTouch.RC_OK = 0;
IndoorTouch.RC_ERR_CONN = -1; API daemon connection error
IndoorTouch.RC_ERR_LOCKED = -8; already locked by another process via
GPIOLock
IndoorTouch.RC_ERR_NOTLOCKED = -9; PIN is not locked and need not be
unlocked

2N TELEKOMUNIKACE a.s., www.2n.cz 15/42
3.3.2.5 Switchable GPIO Direction Getting
int IndoorTouch.GPIOGetDirection(int pin);
Pin is the PIN index, refer to . GPIO_PIN_IO1 and 3.3.2.1 GPIO Pin Reading
GPIO_PIN_IO2 can be I/O switched. This command helps you get the currently set
direction. GPIO_DIRECTION_IN is set by default.
The return value is as follows:
IndoorTouch.GPIO_DIRECTION_IN = 1;
IndoorTouch.GPIO_DIRECTION_OUT = 2;
IndoorTouch.RC_ERR_CONN = -1; API daemon connection error
IndoorTouch.RC_ERR_SYS = -6; system error (the value cannot be read, etc.)
IndoorTouch.RC_ERR_DENIED = -7; GPIO does not exist or is unswitchable
3.3.2.6 Switchable GPIO Direction Setting
int IndoorTouch.GPIOSetDirection(int pin, int direction);
Sets the direction of the switchable GPIO PIN. Pin is the PIN index, refer to 3.3.2.1 GPIO
. This switch is valid until the next ICU restart or reconfiguration. The state Pin Reading
is not stored in the configuration.
Direction is one of the values:
IndoorTouch.GPIO_DIRECTION_IN = 1;
IndoorTouch.GPIO_DIRECTION_OUT = 2;
The return value is as follows:
IndoorTouch.RC_OK = 0;
IndoorTouch.RC_ERR_CONN = -1; API daemon connection error
IndoorTouch.RC_ERR_SYS = -6; system error (the value cannot be set, etc.)
IndoorTouch.RC_ERR_DENIED = -7; GPIO does not exist or is unswitchable

2N TELEKOMUNIKACE a.s., www.2n.cz 16/42
3.3.2.7 Active Low Pin Value Setting
int IndoorTouch.GPIOSetActiveLow(int pin, int value);
Pin is the PIN index, refer to , and value is {0,1}. Applicable for 3.3.2.1 GPIO Pin Reading
GPIO_PIN_IO1 and GPIO_PIN_IO2.
The return value is as follows:
IndoorTouch.RC_OK = 0;
IndoorTouch.RC_ERR_CONN = -1; API daemon connection error
IndoorTouch.RC_ERR_SYS = -6; system error (the value cannot be set, etc.)
IndoorTouch.RC_ERR_DENIED = -7; GPIO does not exist or is unswitchable
3.3.2.8 GPIO Input Value Change Detection
As the Java GUI interface is primarily controlled by messages and periodical reading
of GPIO inputs is complicated for programmers and speed-limiting due to high JNI
operational costs and delay caused by Java-daemon communication intervals, an
auxiliary nested static class is available for detection of IndoorTouch.GPIOWatcher
GPIO value changes. When its instance is created, starts a IndoorTouch.GPIOWatcher
thread, which periodically checks the GPIO input states and, having detected a
change, calls via Android Looper, i.e. public void OnGPIOChanged(int gpio, int value)
the content of this method is executed in the UI thread. Hence, to monitor the GPIO
state, the user creates a son of this class and overrides this method. Then the user
creates an instance of this class. Example:
class MyWatcher extends IndoorTouch.GPIOWatcher {
public MyWatcher(int mask) {
super(mask);
}
@Override
public void OnGPIOChanged(int gpio, int value) {
if (gpio == IndoorTouch.GPIO_PIN_IN1) {
// do the magic
}
}
}
protected IndoorTouch.GPIOWatcher mWatch = new MyWatcher( IndoorTouch.
GPIO_PIN_IN1 | IndoorTouch.GPIO_PIN_IN2);
GPIOWatcher has the following two constructors:
public GPIOWatcher(int watchMask)

2N TELEKOMUNIKACE a.s., www.2n.cz 17/42
public GPIOWatcher(int watchMask, int updateMs)
where watchMask is the GPIO pin bit array to be monitored and updateMs denotes the
interval in miliseconds between the GPIO input checks. The default value is 200.
3.3.3 System
Upon the module start up, the serial console is set to the transmission rate of 115200
bps. Telnet is enabled on the Ethernet interface on port 2323 by default, which can be
disabled by the launcher any time later.
3.3.3.1 CPU scaling
3.3.3.2 Display Uptime
3.3.3.3 Overheat detection
3.3.3.4 BootScreen Disable
3.3.3.5 Telnet
3.3.3.1 CPU scaling
The module periodically checks the display backlight. If the backlight is disabled and
CPU scaling enabled, the module reduces the CPU rate from 1 Ghz to 300 Mhz. Enable
/disable this functionality with the following command:
int IndoorTouch.SysEnableCPUDownscale(boolean enable);
Disable the function in the 'Display-Powersave CPU when display is off' menu in the
launcher.
The return value is as follows:
IndoorTouch.RC_OK = 0;
IndoorTouch.RC_ERR_CONN = -1; API daemon connection error
3.3.3.2 Display Uptime
The module periodically checks the display backlight. If the backlight is enabled, the
module counts the display backlight time in seconds, saving the value into the
EEPROM every two minutes (saving the count of write cycles). The value is intended
for technicians and can be obtained using the following Telnet command:
setpkey get hw_cfg.cfg.display_uptime (value in seconds).
To get the total IndoorTouch operation time enter the following command:

2N TELEKOMUNIKACE a.s., www.2n.cz 18/42
cat /proc/device_uptime (value in hours).
The function is always enabled and cannot be affected by the API.
3.3.3.3 Overheat detection
The overheat check is executed every 30 seconds. If the set temperature limit is
exceeded, the display will be swiched off (and the processor underclocked if CPU
scaling is enabled). There is a 5-seconds interval between overheat detection and
display switch-off, which allows the GUI to display a device overheat warning. Set the
display switch-off activation limit using the function below.
int IndoorTouch.SysSetMaxTemperature(float tempDeg);
where temperature in Celsius degrees is the argument. The GUI can get the current
temperature value using the following function:
float IndoorTouch.SysGetDeviceTemperature();
The result is a temperature value in Celsius degrees. The GUI can detect device
overheating by calling the following function periodically:
boolean IndoorTouch.SysIsOverheating();
3.3.3.4 BootScreen Disable
int IndoorTouch.SysDisableBootScreen();
The IndoorTouch launcher disables boot animation (a custom launcher must disable
animation to display the system).
3.3.3.5 Telnet
Telnet is enabled by the library upon start up by default. The launcher can disable it as
configured. Enable/disable Telnet as follows:
boolean IndoorTouch.SysEnableTelnet(boolean enable);

2N TELEKOMUNIKACE a.s., www.2n.cz 19/42
3.3.4 Licence
3.3.4.1 Licence Key Decoding
3.3.4.2 Product Key Getting
3.3.4.3 Serial Number Getting
3.3.4.4 Product Key Validity Detection
3.3.4.5 Product Key Setting
3.3.4.1 Licence Key Decoding
LicInfo IndoorTouch.LicUnpackProductKey(String productCode, String
serial);
ProductCode is a key with alphanumeric characters in the following format: XXXXX-
.XXXXX-XXXXX-XXXXX-XXXXX
Serial provides the serial number assigned to the product key in the following format:
.##-####-####
The function unpacks information into the IndoorTouch.LicInfo static class:
static public class LicInfo {
public boolean valid;
public int hours;
public int flags;
}
Valid defines that the licence key is valid for the selected serial number. Hours defines
the count of licensed hours: 0 means no hour limit. Flags denotes licence attributes: 1
means a possibility to install customer applications.
The function allows 10 calls in 5 seconds at most. Further 10 calls are allowed in the
next 5 seconds. When all the attempts are exhausted or a system error occurs, the
method returns .null
3.3.4.2 Product Key Getting
String IndoorTouch.LicGetProductKey();

2N TELEKOMUNIKACE a.s., www.2n.cz 20/42
3.3.4.3 Serial Number Getting
String IndoorTouch.LicGetSerialNumber();
3.3.4.4 Product Key Validity Detection
boolean IndoorTouch.LicIsCurrentLicenceValid();
3.3.4.5 Product Key Setting
boolean IndoorTouch.LicSetProductKey(String productKey);
The method sets the product key into the EEPROM. If the key is not 2N IndoorTouch
®
valid for the serial number or a system error occurs, the method 2N IndoorTouch
®
returns . Otherwise, is returned.false true
3.3.5 Ethernet
As Android JB basic version supports only DHCP Ethernet setting and there are no
such support and UI settings options in Android API, Ethernet will be configured via a
special interface until an official support is available or an own system support is
implemented.
3.3.5.1 Network Info Getting
3.3.5.2 DHCP Active Network Setting
3.3.5.3 Network Static Address Setting
3.3.5.4 Ethernet Interface Deactivation
3.3.5.1 Network Info Getting
NetInfo IndoorTouch.NetEthGetInfo();
The function returns the static class :IndoorTouch.NetInfo