=============================
Network programming interface
=============================

A description of the available programming interfaces used to interact with network components.

.. _Network-Summary:

Summary
~~~~~~~

=========================== ========================== ===========
Chapter                     JSon URL                   HTTP Method     
=========================== ========================== ===========
:ref:`Network/Info`         /Network/Info.json          GET
:ref:`Network/Wifi`         /Network/Wifi.json          GET
:ref:`Network/Wifi/Connect` /Network/Wifi/Connect.json  POST
=========================== ========================== ===========

----------

.. _Network/Info:

Getting the network status
~~~~~~~~~~~~~~~~~~~~~~~~~~

=============== ====================
Key             Value JSon          
=============== ====================
Resource URL    /Network/Info.json  
HTTP Method     GET                 
Response format ``application/json``
=============== ====================

Description
^^^^^^^^^^^

This route sends back informations about :

    - Type of network link (ETHERNET or WIFI)
    - Type of IP mode method (DHCP or STATIC)
    - The MAC address of the current interface
    - The current IP address
    - The current IP netmask
    - The current IP gateway
    - The main DNS Server
    - The second DNS Server
    - The speed of the Wi-Fi link between the device and the remote access point
    - The SSID of the access point the stick is currently connected to
    - Statististics about exchanged data

Parameters
^^^^^^^^^^

None.

Expected response
^^^^^^^^^^^^^^^^^

========= ========== ======================== ==============================
HTTP Code Status     Object type              Description
========= ========== ======================== ==============================
200       ``Passed`` ``NetworkInfoContainer`` A set of network informations.
========= ========== ======================== ==============================

.. hidden-code-block:: json
  :linenos:
  :label: JSON Response Example (Open/Close)

  {
    "network": {
      "network_type": "WIFI",
      "link_speed": 72,
      "link_quality": 0,
      "connected_ssid": "AUDIO_WIFI_TEST",
      "ip_mode": "DHCP",
      "mac_address": "00:1B:A0:14:D3:66",
      "ip_address": "192.168.2.12",
      "ip_netmask": "255.255.255.0",
      "ip_gateway": "192.168.2.1",
      "ip_dns1": "192.168.2.1",
      "ip_dns2": "192.168.2.1"
    },
    "stats": {
      "total_rx_bytes": 270711904,
      "total_tx_bytes": 14542276
    },
    "id": "/Network/Info.json",
    "status": "passed",
    "response_code": 200
  }

|


----------

.. _Network/Wifi:

Retrieving the nearby Wi-Fi access points
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

=============== ====================
Key             Value JSON          
=============== ====================
Resource URL    /Network/Wifi.json            
HTTP Method     GET                            
Response format ``application/json``           
=============== ====================

Description
^^^^^^^^^^^

Returns a list of the access points the device has found around his current location. The ``AccessPointContainer`` is an object wrapping a list of ``AccessPoint`` and the result of the request. 

Parameters
^^^^^^^^^^

None.

Expected response
^^^^^^^^^^^^^^^^^

========= ========== ======================== ======================================
HTTP Code Status     Object type              Description
========= ========== ======================== ======================================
200       ``Passed`` ``AccessPointContainer`` A list of AccessPoints (can be empty).
========= ========== ======================== ======================================

.. hidden-code-block:: json
  :linenos:
  :label: JSON Response Example (Open/Close)

  {
    "ap_list": [{
        "bssid": "94:44:52:cc:2c:dc",
        "channel": "1",
        "raw_level": 100,
        "scaled_signal_level": 5,
        "capabilities_stringified": "[WPA2-PSK-CCMP][WPS]",
        "capabilities": ["WPA2-PSK", "WPS"],
        "ssid": "AUDIO_WIFI_TEST",
        "is_bound": false,
        "favorite": 0
      }, {
        "bssid": "00:1c:c5:07:e0:b0",
        "channel": "1",
        "raw_level": 39,
        "scaled_signal_level": 1,
        "capabilities_stringified": "[WEP]",
        "capabilities": ["WEP"],
        "ssid": "JTE_WIFI_TEST",
        "is_bound": true,
        "favorite": 1
      }],
    "id": "/Network/Wifi.json",
    "status": "passed",
    "response_code": 200
  }

----------

.. _Network/Wifi/Connect:

Connecting to a Wi-Fi AP
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

=============== ==========================
Key             Value JSon                
=============== ==========================
Resource URL    /Network/Wifi/Connect.json
HTTP Method     POST                      
Response format ``application/json``      
=============== ==========================

Description
^^^^^^^^^^^

Allows a client to connect the device to a nearby Wi-Fi access point given its SSID, BSSID, the right authentication method, its visibility and potential credentials. The response to this request is immediate and is sent back right after the request has been made, because the device's access point will be destroyed in order for it to get connected to the given access point.

Parameters
^^^^^^^^^^

= ========= ========= ========= =========== ================================================
# Name      Mandatory Data type HTTP Method Description
= ========= ========= ========= =========== ================================================
1 bssid     Yes       String    POST        The BSSID of the access point to connect to.
2 ssid      No        String    POST        The SSID of the access point to connect to.
3 hidden    Yes       Boolean   POST        Whether the network is hidden or not.
4 auth_type Yes       String    POST        Can be WEP, PSK or OPEN. Indicate PSK for either

                                            WPA-PSK or WPA2-PSK.
5 password  No        String    POST        The password associated to the access point.

                                            None if the authentication method is ``OPEN``.
= ========= ========= ========= =========== ================================================

Expected query (POST)
^^^^^^^^^^^^^^^^^^^^^

	-	``ssid=AUDIO_WIFI_TEST``
	- ``bssid=00:11:22:33:44:55``
	- ``hidden=false``
	- ``auth_type=PSK``
	- ``password=some_password``

Expected response
^^^^^^^^^^^^^^^^^

========= ========== ============================= ================================================
HTTP Code Status     Object type                   Description
========= ========== ============================= ================================================
200       ``Passed`` ``RequestSucceededContainer`` The given parameters were accepted, and a 
                                                   connection is pending.
========= ========== ============================= ================================================

.. hidden-code-block:: json
  :linenos:
  :label: JSON Response Example (Open/Close)

  {
    "id": "/Network/Wifi/Connect.json",
    "status": "passed",
    "return_code": 200
  }


|
|
|
