Controller Interface Description - mobimesh/GTDemo-2015 GitHub Wiki

Interface description of the controller (backend) component used by UE, LocationService and GUI.

  • Remark: This page contains some early ideas for the controller interface. It is far from being complete or fixed. Feel free to edit this page and add own ideas.

The controller component offers a RESTful interface which is available over the internet and over the local network.

This interface can be used by four other components:

  • UE --> Controller: UE registers itself and updates its context (status) e.g. display on/off or stream on/off.
  • Location Service --> Controller: The 3rd party location service can inject location information of registered UE.
  • GUI <-- Controller: The GUI can use this interface to pull the current system state e.g. the context of the UEs or the status of the access points.
  • Controller --> Network Manager: The Controller can interact with the data network infrastructure (e.g. access points) by making requests to the Network Manager.

User Equipment

Endpoints

Endpoint Method Description
/api/ue POST Registers user equipment in the system. Creates context of UE which can later be updated by a PUT request. Returns an URL (with ID) to access the context of this UE.
/api/ue GET Returns a list of URLs for all currently registered UE.
/api/ue/{id} GET Returns the complete context (status) of the UE specified by the ID argument.
/api/ue/{id} PUT Updates the context of a already registered UE.
/api/ue/{id} DELETE Removes a UE from the system and deletes its context.

Messages

POST /api/ue and PUT /api/ue/{id}

  • Request:
{  
   "device_id":"UE-UPB1",
   "display_state":1,
   "location_service_id":"node1",
   "position_x":0.0,
   "position_y":0.0,
   "rx_mobile_bytes":11148,
   "rx_mobile_bytes_per_second":0.0,
   "rx_total_bytes":83518207,
   "rx_total_bytes_per_second":130.82260131835938,
   "rx_wifi_bytes":83507059,
   "rx_wifi_bytes_per_second":130.82260131835938,
   "tx_mobile_bytes":2713,
   "tx_mobile_bytes_per_second":0.0,
   "tx_total_bytes":6908172,
   "tx_total_bytes_per_second":103.07235717773438,
   "tx_wifi_bytes":6905459,
   "tx_wifi_bytes_per_second":103.07235717773438,
   "active_application_activity":"com.google.android.apps.youtube.app.WatchWhileActivity",
   "active_application_package":"com.google.android.youtube",
   "wifi_mac":"00:11:22:33:44:55"
}

ATTENTION: This is always a full example of all data fields which can be send to the backend. However, only some of them are mandatory. The usage of these information also depends on the implementation of used management algorithm (e.g. the algorithm is triggered by active application vs. algorithm is triggered by display_state). A description of the fields is given at the bottom of this section.

  • Response (POST):
[
"/api/ue/9d7034c5008b11e4b714c8bcc8a0a80d"
]
  • Response (PUT): No data (HTTP Status: 204)

GET /api/ue

  • Response:
[
"/api/ue/9d7034c5008b11e4b714c8bcc8a0a80d",
"/api/ue/5e8e61d100fd11e4bfafc8bcc8a0a80d",
"/api/ue/57ae409e00fd11e4a3dec8bcc8a0a80d"
]

GET /api/ue/{id}

  • Response:
{  
   "active_application_activity":"com.google.android.apps.youtube.app.WatchWhileActivity",
   "active_application_package":"com.google.android.youtube",
   "assigned_accesspoint":"/api/accesspoint/3adacf6b222611e4b23ac8bcc8a0a80d",
   "device_id":"UE-UPB1",
   "display_state":1,
   "location_service_id":"node1",
   "position_x":0.0,
   "position_y":0.0,
   "registered_at":"Tue, 12 Aug 2014 15:40:51 -0000",
   "rx_mobile_bytes":11148,
   "rx_mobile_bytes_per_second":0.0,
   "rx_total_bytes":83518207,
   "rx_total_bytes_per_second":130.82260131835938,
   "rx_wifi_bytes":83507059,
   "rx_wifi_bytes_per_second":130.82260131835938,
   "tx_mobile_bytes":2713,
   "tx_mobile_bytes_per_second":0.0,
   "tx_total_bytes":6908172,
   "tx_total_bytes_per_second":103.07235717773438,
   "tx_wifi_bytes":6905459,
   "tx_wifi_bytes_per_second":103.07235717773438,
   "updated_at":"Tue, 12 Aug 2014 15:42:01 -0000",  
   "uri":"/api/ue/465e94fd222611e4a3fbc8bcc8a0a80d",
   "uuid":"465e94fd222611e4a3fbc8bcc8a0a80d",
   "wifi_mac":"00:11:22:33:44:55"
}

Fields

Field Type Mandatory
Optional
Response		 Description
device_id String m Name of the device. Can be used by GUI.
display_state Integer m Display on/off = 1/0
location_service_id String m Maps to the third party location service.
position_x Float o Current position. Can be set directly.
position_y Float o Current position. Can be set directly.
active_application_package String o Package name of the active application.
active_application_activity String o Activity name of the active application.
wifi_mac String m MAC address of Wifi interface.
*_*_bytes Integer o Bytes send/received per interface.
*_*_bytes_per_second Float o Bytes/s currently send/received per interface.
uuid String r Backend identifier.
uri URI r API address of this UE.
assigned_access_point URI r API address of the access point currently assigned to this UE (result of the management algorithm). Only in response.

Information like active application or send/received bytes is provides by the Android SDK and can be send by the monitoring application on the device.

3rd Party Location Service

We will use a 3rd party location service in the demo. So the location of a UE is not transmitted within context updates done by the UE. To make the integration of the location service easier an additional endpoint for location updates is provided. Each update contains an identifier, which is used to map locations to UEs. This endpoint can also be used to set the location of an access point.

Endpoint Method Description
/api/location POST Delivers new location data. The location is mapped to all UEs and APs which has the same location identifier.

Messages

POST /api/location

  • Request:
{
    "location_service_id": "node1",
    "position_x": 0,
    "position_y": 0
}
  • Response: No data (HTTP Status: 204)

Access Point Status

This interface also provides the current status of the access points which can be used for the demonstration GUI. UPDATE: Also includes network statistics of a the access point.

Endpoint Method Description
/api/accesspoint GET Returns a list (URLs) of attached access points.
/api/accesspoint/{id} GET Returns the current status of an access point.

Messages

GET /api/accesspoint

  • Response:
[
"/api/accesspoint/9d7034c5008b11e4b714c8bcc8a0a80d",
"/api/accesspoint/5e8e61d100fd11e4bfafc8bcc8a0a80d",
"/api/accesspoint/57ae409e00fd11e4a3dec8bcc8a0a80d"
]

GET /api/accesspoint/{id}

  • Response:
{
    "uuid": "fe36d68c0b4711e49019c8bcc8a0a80d",
    "uri": "/api/accesspoint/fe36d68c0b4711e49019c8bcc8a0a80d",
    "registered_at": "Mon, 14 Jul 2014 13:14:16 -0000",
    "position_x": 100.0,
    "position_y": 100.0,
    "location_service_id": "loc_ap1",
    "assigned_ue_list": [
        "/api/ue/fee4203a0b4711e4af87c8bcc8a0a80d",
        "/api/ue/fee74f4f0b4711e49673c8bcc8a0a80d",
        "/api/ue/fee8f42b0b4711e4adb8c8bcc8a0a80d"
    ],
    "power_state": 1,
    "device_id": "AP1",
    "ssid": "WLAN1",
    "bssid": "ff:ff:ff:ff:ff:ff",
    "rx_bytes":7625568,
    "tx_bytes":7428406,
    "rx_bytes_per_second":32105.68363463139,
    "tx_bytes_per_second":32561.994423266344
}

(for available power states see below)

Network manager

This interface provides access to the network infrastructure so that controller can issue real-time configuration commands to the access points.

This interface does not provide further WiFi information, like SSIDs. These information can be specified by the backend controller's configuration file.

Attention: All UUIDs are assumed to be fixed between system restarts, so that each physical AP can be identified (e.g. in configuration files).

Endpoint Method Description
/api/network/client/{mac} GET Return the current access point for the specified MAC address (not the enabled ones but the one which that MAC is associated to).
/api/network/client/{mac} PUT Changes the enabled access points for the specified MAC address. Attention: Changed POST to PUT fitting better to REST pattern.
/api/network/accesspoint GET Retrieves the access points list, grouped by usage availability.
/api/network/accesspoint/{uuid}/info GET Retrieves the access point info like name and serial number.
/api/network/accesspoint/{uuid}/stats GET Retrieves the access point statistics foreach active radio.
/api/network/accesspoint/{uuid}/power_state GET Retrieves the access point power state.
/api/network/accesspoint/{uuid}/power_state PUT Set the access point power state.

Messages

GET /api/network/client/{mac}

  • Response:
{
    "name": "open-space-2",
    "uuid": "c3b4a156913a37bf8e11e0bf756fcd9f"
}

NOTE 1: if the specified MAC address is not found on online devices no data is returned (HTTP Status: 204)

Messages

PUT /api/network/client/{mac}

  • Request:
{
    "enable_on": [
        "9d7034c5008b11e4b714c8bcc8a0a80d",
        "393464c5008b11e4b714c8bcc8a92637"
    ],
    "disable_on": [
        "1d7034c5008b11e4b714c8bcc8a0a803",
        "a93464c5008b11e4b714c8bcc8a92632"
    ]
}

NOTE 1: the Content-Type HTTP header must be set to application/json

NOTE 2: the device address {mac} must be urlencoded (for example aa:bb:cc:dd:ee:ff becomes aa%3Abb%3Acc%3Add%3Aee%3Aff

  • Response (PUT): No data (HTTP Status: 204)

GET /api/network/accesspoint

  • Response:
{
    "online": [
        "9d7034c5008b11e4b714c8bcc8a0a80d",
        "5e8e61d100fd11e4bfafc8bcc8a0a80d",
        "57ae409e00fd11e4a3dec8bcc8a0a80d"
    ],
    "offline": [
        "9d7034c5008b11e4b714c8bcc8a0a81d",
        "5e8e61d100fd11e4bfafc8bcc8a0a81d",
        "57ae409e00fd11e4a3dec8bcc8a0a81d"	
    ]
}
  • "Offline" access points are the ones not available for usage since can't be controlled by the Network Manager (i.e. not powered, not reachable, out of order, etc.)

GET /api/network/accesspoint/{uuid}/info

  • Response:
{
    "name": "open-space-2",
    "serial": "00156195a7c1",
    "uuid": "c3b4a156913a37bf8e11e0bf756fcd9f"
}

GET /api/network/accesspoint/{uuid}/stats

  • Response:
{
    "aps": [
        {
            "name": "vap0",
            "rxbyte": 18302973,
            "rxpkt": 18218,
            "timestamp": 1411980443,
            "txbyte": 18850563,
            "txpkt": 19392
        }
    ]
}
  • One entry foreach active radio (vap0, vap1, ..., vapX)

GET /api/network/accesspoint/{uuid}/power_state

  • Response:
{
    "power_state": "radio_on"
}
  • Planned power states: "radio_on", "radio_off"

PUT /api/network/accesspoint/{uuid}/power_state

  • Request:
{
   "power_state": "radio_on"
}

NOTE 1: the Content-Type HTTP header must be set to application/json

  • Response (PUT): No data (HTTP Status: 204)
⚠️ **GitHub.com Fallback** ⚠️