The IMP Application Programming...

This content is the sole property of Icomera AB and is protected by international treaties. You are strictly prohibited from

making a copy or modifications of, or from redistribution, rebroadcasting or re-encoding this content without the prior written

permission from Icomera AB, except as may be permitted by law.

Icomera AB, Odinsgatan 28, SE 411 03 Göteborg, Sweden

Telephone +46 (0)31 799 21 00

© 2018 Icomera AB.

All Rights Reserved.

The IMP Application Programming Interfaces, from Kvaser 14.04.20 & Hod 15.3

Document number 02/6740-S-IMP 0001

Revision A

Date 2018-05-25

Internal, Commercial in Confidence

tel:+46%20(0)31%20799%2021%2000

02/6740-S-IMP 0001 (A)

2018-05-25

Page 2 of 37


Contents

1 Introduction ......................................................................................................... 3

2 XML ....................................................................................................................... 4

2.1 Position ......................................................................................................................................... 4

2.2 Users ............................................................................................................................................. 5

2.3 Connectivity .................................................................................................................................. 5

2.4 System ........................................................................................................................................... 7

3 JSONP .................................................................................................................. 8

3.1 Position ......................................................................................................................................... 8

3.2 User ............................................................................................................................................... 9

3.3 Users ........................................................................................................................................... 10

3.4 Connectivity ................................................................................................................................ 11

3.5 System ......................................................................................................................................... 12

4 SNMP .................................................................................................................. 13

4.1 System ......................................................................................................................................... 14

4.2 Connectivity ................................................................................................................................ 16

4.3 Positioning .................................................................................................................................. 19

4.4 Hotspot ....................................................................................................................................... 20

4.5 Network ...................................................................................................................................... 21

4.6 Configuration .............................................................................................................................. 21

4.7 Virtualization ............................................................................................................................... 22

5 Hotspot-cgi ........................................................................................................ 23

5.1 The Login Method ....................................................................................................................... 24

5.2 The Logout Method .................................................................................................................... 24

5.3 The Classcheck Method .............................................................................................................. 25

5.4 Examples ..................................................................................................................................... 25

5.5 Error Codes ................................................................................................................................. 26

6 Hotsoap .............................................................................................................. 27

6.1 Requests ..................................................................................................................................... 27

6.2 Responses ................................................................................................................................... 28

6.3 Definition Files and Examples ..................................................................................................... 29

6.3.1 The hotspot.xsd Definition File ............................................................................................ 29

6.3.2 Logon Examples ................................................................................................................... 31

6.3.3 Logoff Examples ................................................................................................................... 32

6.3.4 GetStatus Examples ............................................................................................................. 33

7 Contact Information .......................................................................................... 34

8 Acronyms, Terms and Definitions ................................................................... 35

9 Referenced Documentation .............................................................................. 37

02/6740-S-IMP 0001 (A)

2018-05-25

Page 3 of 37


1 Introduction

The Icomera Mobility Platform (IMP) is used as operating system on all Icomera X-series and Icomera

Connectware routers. Several Application Programming Interfaces (APIs) comes with the IMP, enabling

clients, web pages and applications access to information provided. Different APIs are suitable for

different areas of use.

The available API formats are:

XML

JSONP

SNMP

This document describes the different APIs, applicable on Kvaser 14.04.20 & Hod 15.3, or later and the

information provided, along where this is distributed.

For any questions, please contact Icomera, see section 7.

02/6740-S-IMP 0001 (A)

2018-05-25

Page 4 of 37


2 XML

The XML interface is the recommended API for applications. It can be used by any client authorised in

the Vantage settings API: Access list and API: HTTP. Foremost positioning, users and connectivity

data can be retrieved from the interface.

Code in web pages that need to access context information should use the IMP JSON API, see section 3.

The API should primarily be accessed via HTTPS, for a safety reason. HTTP can also be used, but is

not recommended.

There are XML APIs for the router in question, regarding:

Position, provided by the GPS receiver.

Users, information for Wi–Fi hotspot clients as a group, handled by the same system/router.

Connectivity, information about each WAN link currently used.

System, information about the router in question.

The following sections describe the different XML APIs.

2.1 Position

The position information follows NMEA 0183. It is provided by the GPS receiver in the router, thereby

the accuracy might vary between router models, see the Technical Product Description for each model.

The information is provided from ombord.info/api/xml/position/, as in the example below:

<position version="X.Y">

<time type="double">1505915599.0</time>

<age type="integer">0</age>

<latitude type="double">59.335796</latitude>

<longitude type="double">18.046434</longitude>

<altitude type="double">23.5</altitude>

<speed type="double">7.1</speed>

<cmg type="double">293.7</cmg>

<satellites type="integer">10</satellites>

<mode type="integer">2</mode>

</position>

Description of the parameters, all of the latest GPS reading:

time – the time since the Unix Epoch (seconds).

age – shows how old the position is (seconds). Time + age can be used by a third party application, for instance, to calculate the date and time.

latitude – latitude (decimal degrees).

longitude – longitude (decimal degrees).

altitude – the actual elevation above sea level (meters).

speed – speed (m/s).

cmg – course made good, the direction the vehicle travels (the angle from true north, decimal degrees).

satellites – the number of satellites the GPS reading is based upon.

mode – shows the GPS coverage (0 = no coverage, 1 = linear coverage (treated as 0), 2

= 2D coverage, 3 = 3D coverage).

When outside of GPS coverage, only age and mode are updated. The other values will freeze,

continuing to describe the last confirmed position.

02/6740-S-IMP 0001 (A)

2018-05-25

Page 5 of 37


2.2 Users

Users provides information for Wi–Fi hotspot clients as a group, handled by the system/router. The

information is provided from ombord.info/api/xml/users/, as in the example below:

<users version="X.Y">

<total type="integer">75</total>

<online type="integer">35</online>

</users>

Each parameter is described below:

total – the total number of current hotspot users.

online – the number of hotspot users who are currently authenticated to use the service.

2.3 Connectivity

Connectivity provides information about each WAN link currently used.

The information is provided from ombord.info/api/xml/connectivity/, as in the example below:

<connectivity version="X.Y">

<online type="integer">1</online>

<bundleid type="string">8570230981</bundleid>

<bundleip type="string">10.253.10.1</bundleip>

<links type="array">

<link>

<index type="integer">2</index>

<device_type type="string">ethernet</device_type>

<device_state type="string">up</device_state>

<link_state type="string">available</link_state>

<ethernet_info>

<ip type="string">172.28.3.147</ip>

<netmask type="string">255.255.252.0</netmask>

<mode type="string">dhcp</mode>

</ethernet_info>

</link>

<link>


<device_type type="string">wifi</device_type>



<wifi_info>

<ip type="string">172.28.2.161</ip>

<netmask type="string">255.255.252.0</netmask>

<mode type="string">static</mode>

<ssid type="string">Icomera</ssid>

<signalstrength type="string">-66 dBm</signalstrength>

<channel type="string">5.18 GHz</channel>

</wifi_info>

</link>

<link>


<device_type type="string">modem</device_type>

<device_subtype type="string"> MC7455</device_subtype>



<rssi type="integer">–59</rssi>

<technology type="string">dc-hspa+</technology>

<operator_id type="integer">24007</operator_id>

<apninfo type="string">internet.tele2.se,-1,-1</apninfo>

<umts_info>

<net_status type="integer">0</net_status> Deprecated <lac type="string">016E</lac>

<cellid type="string">B219AE82</cellid>

</umts_info>

</link>

<link>


<device_type type="string">modem</device_type>

<device_subtype type="string">MC7455</device_subtype>

02/6740-S-IMP 0001 (A)

2018-05-25

Page 6 of 37


<device_state type="string">down</device_state>

<link_state type="string">disconnected</link_state>

<rssi type="integer">–110</rssi>

<technology type="string">hspa+</technology>

<operator_id type="integer">0</operator_id>

<umts_info>

<net_status type="integer">2</net_status> Deprecated <lac type="string">016E</lac>

<cellid type="string">B219AE82</cellid>

</umts_info>

</link>

</links>

</connectivity>


online – the overall connectivity status of the system (0 = offline, 1 = online).

bundleid – the unique ID of the SureWAN gateway connection.

bundleip – the IP address of SureWAN the gateway connection.

The following parameters are provided for each WAN link that is used:

index – the link’s unique ID (the Interface ID defined in Vantage).

device_type – the type of device used for WAN connection (modem, wifi or ethernet).

device_subtype – the subtype, e.g. sierra–7430 for the SierraWireless MC7430 cellular

modem. For Wi-Fi the text will be unknown. The subtype is excluded, if not applicable.

device_state – the device status relative to a link end point, such as a wireless operator. Possible values are: up, down and unavailable.

link_state – the link status relative to the SureWAN gateway. Possible values are: available, disconnected and unavailable.

rssi – the Received Signal Strength Indicator, i.e. how strong the signal has been between the router and the cellular network (dBm). This is excluded if not applicable. The value is negative. The closer the value is to 0, the better the signal has been.

technology – the technology used by the device, such as lte, hspa and dc–hspa+. This

is excluded if not applicable.

operator_id – the identification number of the current base station operator as per the

standard MCC/MNC tuple, e.g. 24007 for Tele2. –1 if nothing was found, or the operator

is unknown. This is excluded if not applicable.

apninfo – Information regarding the APN the modem is using. It contains comma-separated values with the fields “APN”, ”username” and “password”. ”Username” and “password” is -

1 if they are blank.

The umts_info tag will be present, if the link is using a UMTS modem, or other member of the W–CDMA family of 3G technologies (HSPA, HSPA+, DC–HSPA+, etc.), or LTE. However, the values in umts_info can only be trusted when using a W-CDMA technology. The tag contains the following information:

net_status – Deprecated.

lac – the Location Area Code in hexadecimal, or unavailable if not found. This will be

inaccurate, or -1 when the LTE technology is used. The value 0000 is equal to -1. The

current value will be changed when the new version of the API is implemented.

cellid – the cell identifier of the currently used cell in hexadecimal, or unavailable if not

found. This will be correct for both the W-CDMA and LTE technology. The value 00000000

is equal to -1. Current value will be changed when the new version of the API is

implemented.

02/6740-S-IMP 0001 (A)

2018-05-25

Page 7 of 37


The ethernet_info tag is provided for Ethernet links, presenting:

ip – the ip address that the router is assigned by the connected Ethernet device.

netmask – the net mask that the router is assigned by the connected Ethernet device.

mode – the mode the Ethernet device is using. Possible values are dhcp and static.

The wifi_info tag provides additional information for Wi-Fi WAN links, including:

ip – the ip address that the router is assigned by the connected Wi-Fi device.

netmask – the net mask that the router is assigned by the connected Wi-Fi device.

mode – the mode the Wi-Fi device is using. Possible values are dhcp and static.

ssid – the SSID used when connecting with the Wi-Fi device.

signalstrength – the signal strength of the Wi-Fi connection (dBm).

channel – the channel used for the Wi-Fi connection (GHz).

2.4 System

System provides information about the router in question.

The information is provided from ombord.info/api/xml/system/, as in the example below:

<system version="X.Y">

<system_id type="integer">12345</system_id>

<system_name type="string">my-x6-router</system_name>

</system>


system_id – unique system identifier, which always remain the same, regardless if the system_name has been changed, or not.

system_name – the name given to the system in the IMS, Vantage. It is guaranteed to be escaped for the XML format, but might need to be escaped further in case it is intended to be inserted into HTML.

02/6740-S-IMP 0001 (A)

2018-05-25

Page 8 of 37


3 JSONP

The JavaScript Object Notification with Padding (JSONP) interface is intended to be used by on-board

web clients, authorised in the Vantage settings API: Access list, API: HTTP and API: JSONP.

JavaScript scripts cannot normally access resources on other sites than that from which it was loaded.

JSONP circumvents this limitation by using the fact that JavaScript scripts can be imported from arbitrary

sites.

The API should primarily be accessed via HTTPS, for a safety reason. HTTP can also be used, but is

not recommended.

There are JSONP APIs for:

Position, provided by the GPS receiver in each router.

User, session information for a specific Wi–Fi hotspot client on-board a vehicle.

Users, information for Wi–Fi hotspot clients as a group, handled by the same system/router.

Connectivity, information about each WAN link currently used.

System, information about the router in question.

The following sections describe the different JSONP APIs.

3.1 Position

The position information follows NMEA 0183. It is provided by the GPS receiver in the router, thereby

the accuracy might vary between router models, see the Technical Product Description for each model.

The information is provided from ombord.info/api/jsonp/position/?callback=function, as in the

example below:

function({

"version":"X.Y",

"time":"1903245111",

"age":"0",

"latitude":"52.175937",

"longitude":"-0.274707",

"altitude":"27.2",

"speed":"0.0",

"cmg":"0.0",

"satellites":"0",

"mode":"3"

});

The different parameters are described in section 2.1.

http://www.ombord.info/api/jsonp/position/?callback=function

02/6740-S-IMP 0001 (A)

2018-05-25

Page 9 of 37


3.2 User

User provides session information for a specific Wi–Fi hotspot client on-board a vehicle. It includes data

and time used from previous sessions on the same system within a server-configurable time period

(typically 24 hours). This is set for the RADIUS server, for each customer.

The information is provided from ombord.info/api/jsonp/user/?callback=function, as in the example

below:

function({

"version":"X.Y",

"ip":"10.101.1.111",

"mac":"F8:1E:DF:E7:6D:37",

"online":"2400", Deprecated "timeleft":"2400",

"authenticated":"1",

"userclass":"2",

"expires":"Tue Jul 16 14:15:02 2017",

"timeused":"1200",

"data_download_used":"20000000",

"data_upload_used":"10000000",

"data_total_used":"30000000",

"data_download_limit":"0",

"data_upload_limit":"0",

"data_total_limit":"180000000",

"bandwidth_download_limit":"0",

"bandwidth_upload_limit":"0",

"cap_level":"0"

});

Each parameter is described below. An asterisk after a parameter indicates that the parameter is only

set when the Wi–Fi user is authenticated using Icomera Hotspot. These parameters consider Service

level settings in the Icomera Management System (IMS) application Hotspot, see the document

“Icomera Hotspot X.X – User Manual”.

ip – the IP address of the Wi–Fi client.

mac – the MAC address of the client.

online – Deprecated. The same value as "timeleft". Use "authenticated" instead, to get the overall user status.

timeleft – time remaining before the user is de–authenticated (seconds, 0 = unlimited).

authenticated – whether the user is currently authorized to use the service, or not (0 = not

authenticated, 1 = authenticated).

userclass – passenger class of the client (class 2 by default, if no class is found).

expires* – a timestamp for when the session will expire (the string Never, or the time

formatted like DayType Month Date HH:MM:SS YYYY).

timeused* – the time a user has been authenticated with current privileges (seconds).

data_download_used* – data downloaded by the user during the current session (bytes).

Example:

A passenger logs in, uses 30 Mbyte of her 180 Mbyte limit, and 20 minutes of her 60-

minute limit, and then closes her computer to purchase a snack. After returning to her

seat, she might need to log in again. The used data will then start at 30 Mbyte, with

the old limit of 180 Mbyte and 20 minutes used. The user is shown as having 40

minutes left.


https://wiki.icomera.com/wiki/Icomera_Hotspot

02/6740-S-IMP 0001 (A)

2018-05-25

Page 10 of 37


data_upload_used* – data uploaded by the user during the current session (bytes).

data_total_used* – data transferred during the current session (bytes, the sum of downloads and uploads).

data_download_limit* – maximum data available for download by the user with the current privileges (bytes, 0 = unlimited).

data_upload_limit* – maximum data available for upload by the user with current privileges (bytes, 0 = unlimited).

data_total_limit* – maximum data available for transfer by the user with current privileges (bytes, 0 = unlimited).

bandwidth_download_limit* – a cap on download bandwidth with current privileges (bytes, 0 = unlimited).

bandwidth_upload_limit* – a cap on upload bandwidth with current privileges (bytes, 0 =

unlimited).

cap_level – indicates if the user has previously exceeded available resources (data/time limit). 0 = cap level not reached, 1 = "Throttled" cap level has been reached.

3.3 Users

Users provides information for Wi–Fi hotspot clients as a group, handled by the same system/router.

The information is provided from ombord.info/api/jsonp/users/?callback=function, as in the example

below:

function({

"version":"X.Y",

"total":"178",

"online":"102",

});



02/6740-S-IMP 0001 (A)

2018-05-25

Page 11 of 37


3.4 Connectivity

Connectivity provides information about each WAN link currently used.

The information is provided from ombord.info/api/jsonp/connectivity/?callback=function, as in the

example below:

function ({

"version":"X.Y",

"online":"1",

"bundleid":"84105099173",

"bundleip":"10.10.82.1",

"links":[

{

"index":"2",

"device_type":"ethernet",

"device_state":"up",

"link_state":"available",

"ethernet_info":{

"ip":"172.28.3.147",

"netmask":"255.255.252.0",

"mode":"dhcp"

}

},

{

"index":"10",

"device_type":"wifi",



"wifi_info":{

"ip":"172.28.2.161",

"netmask":"255.255.252.0",

"mode":"static",

"ssid":"Icomera",

"signalstrength":"-63 dBm",

"channel":"5.18 GHz"

}

},

{

"index":"103",

"device_type":"modem",

"device_subtype":"unavailable",

"device_state":"down",

"link_state":"disconnected",

"rssi":"-1",

"technology":"unknown",

"operator_id":"-1",

"apninfo":"-1,-1,-1",

"umts_info":{

"net_status":"-1",

"lac":"-1",

"cellid":"-1"

}

},

{

"index":"104",





"rssi":"-1",


"operator_id":"-1",

"apninfo":"-1,-1,-1",

"umts_info":{

"net_status":"-1",

"lac":"-1",

"cellid":"-1"


02/6740-S-IMP 0001 (A)

2018-05-25

Page 12 of 37


}

},

{

"index":"105",


"device_subtype":"MC7455",



"rssi":"-59",

"technology":"dc-hspa+",

"operator_id":"24007",

"apninfo":"internet.tele2.se,-1,-1",

"umts_info":{

"net_status":"2",

"lac":"004B",

"cellid":"004B575F"

}

},

{

"index":"106",





"rssi":"-1",


"operator_id":"-1",

"apninfo":"-1,-1,-1",

"umts_info":{

"net_status":"-1",

"lac":"-1",

"cellid":"-1"

}

}

]

});


3.5 System

System provides information about the router in question.

The information is provided from ombord.info/api/jsonp/system/?callback=function, as in the

example below:

function({

"version":"X.Y",

"system ":12345", Deprecated

"system_id":"12345",

"system_name":"my-x6-router"

});



02/6740-S-IMP 0001 (A)

2018-05-25

Page 13 of 37


4 SNMP

The IMP SNMP API refers to several SNMP MIBs (Management Information Base) installed on the IMP.

They are available for SNMP queries, but require authentication. Several standard SNMP MIBs are

used, see Table 1.

Table 1. Standard MIBs

Third-party SNMP MIBs Further information provided at

IF-MIB

Network traffic, type, address, MTU

etc. for all interfaces.

Note, that an Icomera patch update

some entries in the IF-MIB with the

correct interface name and index, to

better keep track of them. Thereby

the following error message might

appear:

error on subcontainer

'ifTable container' insert

(-1)

Please ignore this message.

http://www.net-snmp.org/docs/mibs/interfaces.html

http://www.net-snmp.org/docs/mibs/IF-MIB.txt

HOST-RESOURCES-MIB

System uptime, running processes. http://www.net-snmp.org/docs/mibs/host.html

http://www.net-snmp.org/docs/mibs/HOST-RESOURCES-MIB.txt

IP-MIB

Routes and similar.

http://www.net-snmp.org/docs/mibs/ip.html

http://www.net-snmp.org/docs/mibs/IP-MIB.txt

UCD-DISKIO-MIB

Permanent memory input/output,

i.e. SSD usage.

http://www.net-snmp.org/docs/mibs/ucdDiskIOMIB.html

http://www.net-snmp.org/docs/mibs/UCD-DISKIO-MIB.txt

SNMP-USER-BASED-SM-MIB http://www.net-snmp.org/docs/mibs/snmpUsmMIB.html

http://www.net-snmp.org/docs/mibs/SNMP-USER-BASED-SM-MIB.txt

The primary specification for the Icomera specific MIB is maintained as an SMI text file called

“ICOMERA-IMP-MIB”. There are SNMP OIDs for:

System, software and hardware related information about the router in question.

Connectivity, information about gateways, WAN links and modems with SIM cards currently used.

Positioning, information provided by the GPS receiver in each router.

Hotspot, session information and Hotspot settings (see the document “Icomera Hotspot X.X – User Manual”) for each Wi–Fi hotspot client on-board a vehicle.

Network, client network information.

https://wiki.icomera.com/wiki/SNMP

http://www.net-snmp.org/docs/mibs/interfaces.html

http://www.net-snmp.org/docs/mibs/IF-MIB.txt

http://www.net-snmp.org/docs/mibs/host.html

http://www.net-snmp.org/docs/mibs/HOST-RESOURCES-MIB.txt

http://www.net-snmp.org/docs/mibs/ip.html

http://www.net-snmp.org/docs/mibs/IP-MIB.txt

http://www.net-snmp.org/docs/mibs/ucdDiskIOMIB.html

http://www.net-snmp.org/docs/mibs/UCD-DISKIO-MIB.txt

http://www.net-snmp.org/docs/mibs/snmpUsmMIB.html



02/6740-S-IMP 0001 (A)

2018-05-25

Page 14 of 37


Configuration, presents the configuration database (settings, interfaces and interface settings made in Vantage1).

Virtualization, provides information of the IMP's virtual applications.

The description of the Icomera OID root starts with the numeric value ‘.1.3.6.1.4.1.10581’. For instance,

‘icomeraImpSystemName’ corresponds to ‘.1.3.6.1.4.1.10581.2.2.1’.

Contact Icomera for further information, see section 7. The following sections consist of a human-

readable overview of the Icomera specific MIB OIDs. In the different tables, entries in bold are branches,

not leaves. They will not contain any value readable by the Net-SNMP's snmpget utility. As with all

SNMP tables, addresses to entries in the tables are expanded with a final OID element identifying the

item of interest.

4.1 System

OID Name Definition Data Type

icomera.2.2 icomeraImpSystem Mainly read-only system

information.

icomera.2.2.1 icomeraImpSystemName By default, this is the string

"Icomera System". Settable to an

arbitrary string.

STRING

icomera.2.2.2 icomeraImpSystemHardwareVersion A placeholder string returns the

hardware version (e.g. "X3 1A").

Not specific to the system in any

way. Reserved for a succinct name

of the hardware type in a future

version.

STRING

icomera.2.2.3 icomeraImpSystemImageVersion Short form of the IMP version

designation, e.g. "14.04.0".

STRING

icomera.2.2.4 icomeraImpSystemAPIVersion The general IMP SNMP API

version, e.g. "1.4".

STRING

icomera.2.2.5 icomeraImpSystemVehicleId A unique system ID as read from

the IMS, System ID in Vantage.

STRING

icomera.2.2.6 icomeraImpSystemSecondsUntilPoweroff The number of seconds until the

IMP should be expected to shut

down. Intended to be read by

other systems, applications etc.

Will return -1 if no shutdown of the

IMP has been scheduled by any

service.

INTEGER

icomera.2.2.7 icomeraImpSystemDeviceName The individual name of the device. STRING

icomera.2.2.8 icomeraImpSystemId A unique identifier of the system

for configuration purposes. Not

hardware-dependent.

GAUGE32

(GAUGE32 is

an unsigned

32-bit integer,

required to

encompass

the range of

the data)

icomera.2.2.10 icomeraImpSysHwInfo Hardware-related system

information.

icomera.2.2.10.1 icomeraImpSysHwInfoPlatform The hardware platform of the

system, as designated by Icomera.

Example: "Icomera X3".

STRING

icomera.2.2.10.2 icomeraImpSysHwInfoTemp Temperature-related information.

1 Vantage is part of the Icomera Management Suite (IMS) and is used for configuration of the Icomera

Mobility Platform (IMP).

02/6740-S-IMP 0001 (A)

2018-05-25

Page 15 of 37


icomera.2.2.10.2.1 icomeraImpSysHwInfoTempCPU The temperature of the CPU in

whole °C, as determined by the

ACPI.

INTEGER

icomera.2.2.10.2.2.1 icomeraImpSysHwInfoTempLinkEntry The temperature of the modems.

icomera.2.2.10.2.2.1.1 icomeraImpSysHwInfoTempLinkEntryIndex The link ID used for this modem,

e.g. 103.

INTEGER

icomera.2.2.10.2.2.1.2 icomeraImpSysHwInfoTempLinkEntryValue The temperature of the modem, in

whole °C (degrees Celsius).

INTEGER

icomera.2.2.10.3 icomeraImpSysHwInfoStorage Storage device, e.g. SSD, related

information. New in API version 1.17.

icomera.2.2.10.3.1 icomeraImpSysHwInfoStorageDevicesList A space-separated list of storage

devices found on the system,

identified by storage device IDs.

STRING

icomera.2.2.10.3.2.1 icomeraImpSysHwInfoStorageDeviceEntry The information for a storage

device.

icomera.2.2.10.3.2.1.1 icomeraImpSysHwInfoStorageDevicesEntryID The ID of the storage device. INTEGER

icomera.2.2.10.3.2.1.2 icomeraImpSysHwInfoStorageDevicesEntry

Name

The full path to the device file, e.g.

"/dev/sda".

STRING


Model

The model number of the storage

device, e.g. “TS1TSSD420I”

STRING


SerialNumber

The serial number of the storage

device, e.g. “C334110052”.

STRING


FirmwareVersion

The firmware version, e.g.

“N1114B”.

STRING

icomera.2.2.11 icomeraImpSystemCriticalWatchdog 1, if the critical watchdog has

triggered.

0, if not.

Boolean

INTEGER

02/6740-S-IMP 0001 (A)

2018-05-25

Page 16 of 37


4.2 Connectivity


icomera.2.3 icomeraImpConnectivity

icomera.2.3.1 icomeraImpConnectivityAPIVersion The version of the connectivity section

of the API.

STRING

icomera.2.3.2 icomeraImpConnectivityIsOnline 1, if connected with

icomeraImpConnectivityMode,

0, if not connected.

Boolean

INTEGER

icomera.2.3.3 icomeraImpConnectivityIsOnlineWithZeroCostLink 1, if connected with Wi-Fi or LAN, else 0. Boolean

INTEGER

icomera.2.3.4 icomeraImpConnectivityIP The IP address of the SureWAN link.

New in API version 1.2.

STRING

icomera.2.3.5 icomeraImpConnectivityIPGatewayCount The number of configured SureWAN

gateways.

INTEGER

icomera.2.3.6 icomeraImpConnectivity Table with information on configured

gateways. As with all SNMP tables,

addresses to entries in this table are

expanded with a final OID element

identifying the item of interest.

icomera.2.3.6.1.1 icomeraImpConnectivityGatewayEntryIndex SNMP index. In the case of this specific

table, the index is an integer, 1 or 2.

1 corresponds to the primary SureWAN

server.

2 corresponds to an optional secondary

SureWAN server to be used as a fall-

back when the primary server has been

unreachable for a period of time.

INTEGER

icomera.2.3.6.1.2 icomeraImpConnectivityGatewayEntryHost IP address and port of the SureWAN

server.

STRING

icomera.2.3.6.1.3 icomeraImpConnectivityGatewayEntryLogin SureWAN login. STRING

icomera.2.3.6.1.4 icomeraImpConnectivityGatewayEntryPassword SureWAN password. STRING

icomera.2.3.6.1.5 icomeraImpConnectivityGatewayEntryIsConnected 1 if connected to this specific server.

0 if not connected.

Boolean

INTEGER

icomera.2.3.6.1.6 icomeraImpConnectivityGatewayEntryRoutingScheme The name of the routing scheme used

by this SureWAN server and the

system.

STRING

icomera.2.3.6.1.7 icomeraImpConnectivityGatewayEntryServer IP address of the SureWAN server. STRING

icomera.2.3.6.1.8 icomeraImpConnectivityGatewayEntryPort The port of the SureWAN server. INTEGER

icomera.2.3.7 icomeraImpConnectivityLinksCount Number of configured WAN links. INTEGER

icomera.2.3.8 icomeraImpConnectivityLinksList A space-separated list of the configured

WAN link IDs, e.g. "1 2 10 103 104 105

106" for 2 x LAN ("1 2"), 1 x Wi-Fi ("10")

and 4 x cellular modems in slots 3 to 6,

see Figure 1.

STRING

icomera.2.3.10 icomeraImpConnectivityLinks Information common to all types of con-

nected links in a table.

icomera.2.3.10.1.1 icomeraImpConnectivityLinkEntryID Table index. A WAN link ID, i.e. the in-

teger ID number of the link as used in

proprietary link management software.

Appropriate ID numbers can be

obtained from

icomeraImpConnectivityLinksList.

INTEGER

(1-256)

icomera.2.3.10.1.2 icomeraImpConnectivityLinkEntrySnmpIndex The SNMP ID of the link's network

interface. Can be used for lookups in

the IF-MIB section of the IMP SNMP

API. Will return -1 for WAN links

currently without network interfaces

identifiable to the SNMP service,

including disconnected modems.

INTEGER

icomera.2.3.10.1.3 icomeraImpConnectivityLinkEntryType Type of WAN link. Returns an upper-

case string, one of

"UMTS"/"ETHERNET"/"WIFI"/"CDMA".

STRING

02/6740-S-IMP 0001 (A)

2018-05-25

Page 17 of 37


icomera.2.3.10.1.4 icomeraImpConnectivityLinkEntryLatency The latency over the link, targeting a

server on the public Internet. Unframed

by the SureWAN gateway. Will return -

1 if the link cannot be tested.

INTEGER

icomera.2.3.10.1.5 icomeraImpConnectivityLinkEntryPriorityUp The TX (uplink) merit value for this link,

as determined by proprietary Icomera

software.

INTEGER

icomera.2.3.10.1.6 icomeraImpConnectivityLinkEntryPriorityDown The RX (downlink) merit value for this

link, as determined by proprietary

Icomera software.

INTEGER

icomera.2.3.10.1.7 icomeraImpConnectivityLinkEntryConnectedOp 1 if the link is connected to its Internet

Service Provider, 0 if it is not.

Boolean

INTEGER

icomera.2.3.10.1.8 icomeraImpConnectivityLinkEntryConnectedOpTime A UTC timestamp for when the modem

connected to its ISP. If the link is not

connected, this is the time the modem

disconnected. Formatted as

"YYYY-MM-DD HH:MM:SS".

STRING

icomera.2.3.10.1.9 icomeraImpConnectivityLinkEntryConnectedGw 1 if the link is connected to the

SureWAN gateway, 0 if it is not.

Boolean

INTEGER

icomera.2.3.10.1.10 icomeraImpConnectivityLinkEntryConnectedGwTime The time when the modem connected

to a SureWAN gateway. Formatted as

icomeraImpConnectivityLinkEntryIsCon

nectedOpTime, above.

STRING

icomera.2.3.10.1.11 icomeraImpConnectivityLinkEntryLastUpdate The time of the last link update, in UTC.

For cellular modems, this is the last time

that information was successfully read

from the modem. For other types of

links, it is the time of the last event, in

general link management. Formatted as

icomeraImpConnectivityLinkEntryIsCon

nectedOpTime, above.

STRING

icomera.2.3.11 icomeraImpConnectivityUmts The term "UMTS" refers to all cellular

modems.

icomera.2.3.11.1.1 icomeraImpConnectivityUmtsEntryLinkID WAN link ID. Identical to the link's index

in the icomeraImpConnectivityLinks

table.

INTEGER

(1-256)

icomera.2.3.11.1.2 icomeraImpConnectivityUmtsEntryIdentifier IMEI number. STRING

icomera.2.3.11.1.3 icomeraImpConnectivityUmtsEntrySubscription IMSI number. STRING

icomera.2.3.11.1.4 icomeraImpConnectivityUmtsEntryOperator Operator ID. INTEGER

icomera.2.3.11.1.5 icomeraImpConnectivityUmtsEntryApnInfo APN, login, and password for the

modem's connection to its operator.

Trying to set this value will fail and

should not be attempted.

STRING

icomera.2.3.11.1.6

icomeraImpConnectivityUmtsSimSlot The SIM slot currently used by the

modem. On X6 SIMEM, M4X and X3

routers, the response uses the format

<carrier type><carrier number>:<SIM

slot>.

- <carrier type> “MC” for mini SIM

carrier slots, or “SC” for nano-SIM

carriers.

- <carrier number> is 0 for “MC”, and

1 to 8 for “SC”. If the carrier number has

an “_unsup” suffix, contact Icomera, see

section 7.

- <SIM slot> is a number from 1 to 8.

Example, for an X6:

“MC0:2” is the SIM slot indicated in red,

in Figure 1.

“SC7:1” is the SIM slot 1 on the nano-

SIM carrier NSC1. This is the seventh

mini-PCIe card slot on the modem car-

rier board, counting the modem slots

first.

STRING

8

7

Bottom

1 3 5

2 4 6 Top

Cellular Modem Slots

3 4 5 6

Mini SIM Slots

4

1 3 Nano SIM Carrier Boards

NSC1 NSC2

SC7 SC8

SC6

SC6

Figure 1. The X6/X6i SIMEM router

Figure 2. The M4X router

Figure 4. The nano SIM carrier board slots Figure 3. The X3 router

NSC

NSC

02/6740-S-IMP 0001 (A)

2018-05-25

Page 18 of 37


icomera.2.3.11.1.7 icomeraImpConnectivityUmtsEntryHardwareInfo A name for the specific cellular modem,

e.g. "MC7304" for the Sierra Wireless

model MC7304. Will return -1 for any

link that has not connected since the

IMP booted.

STRING

icomera.2.3.11.1.8 icomeraImpConnectivityUmtsEntryTechnology Current technology reported by the link. STRING

icomera.2.3.11.1.9 icomeraImpConnectivityUmtsEntrySignal

Strength

Signal strength (RSSI) in dBm. INTEGER

icomera.2.3.11.1.10 icomeraImpConnectivityUmtsEntryLAC Current Location Area Code (LAC). STRING

icomera.2.3.11.1.11 icomeraImpConnectivityUmtsEntryCellID Currently connected cell ID. STRING

icomera.2.3.11.1.12 icomeraImpConnectivityUmtsEntryInfoAge The age in seconds since the last report

of information from the modem. In

normal operation, this does not exceed

6. If the value is higher than 6, or

[...]UmtsSimSlot has changed since the

last report, other information in this table

will not be reliable. For example, the

system may be attempting to connect

the modem with a new SIM, but will not

yet have read the IMSI of the new SIM.

New in API version 1.3.

INTEGER

icomera.2.3.11.1.13 icomeraImpConnectivityUmtsEntryOpName Operator name. STRING

icomera.2.3.11.1.14 icomeraImpConnectivityUmtsEntryICCID ICCID number. STRING

icomera.2.3.12 icomeraImpConnectivityEthernet Ethernet WAN links.

icomera.2.3.12.1.1 icomeraImpConnectivityEthernetEntryLinkId The WAN link ID. INTEGER

(1-256)

icomera.2.3.12.1.2 icomeraImpConnectivityEthernetEntryMode ”dhcp”, or ”static”. STRING

icomera.2.3.12.1.3 icomeraImpConnectivityEthernetEntryIp IP address of the link interface. STRING

icomera.2.3.12.1.4 icomeraImpConnectivityEthernetEntryNetmask Netmask for the network the link is

connected to.

STRING

icomera.2.3.13 icomeraImpConnectivityWifi Wi-Fi WAN links.

icomera.2.3.13.1.1 icomeraImpConnectivityWifiEntryLinkID The WAN link ID. INTEGER

(1-256)

icomera.2.3.13.1.2 icomeraImpConnectivityWifiEntryMode ”dhcp”, or ”static”. STRING

icomera.2.3.13.1.3 icomeraImpConnectivityWifiEntryIp IP address of the link. STRING

icomera.2.3.13.1.4 icomeraImpConnectivityWifiEntryNetmask Netmask for the network the link is

connected to.

STRING

icomera.2.3.13.1.5 icomeraImpConnectivityWifiEntrySSID The SSID this link is currently

connected to. Will return "off/any" when

disconnected.

STRING

icomera.2.3.13.1.6 icomeraImpConnectivityWifiEntryChannel The IEEE 802.11 channel frequency,

not channel ID, used by this Wi-Fi link.

0 if not connected, otherwise a string

like "2.437 GHz".

STRING

icomera.2.3.13.1.7 icomeraImpConnectivityWifiEntrySignalStrength The signal strength for this Wi-Fi link.

0 if not connected, otherwise a string

like "-38 dBm". Note that the unit is

included in the output, which is not the

case for cellular links.

STRING

icomera.2.3.20.1 icomeraImpConnectivityWwan

WWAN links. New in API version 1.17.

icomera.2.3.20.1.1.1 icomeraImpConnectivityWwanEntryLinkID The ID of the WWAN device, e.g.

“105”, for a cellular modem in slot 5.

INTEGER

icomera.2.3.20.1.1.2 icomeraImpConnectivityWwanEntryFirmware

Carrier

The name of the carrier provisioned

firmware image used for this modem,

e.g. “GENEU-4G.”

STRING

icomera.2.3.20.1.1.3 icomeraImpConnectivityWwanEntryFirmwarePri

Version

The version of the carrier provisioned

firmware image used for this modem,

e.g. “005.026”.

STRING


PkgVersion

The version of the firmware PKG, e.g.

“000”.

STRING

02/6740-S-IMP 0001 (A)

2018-05-25

Page 19 of 37



Revision

The version of the firmware used for

this modem, e.g.

“WI9X15C_05.05.58.00 r27038 carmd-

fwbuild1 2015/03/04 21:30:23”.

STRING

icomera.2.3.20.4 icomeraImpConnectivityWwanLte Cellular LTE links

icomera.2.3.20.4.1.1 icomeraImpConnectivityWwanLteEntryLinkID The link ID used for this modem. INTEGER

icomera.2.3.20.4.1.2 icomeraImpConnectivityWwanLteEntrySnr The SNR (Signal to Noise Ratio) value

of the link. This is a decimal value in dB,

presented as a string.

STRING

icomera.2.3.20.4.1.3 icomeraImpConnectivityWwanLteEntryRsrp The LTE RSRP (Reference Signal

Received Power) value for the modem

in dBm. RSRP is the average received

power of a single RS (Reference Signal)

resource element.

INTEGER

icomera.2.3.20.4.1.4 icomeraImpConnectivityWwanLteEntryRsrq The LTE RSRQ (Reference Signal

Received Quality) value for the modem

in dB. RSRQ = N x RSRP / RSSI, where

N is the number of PRBs (Physical

Resource Blocks) over which the RSSI

is measured, typically equal to system

bandwidth.

INTEGER

icomera.2.3.20.4.1.5 icomeraImpConnectivityWwanLteEntryLbw The LTE bandwidth used by the

modem. Usually measured in MHz.

STRING

icomera.2.3.20.4.1.6 icomeraImpConnectivityWwanLteEntryLband The LTE band used by the modem. INTEGER

icomera.2.3.20.4.1.7 icomeraImpConnectivityWwanLteEntryLtchan The LTE Tx (transmit) channel used by

the modem.

INTEGER

icomera.2.3.20.4.1.8 icomeraImpConnectivityWwanLteEntryLrchan The LTE Rx (receive) channel used by

the modem.

INTEGER

icomera.2.3.20.4.1.9 icomeraImpConnectivityWwanLteEntryTxpower The LTE Tx (transmit) power used by

the modem.

INTEGER

4.3 Positioning


icomera.2.4 icomeraImpPositioning GPS information.

icomera.2.4.1 icomeraImpPositioningAPIVersion The version of the positioning section of the API. STRING

icomera.2.4.2 icomeraImpPositioningLatitude Latitude (decimal degrees). STRING

icomera.2.4.3 icomeraImpPositioningLongitude Longitude (decimal degrees). STRING

icomera.2.4.4 icomeraImpPositioningAltitude The actual elevation above sea level (meters). STRING

icomera.2.4.5 icomeraImpPositioningSpeed Speed (m/s). STRING

icomera.2.4.6 icomeraImpPositioningCourse Direction of movement (the angle from true north,

decimal degrees).

STRING

icomera.2.4.7 icomeraImpPositioningSatellites The number of satellites upon which the last positional

estimate is based.

INTEGER

icomera.2.4.8 icomeraImpPositioningString A string with latitude, longitude, altitude, speed, course

and satellites. Comma-separated.

STRING

icomera.2.4.9 icomeraImpPositioningTime A timestamp for when the last useful GPS fix was

received. Expressed in seconds since the Unix Epoch.

Will return -1 if there has been no fix this boot.

INTEGER

icomera.2.4.10 icomeraImpPositioningAge The number of seconds since the last fix. INTEGER

icomera.2.4.11 icomeraImpPositioningMode The current level of GPS coverage.

0 = No coverage,

1 = Linear coverage (functionally equivalent to 0),

2 = 2D coverage,

3 = 3D coverage.

INTEGER

When outside of GPS coverage, only the age and mode will be updated. The other values will freeze,

continuing to describe the last known good position.

02/6740-S-IMP 0001 (A)

2018-05-25

Page 20 of 37


4.4 Hotspot


icomera.2.5 icomeraImpHotspot Hotspot information.

icomera.2.5.1 icomeraImpHotspotAPIVersion The version of the hotspot section of the API. STRING

icomera.2.5.2 icomeraImpHotspotStatus The status of the hotspot. 0 if not running, 1 if

running.

Boolean

INTEGER

icomera.2.5.3 icomeraImpHotspotAuthUserCount The number of authenticated users. INTEGER

icomera.2.5.4 icomeraImpHotspotUnauthUserCount The number of unauthenticated users. INTEGER

icomera.2.5.5 icomeraImpHotspotTotalUserCount The total number of users. INTEGER

icomera.2.5.6 icomeraImpHotspotAuthByIP Settable value. Set to an IP that should be

authenticated.

STRING

icomera.2.5.7 icomeraImpHotspotUnauthByIP Settable value. Set to an IP that should be de-

authenticated.

STRING

icomera.2.5.10 icomeraImpHotspotUsers A table of all current users.

icomera.2.5.10.1.1 icomeraImpHotspotUsersEntryID Table index. ID of the user. These are assigned in

order of association, starting at 1. The sequence

of user IDs can be sparse, since numbers are

unassigned when their users are no longer

associated.

INTEGER

icomera.2.5.10.1.2 icomeraImpHotspotUsersEntryIP The full IPv4 address of the user. STRING

icomera.2.5.10.1.3 icomeraImpHotspotUsersEntryMAC The MAC address of the user. STRING

icomera.2.5.10.1.4 icomeraImpHotspotUsersEntryStatus The status of the user, as a string:

"AUTHORIZED", or "UNAUTHORIZED".

STRING

icomera.2.5.10.1.5 icomeraImpHotspotUsersEntryMethod The authentication method: "Radius" (RADIUS),

or "None" (when not authenticated, or manually

authenticated).

STRING

icomera.2.5.10.1.6 icomeraImpHotspotUsersEntryTime A UTC clock time showing when the user's

state last changed. This is updated when the

user is first added, but also when attempting, or

succeeding to log in, and when being

authorized or denied. Example: "14:22:29".

STRING

icomera.2.5.10.1.7 icomeraImpHotspotUsersEntryRX Data downloaded by the user, in bytes, during

the current session only.

INTEGER

icomera.2.5.10.1.8 icomeraImpHotspotUsersEntryTX Data uploaded by the user, in bytes, during the

current session only.

INTEGER

icomera.2.5.10.1.9 icomeraImpHotspotUsersEntryClass Passenger class of user.

1 (first class), or 2 (second class).

INTEGER

icomera.2.5.10.1.10 icomeraImpHotspotUsersEntryAccessPoint

Address

The IP address of the access point the user is

associated with.

STRING

icomera.2.5.10.1.11 icomeraImpHotspotUsersEntryRXTotal Data received by the user in bytes. INTEGER

icomera.2.5.10.1.12 icomeraImpHotspotUsersEntryTXTotal Data transmitted by the user in bytes. INTEGER

icomera.2.5.10.1.13 icomeraImpHotspotUsersEntryTRXTotal Data transferred by the user in bytes. INTEGER

icomera.2.5.10.1.14 icomeraImpHotspotUsersEntryRXDataLimit The amount of data in bytes the user can

receive before being throttled.

INTEGER

icomera.2.5.10.1.15 icomeraImpHotspotUsersEntryTXDataLimit The amount of data in bytes the user can

transmit before being throttled.

INTEGER

icomera.2.5.10.1.16 icomeraImpHotspotUsersEntryTRXDataLimit The amount of data in bytes the user can

transfer before being throttled.

INTEGER

icomera.2.5.10.1.17 icomeraImpHotspotUsersEntryTimeLeft The amount of time in seconds remaining

before user is de-authenticated, or 0 if

unlimited.

INTEGER

icomera.2.5.10.1.18 icomeraImpHotspotUsersEntryTimeUsed The amount of time in seconds spent

authenticated.

INTEGER

icomera.2.5.10.1.19 icomeraImpHotspotUsersEntryTimeExpires The time at which the session will expire (e.g.

"Tue Jul 16 14:15:02 2013"), or the string

"Never".

STRING

icomera.2.5.10.1.20 icomeraImpHotspotUsersEntryString A comma-separated string containing the

following information (in that order) about a user:

expires, time left, time used, downloaded data,

download limit, download bandwidth, uploaded

data, upload limit, upload bandwidth, totalled

data, total limit, MAC, state, and cap level.

STRING

02/6740-S-IMP 0001 (A)

2018-05-25

Page 21 of 37


4.5 Network


icomera.2.6 icomeraImpNetwork RESERVED - Currently only used by

notifications.

icomera.2.6.1 icomeraImpNetworkClientInfo Client network information.

icomera.2.6.1.1 icomeraImpNetworkClientAccessPointESSID The ESSID of the access point the client

is associated with.

STRING

icomera.2.6.1.2 icomeraImpNetworkClientEvent Client access point event. STRING

icomera.2.6.1.3 icomeraImpNetworkClientMAC MAC address of client. STRING

icomera.2.6.2.1

icomeraImpNetworkFirewallChecksum A hash of all non-volatile firewall rules. A

rule is considered volatile

1) if it is added, or removed dynamically,

as part of normal operations and

2) if it is not directly derived from the con-

figuration.

Uses SHA-256 to generate the hash.

STRING

4.6 Configuration


icomera.2.11 icomeraImpConfig A presentation of the configuration database

based on Vantage settings.

icomera.2.11.1 icomeraImpConfigAPIVersion The version of the configuration section of the

API.

STRING

icomera.2.11.2 icomeraImpConfigAge The date and time of last modification of the

configuration database. Formatted like

"MMM DD HH:MM".

STRING

icomera.2.11.10.1 icomeraImpConfigSettingsTable The settings table of the configuration database.

icomera.2.11.10.1.1 icomeraImpConfigSettingsEntryIndex Table index. The row number of the setting in the

actual configuration table.

INTEGER

icomera.2.11.10.1.2 icomeraImpConfigSettingsEntryName The name of the setting. STRING

icomera.2.11.10.1.3 icomeraImpConfigSettingsEntryValue The value of the setting. STRING

icomera.2.11.11.1 icomeraImpConfigInterfacesTable The interfaces table of the configuration data-

base.

icomera.2.11.11.1.1 icomeraImpConfigInterfacesEntryIndex Table index. The row number of the setting in the


INTEGER

icomera.2.11.11.1.2 icomeraImpConfigInterfacesEntryId The WAN link ID or equivalent ID of the interface. INTEGER

icomera.2.11.11.1.3 icomeraImpConfigInterfacesEntryDevice The device name of the interface, e.g. 2-1,

wlan0, or eth1.

STRING

icomera.2.11.11.1.4 icomeraImpConfigInterfacesEntryName The name of the interface, e.g. PPP101, wifi0, or

eth1.

STRING

icomera.2.11.11.1.5 icomeraImpConfigInterfacesEntryType The type of the interface, e.g. radio, wlan, or

ethernet

STRING

icomera.2.11.11.1.6 icomeraImpConfigInterfacesEntryMode The mode of the interface, e.g. wan, slave, wan. STRING

icomera.2.11.12.1 icomeraImpConfigInterfaceSettingsTable The interface settings table of the configuration

database.

icomera.2.11.12.1.1 icomeraImpConfigInterfacesSettings Table index. The row number of the setting in the


INTEGER

icomera.2.11.12.1.2 icomeraImpConfigInterfacesSettings The unique identifier for a setting:

<linkid>,<option>, e.g. 10,ssid.

STRING

icomera.2.11.12.1.3 icomeraImpConfigInterfacesSettings The value of the setting, e.g. Icomera Wi-Fi. STRING

02/6740-S-IMP 0001 (A)

2018-05-25

Page 22 of 37


4.7 Virtualization


icomera.2.20 icomeraImpVirtualization Information on the IMP's virtual apps.

icomera.2.20.1 icomeraImpVirtualizationAPIVersion The version of the virtualization section of the API. STRING

icomera.2.20.10.1 icomeraImpVirtualizationTable A table containing general virtualization info. STRING

icomera.2.20.10.1.1 icomeraImpVirtualizationEntryIndex Index of the application. STRING

icomera.2.20.10.1.2 icomeraImpVirtualizationEntryName The name of the application. STRING

icomera.2.20.10.1.3 icomeraImpVirtualizationEntryUser The user that owns the application. STRING

icomera.2.20.10.1.4 icomeraImpVirtualizationEntryAutoStart Whether the application should be started on boot. STRING

icomera.2.20.10.1.5 icomeraImpVirtualizationEntryStatus The status of the application, obtained through

the VirtualBox showvminfo command.

STRING

icomera.2.20.10.1.6 icomeraImpVirtualizationEntryIP The IP of the application. STRING

02/6740-S-IMP 0001 (A)

2018-05-25

Page 23 of 37


5 Hotspot-cgi

Icomera’s hotspot-cgi package can be used when designing a logon portal/landing page, for instance

when it includes features that cannot be enabled by using Icomera’s web based editing application

SlotMachine. The hotspot-cgi package provides a web page for authenticating end users in Icomera

Hotspot, by means of a common gateway interface (CGI) program called hotspot.cgi. The end users

should be redirected to this web page after supplying their personal parameters, to authenticate with the

hotspotd service.

The webpage can be accessed through ‘https://”imp-address”/hotspot/hotspot.cgi’, where “imp-address”

is the IP-address, or hostname alias to the IMP (typically 10.101.0.1 and www.ombord.info). It supports

both GET and POST requests.

The Vantage interface settings/settings below are used by the hotspot-cgi package:

Hotspot free classes A list of passenger classes that will have free Internet access. Wi-Fi access points on board are associated with classes and users are associated with access points. When the standard hotspot web service is called with the class check method and the user's class is on this list, the user is logged in based on Captive portal username, Captive portal password and/or Captive portal realm interface settings. Users whose class cannot be identified are treated as belonging to class 0 for the purposes of this setting. External access points should be considered to represent different classes and have settings to provide this type of information. The Icomera routers also need additional software settings, not possible to do by using Vantage.

Captive portal URL The URL where unauthenticated users are directed to log on. It will default to http://vanilla.on.icomera.com if not set.

Hotspot: Access list A list of sites allowed to log in and out users to the Hotspot CGI (hotspot.cgi). This is usually the path to the captive portal. The information is typically sent to https://www.ombord.info/hotspot/hotspot.cgi. A blank setting (“”) means that all sites are allowed access, which is the default behaviour. Note that the sites should be entered as regular expressions. Enter ^deny$ if the Hotspot-cgi should be blocked, for instance if Hotsoap is used instead.

Hotspot debugging Should be set as true to enable a detailed output printed to the syslog. It is off by default.

See the document “Icomera Vantage X.X – User Manual” to get further information about the Vantage

interface settings/settings.



https://wiki.icomera.com/wiki/Hotspotd

http://vanilla.on.icomera.com/

02/6740-S-IMP 0001 (A)

2018-05-25

Page 24 of 37


5.1 The Login Method

The Login method logs in an end-user that supplies the correct parameters. The login call is made to

hotspotd, which either authenticates the user, or not. The login method page responds with the HTTP

redirect code 302, redirecting the user to different URLs depending on if the operation succeeded.

Supported parameters:

Name Description Required

method Should be set to login yes

url The URL to redirect the user to upon success. Defaults to

www.google.com.

no

onerror The URL to redirect the user to upon error. no

username1 The username to authenticate the user with. no

password The password to authenticate the user with. no

realm The realm (a service level defined in Hotspot, see the document

“Icomera Hotspot X.X – User Manual”) to authenticate the user with. Use

this with care, since this will be visible to the passenger. If the name

indicates specific privileges, for instance “2nd-class”, the user might try

with another realm to get improved surf conditions.

no

5.2 The Logout Method

The Logout method, can be used if the landing page has an integrated logout function. The user will

become unauthenticated, as soon as logging out and will thereafter get redirected to the captive portal,

when trying to access the Internet again. Thereby, the time allowance will not be wasted, while waiting

for the system to automatically noticing that the user has stopped using the service. This could otherwise

take up to 10 minutes.



method Should be set to logout yes


www.google.com.

no


1 It is important to ONLY use this method with personal accounts! Account details are visible to end-

users, and when used together with an account that is shared, the details can be used among all

systems using a hotspot system configured the same way.


https://en.wikipedia.org/wiki/HTTP

02/6740-S-IMP 0001 (A)

2018-05-25

Page 25 of 37


5.3 The Classcheck Method

The Classcheck method retrieves the class of the end-user that accesses the web page. Then the

configured free class list (see Hotspot free classes, in section 5) is checked towards the end-user's

class. If the end-user's class is in the free list, then an automatic login is performed (using the Captive

portal interface settings, see the document “Icomera Vantage X.X – User Manual”). The Classcheck

method page responds with the HTTP redirect code 302.



method Should be set to classcheck yes

redirecturl The URL to redirect the user to if the class is not in the free classes list. no


www.google.com.

no


5.4 Examples

https://www.ombord.info/hotspot/hotspot.cgi?method=login&url=www.icomera.com&onerror=http://vanill

a.on.icomera.com

A user, without any specific credentials, will be logged in with its MAC address by the IMP. The user is

redirected to:

http://www.icomera.com site, if the authentication succeeds

http://vanilla.on.icomera.com, if the authentication fails.

This is the most common procedure; The user just accepts the terms and conditions, without entering

any further information and thereafter begins to surf. Information about the user’s MAC address is

registered, to check that the user is within the defined service level. For instance, when a certain MAC

address has reached its maximum surf quota of 100 Mbyte, the MAC address will be throttled for 24

hours.

https://www.ombord.info/hotspot/hotspot.cgi?method=login&username=user&password=pass&realm=re

alm&url=www.icomera.com&onerror=http://vanilla.on.icomera.com

will try to authenticate those using the entered credentials, and redirect them to:

http://www.icomera.com, if the authentication succeeds

http://vanilla.on.icomera.com, if the authentication fails.

All users must have personal accounts, or a single-use ticket to access the Internet. Personal

information (username and password) must be entered, when accessing the logon portal.

https://www.ombord.info/hotspot/hotspot.cgi?method=classcheck&url=www.icomera.com&onerror=http:/

/vanilla.on.icomera.com&redirecturl=payment.icomera.com

will try to determine the class of the users and check the free classes list.

If the class is free, then the users are automatically authenticated using the credentials set by the configuration and redirected to http://www.icomera.com.

If the class is not free, then the user is redirected to http://payment.icomera.com. If an error occurs the user is redirected to http://vanilla.on.icomera.com.

https://en.wikipedia.org/wiki/HTTP



http://www.icomera.com/


https://www.ombord.info/hotspot/hotspot.cgi?method=login&username=user&password=pass&realm=realm&url=www.icomera.com&onerror=www.bing.com






https://www.ombord.info/hotspot/hotspot.cgi?method=classcheck&url=www.icomera.com&onerror=www.bing.com&redirecturl=payment.icomera.com




http://payment.icomera.com/


02/6740-S-IMP 0001 (A)

2018-05-25

Page 26 of 37


5.5 Error Codes

The hotspot.cgi webpage can return error codes, see Table 2, for different operations. These are

returned in a GET parameter called error to the site configured by onerror via a redirect.

Table 2. Error codes.

Code Name Description

1 RESPONSE_GENERAL_ERROR A general error. Usually means a bug in the code.

101 RESPONSE_NO_SUCH_METHOD Missing, or wrong method parameter provided.

102 RESPONSE_PARAMETER_VALIDATION

_ERROR Parameter validation failed. Missing a required

parameter for the request.

103 RESPONSE_MAC_REQUEST_ERROR The user is not part of the list maintained by hotspotd.

Same error as 301.

104 RESPONSE_IP_PARSE_ERROR The IP address is not allowed.

105 RESPONSE_HOTSPOT_DAEMON_SOC

KET_FAILURE No response from the hotspotd service.

106 RESPONSE_DATABASE_ERROR Database error.

108 RESPONSE_INTERFACE_REQUEST_E

RROR The user is not registered to an interface handled by the

hotspot daemon.

201 RESPONSE_GENERAL_AUTHENTICATI

ON_ERROR Unknown authentication error.

202 RESPONSE_UNKNOWN_USER The user is either not managed by the hotspot daemon,

or the account does not exist.

203 RESPONSE_NETWORK_ERROR A problem communicating with the RADIUS server.

208 RESPONSE_INSUFFICIENT_RIGHTS Can be returned when the user was rejected without a

more detailed reason, for instance, if the relevant

RADIUS server has run out of disk space.

214 RESPONSE_INVALID_REALM The realm (a service level defined in Hotspot) is not

allowed by the IMP.

301 RESPONSE_NO_ASSOCIATION_IP_MAC The user is not in the list maintained by hotspotd.

302 RESPONSE_LIMIT_REACHED A limit has been reached, that prevents the user from

logging in. Used when the exceeded limit is unknown.

303 RESPONSE_TIME_LIMIT_REACHED The time limit has been reached, preventing the user

from logging in.

304 RESPONSE_DOWNLOAD_LIMIT_REAC

HED The download limit has been reached, preventing the

user from logging in.

305 RESPONSE_UPLOAD_LIMIT_REACHED The upload limit has been reached, preventing the user

from logging in.

306 RESPONSE_TOTAL_BYTES_LIMIT_REA

CHED The total bytes limit has been reached, preventing the

user from logging in.

307 RESPONSE_PERMANENTLY_BLOCKED The user has been permanently blocked from the

service.

308 RESPONSE_PARSING_ERROR Unable to parse the reply message from the RADIUS

server.




02/6740-S-IMP 0001 (A)

2018-05-25

Page 27 of 37


6 Hotsoap

Hotsoap is used to authenticate users through a local web service on the IMP, when initiated by

connected units and applications on the servicenet, using port 6040, for instance on-board computers

and the Icomera media portal.

The hotsoap package provides a SOAP interface to hotspotd and is enabled by default.

6.1 Requests

The hotsoap web service is accessible using HTTP. For example, assuming that the IMP responds to

"www.ombord.info" and that the on-board computer is connected to it, the web service should handle

the URL http://www.ombord.info:6040/hotsoap.cgi.

The hotsoap web service can handle the SOAP requests described in the table below.

Request Parameter Description

Logon Requires ip, realm (a service level

defined in Hotspot, see the document

“Icomera Hotspot X.X – User Manual”),

useragent and language. username

and password are optional and can be

omitted, or empty.

Logs in an IP-address into the Hotspot,

using credentials for the provider set-up in

the Hotspot.

Logoff Requires ip. Logs out an IP-address from the Hotspot.

GetStatus Requires ip. Gets the status of a user, which includes

transmitted data, MAC-address, user state,

and a timestamp showing the time that the

user was altered in the Hotspot.

Allow Requires ip. allowTime can be used to

specify when the user should be logged

out (using seconds since epoch).

Allows an IP-address into the Hotspot,

without having to specify credentials. The

user will not be authenticated in RADIUS.

Thereby, nothing about the user will get

registered in neither RADIUS, nor Hotspot

and defined realms/service levels will be

disregarded. Also, there will be no surf

statistics. Therefore, it is not recommended

to use this SOAP request.

Deny Requires ip. Denies an IP-address from the Hotspot.

Currently this is the same as Logoff.

Further information can be found in section 6.3.

http://en.wikipedia.org/wiki/SOAP


http://www.ombord.info:6040/hotsoap.cgi

02/6740-S-IMP 0001 (A)

2018-05-25

Page 28 of 37


6.2 Responses

The content type of the HTTP response will be set to "text/xml", if the request was successfully parsed

and handled. The response is a valid SOAP document, containing an envelope, body and the result

within, which is usually stored as a string in the result tag. Further information can be found in the

hotspot.xsd example file, see section 6.3.

A failed operation will return "HTTP/1.0 500 Internal Server Error", which can happen if:

the parsing fails,

the request does not exist,

the communication with the Hotspot daemon does not work, or

some required parameter is not set.

The syslog on the system should contain more information about what went wrong.

The different methods and their responses are:

Allow, Deny, Logoff “Success”, or “Failure”

Logon “OK”, “WrongUsernameOrPassword”, “MissingUser”, or “ParameterValidationError”

GetStatus

timestamp Seconds since epoch

rxOctets Received bytes

txOctets Transmitted bytes

mac The user’s device MAC address

ip The user’s device IP address

state “Authenticated” or “Unauthenticated”

class The user’s class

Do also see the response examples in section 6.3.2-6.3.4

02/6740-S-IMP 0001 (A)

2018-05-25

Page 29 of 37


6.3 Definition Files and Examples

The following sections provide definition files, followed by examples, to give a better understanding of

the resulting Hotsoap requests and responses.

6.3.1 The hotspot.xsd Definition File

hotspot.xsd, see below, is an XML schema which shows the different requests and responses that the

hotsoap web service allows. It is accessible through http://www.ombord.info:6040/hotspot.xsd, from

units and applications on the servicenet, connected to the IMP.

<?xml version="1.0" encoding="UTF-8"?>

<schema targetNamespace="http://10.101.0.1:6040/hotspot.xsd"

xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"

xmlns:SOAP-ENC="http://schemas.xmlsoap.org/soap/encoding/"

xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"

xmlns:xsd="http://www.w3.org/2001/XMLSchema"

xmlns:hotspot="http://10.101.0.1:6040/hotspot.xsd"

xmlns="http://www.w3.org/2001/XMLSchema"

elementFormDefault="unqualified"

attributeFormDefault="unqualified">

<import namespace="http://schemas.xmlsoap.org/soap/encoding/"

schemaLocation="http://schemas.xmlsoap.org/soap/encoding/"/>



<element name="Logon">

<complexType>

<sequence>

<element name="ip" type="xsd:string" minOccurs="1" maxOccurs="1"/>

<element name="realm" type="xsd:string" minOccurs="1" maxOccurs="1"/>

<element name="username" type="xsd:string" minOccurs="1" maxOccurs="1"/>

<element name="password" type="xsd:string" minOccurs="1" maxOccurs="1"/>

<element name="useragent" type="xsd:string" minOccurs="1" maxOccurs="1"/>

<element name="language" type="xsd:string" minOccurs="1" maxOccurs="1"/>

</sequence>

</complexType>

</element>



<element name="LogonResponse">

<complexType>

<sequence>

<element name="result" type="hotspot:hotspot-LoginResult" minOccurs="1" maxOccurs="1"/>

</sequence>

</complexType>

</element>


<element name="Logoff">

<complexType>

<sequence>


</sequence>

</complexType>

</element>


<element name="LogoffResponse">

<complexType>

<sequence>

<element name="result" type="hotspot:hotspot-RequestResult" minOccurs="1" maxOccurs="1"/>

</sequence>

</complexType>

</element>


<element name="GetStatus">

<complexType>

<sequence>


</sequence>

</complexType>

</element>

http://www.ombord.info:6040/hotspot.xsd

02/6740-S-IMP 0001 (A)

2018-05-25

Page 30 of 37



<element name="hotspot-StatusResult">

<complexType>

<sequence>

<element name="timestamp" type="xsd:time" minOccurs="1" maxOccurs="1"/>

<element name="rxOctets" type="xsd:int" minOccurs="1" maxOccurs="1"/>

<element name="txOctets" type="xsd:int" minOccurs="1" maxOccurs="1"/>

<element name="mac" type="xsd:string" minOccurs="1" maxOccurs="1"/>


<element name="state" type="hotspot:hotspot-UserState" minOccurs="1" maxOccurs="1"/>

</sequence>

</complexType>

</element>


<element name="Allow">

<complexType>

<sequence>


<element name="allowtime" type="xsd:intt" minOccurs="0" maxOccurs="1"/>

</sequence>

</complexType>

</element>


<element name="AllowResponse">

<complexType>

<sequence>


</sequence>

</complexType>

</element>


<element name="Deny">

<complexType>

<sequence>


</sequence>

</complexType>

</element>


<element name="DenyResponse">

<complexType>

<sequence>


</sequence>

</complexType>

</element>

</schema>

02/6740-S-IMP 0001 (A)

2018-05-25

Page 31 of 37


6.3.2 Logon Examples

The request:


<SOAP-ENV:Envelope





xmlns:hotspot="http://10.101.0.1/hotspot.xsd">

<SOAP-ENV:Body>

<hotspot:Logon>

<ip>10.101.0.104</ip>

<realm>dev</realm>

<username>dev</username>

<password>dev</password>

<useragent>www</useragent>

<language>en</language>

</hotspot:Logon>

</SOAP-ENV:Body>

</SOAP-ENV:Envelope>

The response:


<SOAP-ENV:Envelope






<SOAP-ENV:Body>

<hotspot:LogonResponse>

<result>Success</result>

</hotspot:LogonResponse>

</SOAP-ENV:Body>


02/6740-S-IMP 0001 (A)

2018-05-25

Page 32 of 37


6.3.3 Logoff Examples

The request:


<SOAP-ENV:Envelope






<SOAP-ENV:Body>

<hotspot:Logoff>

<ip>10.101.0.104</ip>

</hotspot:Logoff>

</SOAP-ENV:Body>


The response:


<SOAP-ENV:Envelope






<SOAP-ENV:Body>

<hotspot:LogoffResponse>

<result>Success</result>

</hotspot:LogoffResponse>

</SOAP-ENV:Body>


02/6740-S-IMP 0001 (A)

2018-05-25

Page 33 of 37


6.3.4 GetStatus Examples

The request:


<SOAP-ENV:Envelope






<SOAP-ENV:Body>

<hotspot:GetStatus>

<ip>10.101.0.104</ip>

</hotspot:GetStatus>

</SOAP-ENV:Body>


The response:


<SOAP-ENV:Envelope






<SOAP-ENV:Body>

<hotspot-StatusResult>

<timestamp>1334137732</timestamp>

<rxOctets>1024</rxOctets>

<txOctets>254</txOctets>

<mac>00:00:00:00:00:00</mac>

<ip>10.101.0.104</ip>

<state>Authenticated</state>

<class>2</class>

</hotspot-StatusResult>

</SOAP-ENV:Body>


02/6740-S-IMP 0001 (A)

2018-05-25

Page 34 of 37


7 Contact Information

For common questions and questions related to hardware troubleshooting and faulty units, send an

email to [email protected].

The global Support Desk team, including out of hours/on–call, is manned 24/7/365.

The local phone numbers for contacting the global Support Desk are:

Sweden: +46 31 799 21 70

US: +1 24 0454 6885

UK: +44 208 028 0370

In emails concerning hardware troubleshooting and faulty units, include information about:

1. the customer contact information,

2. the name of the faulty unit (X6i, X3, or M4X router, for example),

3. the serial number,

4. actions that have been performed when troubleshooting,

5. remaining problems and their consequences,

6. if there are connected units to any of the LAN ports, which these units are and how they behave.

Within office hours, Icomera will reply within one hour.

Only authorized service centres are allowed to handle maintenance of and/or

repair the Icomera router. Improper handling can lead to loss of warranty.

mailto:[email protected]

02/6740-S-IMP 0001 (A)

2018-05-25

Page 35 of 37


8 Acronyms, Terms and Definitions

Acronym/term Definition

ACPI Advanced Configuration and Power Interface

An open standard to discover and configure hardware components, to

perform power management and status monitoring.

API Application Programming Interface

Describes the format of code that allows two software programs to

communicate with each other. Is used by developers when writing programs

that request services from an operating system (OS), or other application.

BS Base Station

BSSID Basic Service Set Identification

Used by administrators, in an ad hoc wireless network with no access points.

In this document it is used for the base station's system ID.

ESSID Extended Service Set Identification

The ESSID is used by administrator, in a wireless network that includes an

access point, but may still be referred to as SSID, see below.

hotspotd Provides a Hotspot for the local network

IMEI International Mobile Equipment Identity

A number, usually unique, to identify mobile phones. The IMEI can be used

for stopping a stolen phone from accessing a network. Can be found on the

phone.

IMSI International Mobile Subscriber Identity

A unique number associated with all Global System for Mobile

Communications (GSM) and Universal Mobile Telecommunications System

(UMTS) network mobile phone users used for identifying a GSM subscriber.

The IMSI is used in any mobile network that interconnects with other

networks. For GSM, UMTS and LTE network the number is provisioned in

the SIM card.

LAC Location Area Code

A unique number of the current location area. A location area is a set of base

stations grouped together.

RSSI Received Signal Strength Indicator

RSSI is an indication of the power level being received by the receive radio

after the antenna and possible cable loss.

SSID Service Set Identification

A case sensitive, 32 alphanumeric character unique identifier attached to the

header of packets sent over Wi-Fi. This identifier must often be entered into

devices manually by a human user, it is often a human-readable string and

thus commonly called the "network name". For the wireless devices in a

https://en.wikipedia.org/wiki/Mobile_phone

https://en.wikipedia.org/wiki/GSM

https://en.wikipedia.org/wiki/Universal_Mobile_Telecommunications_System

https://en.wikipedia.org/wiki/LTE_(telecommunication)

https://en.wikipedia.org/wiki/Subscriber_identity_module

02/6740-S-IMP 0001 (A)

2018-05-25

Page 36 of 37


network to communicate with each other, all devices must be configured with

the same SSID.

WWAN Wireless Wide Area Network

A telecommunications network, or a computer network that provides

regional, nationwide and global wireless coverage, for instance a cellular

network.

https://en.wikipedia.org/wiki/Telecommunications_network

https://en.wikipedia.org/wiki/Computer_network

02/6740-S-IMP 0001 (A)

2018-05-25

Page 37 of 37


9 Referenced Documentation

Icomera Vantage X.X – User Manual, document number 01/6730–S CMP 0004

Icomera Hotspot X.X – User Manual, document number 01/6730–S CMP 0005

The X.X above refers to the application version.

Document Revisions

Date Version Comment

2018-05-25 A Released

Date post:	04-Aug-2020
Category:	Documents
Upload:	others
View:	6 times
Download:	1 times

The IMP Application Programming...

Documents