736 lines
21 KiB
ReStructuredText
736 lines
21 KiB
ReStructuredText
Models & data types
|
|
===================
|
|
|
|
|
|
Introduction
|
|
~~~~~~~~~~~~
|
|
|
|
The ``WAPI`` takes requests as inputs and ouputs back an appropriate reponse to the client. As you may have seen, these response are formatted under the form of objects serialized in JSON. As it is sometimes hard to make all the response uniform, we wanted to keep a well stated logic in our way of responding to your requests by outputting well-documented objects for each type of responses.
|
|
|
|
This page will list every objects that we are using for responding to your requests. Every responses we are sending back extends a ``BasicResponseContainer`` object.
|
|
|
|
When reading about the layout of each type of responses, keep in mind that the layout depends on the object attributes. If an object's attribute can vary, we will only document its type, otherwise, we will document the exact value this attribute must take.
|
|
|
|
|
|
Models
|
|
~~~~~~
|
|
|
|
BasicResponseContainer
|
|
----------------------
|
|
|
|
Description:
|
|
^^^^^^^^^^^^
|
|
|
|
This is the object every other JSON object will be extending. This object basically contains every attributes a response needs to be correctly handled by the client.
|
|
|
|
Object layout:
|
|
^^^^^^^^^^^^^^
|
|
|
|
+---------------+------------+
|
|
| Field name | Data type |
|
|
+===============+============+
|
|
| id | String |
|
|
+---------------+------------+
|
|
| status | String |
|
|
+---------------+------------+
|
|
| response_code | Integer |
|
|
+---------------+------------+
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
RequestSucceededContainer *extends BasicResponseContainer*
|
|
----------------------------------------------------------
|
|
|
|
Description:
|
|
^^^^^^^^^^^^
|
|
This response is sent back when the request went well. This is a generic container stating that everything is OK.
|
|
|
|
Object layout:
|
|
^^^^^^^^^^^^^^
|
|
|
|
.. code-block:: json
|
|
|
|
{
|
|
"id": "/xxx/yy.json",
|
|
"status": "passed",
|
|
"response_code": 200
|
|
}
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
LocaleContainer *extends RequestSucceededContainer*
|
|
---------------------------------------------------
|
|
|
|
Description:
|
|
^^^^^^^^^^^^
|
|
|
|
Holds informations about the device available locales, as well as the currently active locale.
|
|
|
|
Object layout:
|
|
^^^^^^^^^^^^^^
|
|
|
|
+------------------+------------+
|
|
| Field name | Data type |
|
|
+==================+============+
|
|
| current_locale | object |
|
|
+------------------+------------+
|
|
| available_locale | Array |
|
|
+------------------+------------+
|
|
|
|
The ``available_locale`` attribute is an array of ``Locale`` objects. The layout of a ``Locale`` object is described as follow :
|
|
|
|
+------------------+------------+
|
|
| Field name | Data type |
|
|
+==================+============+
|
|
| iso3_language | String |
|
|
+------------------+------------+
|
|
| iso3_country | String |
|
|
+------------------+------------+
|
|
| display_name | String |
|
|
+------------------+------------+
|
|
| display_language | String |
|
|
+------------------+------------+
|
|
| country | String |
|
|
+------------------+------------+
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
AlarmConfigContainer
|
|
--------------------
|
|
|
|
Description:
|
|
^^^^^^^^^^^^
|
|
|
|
Holds informations about the device alarm configuration.
|
|
|
|
Object layout:
|
|
^^^^^^^^^^^^^^
|
|
|
|
The ``AlarmConfigContainer`` is an array of ``alarms`` objects. The layout of a ``alarms`` object is described as follow :
|
|
|
|
+-----+--------------------+-------------+-----------+
|
|
| # | Field Name | Mandatory | Data type |
|
|
+=====+====================+=============+===========+
|
|
| 1 | id | Yes | Integer |
|
|
+-----+--------------------+-------------+-----------+
|
|
| 2 | state | No | String |
|
|
+-----+--------------------+-------------+-----------+
|
|
| 3 | source_type | No | String |
|
|
+-----+--------------------+-------------+-----------+
|
|
| 4 | source | No | String |
|
|
+-----+--------------------+-------------+-----------+
|
|
| 5 | frequency | No | Array |
|
|
+-----+--------------------+-------------+-----------+
|
|
| 6 | volume_mode | No | String |
|
|
+-----+--------------------+-------------+-----------+
|
|
| 7 | volume | No | Integer |
|
|
+-----+--------------------+-------------+-----------+
|
|
| 9 | time | No | String |
|
|
+-----+--------------------+-------------+-----------+
|
|
|
|
|
|
The ``alarms`` object contains the following attributes :
|
|
|
|
:id: Alarm id value starting at index ''0''
|
|
|
|
:state: Alarm state can be ''on'' or ''off''
|
|
|
|
:source_type: Alarm source_type can be ''default_tone'' or ''preset''
|
|
|
|
:source: Alarm source can be a preset number (starting at index 1) if source_type = preset
|
|
|
|
:frequency: Alarm frequency can be ''0'' (once), ''1'' (monday), ''2'' (tuesday), ''4'' (wednesday), , ''8'' (thursday), ''16'' (friday), ''32'' (saturday), ''64'' (sunday)
|
|
|
|
:volume_mode: Alarm volume_mode can be ''specific'' or ''incremental''
|
|
|
|
:volume: Alarm specific volume value or the maximum incremental volume value
|
|
|
|
:time: Alarm time value in the form "HH:MM"
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
AlarmPresetContainer
|
|
--------------------
|
|
|
|
Description:
|
|
^^^^^^^^^^^^
|
|
|
|
Holds informations about the available device alarm presets.
|
|
|
|
Object layout:
|
|
^^^^^^^^^^^^^^
|
|
|
|
The ``AlarmPresetContainer`` is an array of ``alarm_presets`` objects. The layout of a ``alarm_presets`` object is described as follow :
|
|
|
|
+-----+--------------------+-------------+-----------+
|
|
| # | Field Name | Mandatory | Data type |
|
|
+=====+====================+=============+===========+
|
|
| 1 | id | No | Integer |
|
|
+-----+--------------------+-------------+-----------+
|
|
| 2 | title | No | String |
|
|
+-----+--------------------+-------------+-----------+
|
|
| 3 | selected | No | boolean |
|
|
+-----+--------------------+-------------+-----------+
|
|
|
|
The ``alarm_presets`` object contains the following attributes :
|
|
|
|
:id: Preset id value starting at index ''1''
|
|
|
|
:title: Preset title
|
|
|
|
:selected: Flag set to true if the preset id is selected as an alarm source
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
NetworkInfoContainer *extends RequestSucceededContainer*
|
|
--------------------------------------------------------
|
|
|
|
Description:
|
|
^^^^^^^^^^^^
|
|
Contains informations about the network state of the AwoX Audio Device.
|
|
|
|
Object layout:
|
|
^^^^^^^^^^^^^^
|
|
|
|
+---------------+------------+
|
|
| Field name | Data type |
|
|
+===============+============+
|
|
| network | object |
|
|
+---------------+------------+
|
|
| stats | object |
|
|
+---------------+------------+
|
|
|
|
|
|
The ``network`` object contains the following attributes :
|
|
|
|
:network_type: the type of the interface
|
|
|
|
:ip_mode: Mode of Ip Acquisition
|
|
|
|
:mac_address: The MAC address of the current interface
|
|
|
|
:ip_address: The current IP address of the device. Can be ``0.0.0.0`` if the device isn't bound to any network
|
|
|
|
:ip_netmask: The current IP netmask of the device. Can be ``0.0.0.0`` if the device isn't bound to any network
|
|
|
|
:ip_gateway: The current IP gateway of the device.
|
|
|
|
:ip_dns1: The main DNS Server used by the device. It could be empty.
|
|
|
|
:ip_dns2: The second DNS Server used by the device. It could be empty.
|
|
|
|
:connected_ssid: If the network_type is Wi-Fi, the field is returned. The SSID of the access point the device is currently bound to
|
|
|
|
:link_speed: If the network_type is Wi-Fi, the field is returned. The current WiFi link speed between the stick and the remote AP
|
|
|
|
The ``stats`` object contains the following attributes :
|
|
|
|
:total_tx_bytes: The amount of bytes sent by the device since it was started
|
|
|
|
:total_rx_bytes: The amount of bytes received by the device since it was started
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
AccessPointContainer *extends RequestSucceededContainer*
|
|
--------------------------------------------------------
|
|
|
|
Description:
|
|
^^^^^^^^^^^^
|
|
Wraps a list of AccessPoint.
|
|
|
|
Object layout:
|
|
^^^^^^^^^^^^^^
|
|
|
|
+---------------+------------+
|
|
| Field name | Data type |
|
|
+===============+============+
|
|
| ap_list | Array |
|
|
+---------------+------------+
|
|
|
|
|
|
The sole purpose of this object is to embed a list of ``AccessPoint`` within the ap_list field, and to advertise the user that the retrieval of the access point list went well.
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
AccessPoint
|
|
-----------
|
|
|
|
Description:
|
|
^^^^^^^^^^^^
|
|
Holds the characteristics of an access point.
|
|
|
|
Object layout:
|
|
^^^^^^^^^^^^^^
|
|
|
|
+--------------------------+------------+
|
|
| Field name | Data type |
|
|
+==========================+============+
|
|
| bssid | String |
|
|
+--------------------------+------------+
|
|
| channel | Integer |
|
|
+--------------------------+------------+
|
|
| raw_level | Integer |
|
|
+--------------------------+------------+
|
|
| scaled_signal_level | Integer |
|
|
+--------------------------+------------+
|
|
| capabilities_stringified | String |
|
|
+--------------------------+------------+
|
|
| capabilities | Array |
|
|
+--------------------------+------------+
|
|
| ssid | String |
|
|
+--------------------------+------------+
|
|
| is_bound | Boolean |
|
|
+--------------------------+------------+
|
|
| favorite | Integer |
|
|
+--------------------------+------------+
|
|
|
|
|
|
|
|
This object contains the following attributes :
|
|
|
|
:bssid: the MAC address of the access point
|
|
:channel: the channel of the access point
|
|
:raw_level: the signal quality of the Wi-Fi Link. between 0-100.
|
|
:scaled_signal_level: the radio level scaled on a scale of 5. Every results expressed in absolute dbm are converted on a 5-based scale. Very handy if you'd like to show to the user the level of the signal in a user-friendly way.
|
|
:capabilities_stringified: A string holding the informations about the authentication capabilities of the access point.
|
|
:capabilities: A clean list of the authentication capabilities this access point supports. This a list of strings which can take the following values : WPA-PSK, WPA2-PSK, WEP, EAP, WPS, OPEN.
|
|
:ssid: the SSID of the access point
|
|
:is_bound: whether the device is connected or is in the process of being connected to this access point
|
|
:favorite: integer value (0 or 1) to know if the Access point is in the favorite of the device.
|
|
|
|
We only support a connection based on one of the following authentication methods : WPA-PSK, WPA2-PSK, WEP and OPEN.
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
CpuInfoContainer *extends RequestSucceededContainer*
|
|
-----------------------------------------------------
|
|
|
|
Description:
|
|
^^^^^^^^^^^^
|
|
Contains informations about the CPU of the Device.
|
|
|
|
Object layout:
|
|
^^^^^^^^^^^^^^
|
|
|
|
+---------------+------------+
|
|
| Field name | Data type |
|
|
+===============+============+
|
|
| load | Integer |
|
|
+---------------+------------+
|
|
|
|
|
|
Field details:
|
|
^^^^^^^^^^^^^^
|
|
|
|
:load: CPU load of the CPU
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
MemoryInfoContainer *extends RequestSucceededContainer*
|
|
-------------------------------------------------------
|
|
|
|
Description:
|
|
^^^^^^^^^^^^
|
|
Holds informations about the device memory metrics.
|
|
|
|
Object layout:
|
|
^^^^^^^^^^^^^^
|
|
|
|
+----------------+------------+
|
|
| Field name | Data type |
|
|
+================+============+
|
|
| memory_info | object |
|
|
+----------------+------------+
|
|
|
|
The ``memory_info`` object layout is described as follow :
|
|
|
|
+------------------+-----------+
|
|
| Field name | Data type |
|
|
+==================+===========+
|
|
| total_memory | Long |
|
|
+------------------+-----------+
|
|
| available_memory | Long |
|
|
+------------------+-----------+
|
|
| used_memory | Long |
|
|
+------------------+-----------+
|
|
| cached | Long |
|
|
+------------------+-----------+
|
|
|
|
|
|
Field details:
|
|
^^^^^^^^^^^^^^
|
|
|
|
:total_memory: The total memory available on the device in bytes.
|
|
|
|
:available_memory: The free memory available on the device in bytes.
|
|
|
|
:used_memory: The used memory on the device in bytes.
|
|
|
|
:cached: The cached memory available on the device in bytes.
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
DeviceInfoContainer *extends RequestSucceededContainer*
|
|
-------------------------------------------------------
|
|
|
|
Description:
|
|
^^^^^^^^^^^^
|
|
Holds informations about the device informations.
|
|
|
|
Object layout:
|
|
^^^^^^^^^^^^^^
|
|
|
|
+----------------+------------+
|
|
| Field name | Data type |
|
|
+================+============+
|
|
| device_info | object |
|
|
+----------------+------------+
|
|
|
|
The ``device_info`` object layout is described as follow :
|
|
|
|
+-----+--------------------+-----------+
|
|
| # | Name | Data type |
|
|
+=====+====================+===========+
|
|
| 1 | Manufacturer | String |
|
|
+-----+--------------------+-----------+
|
|
| 2 | ProductName | String |
|
|
+-----+--------------------+-----------+
|
|
| 3 | CompanyName | String |
|
|
+-----+--------------------+-----------+
|
|
| 4 | HardwareVersion | String |
|
|
+-----+--------------------+-----------+
|
|
| 5 | SoftwareVersion | String |
|
|
+-----+--------------------+-----------+
|
|
| 6 | build_date | String |
|
|
+-----+--------------------+-----------+
|
|
| 7 | build_revision | String |
|
|
+-----+--------------------+-----------+
|
|
| 8 | uuid | String |
|
|
+-----+--------------------+-----------+
|
|
| 9 | uptime | Integer |
|
|
+-----+--------------------+-----------+
|
|
|
|
Field details:
|
|
^^^^^^^^^^^^^^
|
|
|
|
:Manufacturer: The Name of the Manufacturer should be ''AwoX''
|
|
|
|
:ProductName: Correspond to the Product Name could be ''SLCW13''
|
|
|
|
:CompanyName: Correspond to the CompanyName should be ''AwoX''
|
|
|
|
:HardwareVersion: Correspond to the Hardware Version could be ''1.0''
|
|
|
|
:SoftwareVersion: Correspond to the Software Version
|
|
|
|
:build_date: Correspond to the build date of the system.
|
|
|
|
:build_revision: Correspond to the revision attached to the firmware.
|
|
|
|
:uuid: Correspond to the unique UUID of the Device . could be ''xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx''
|
|
|
|
:uptime: Correspond to the uptime of the Device.
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
PlayerStateContainer *extends RequestSucceededContainer*
|
|
--------------------------------------------------------
|
|
|
|
Description:
|
|
^^^^^^^^^^^^
|
|
Holds informations about the player.
|
|
|
|
Object layout:
|
|
^^^^^^^^^^^^^^
|
|
|
|
+----------------+------------+
|
|
| Field name | Data type |
|
|
+================+============+
|
|
| player | object |
|
|
+----------------+------------+
|
|
|
|
The ``player`` object layout is described as follow :
|
|
|
|
+-----+--------------------+-----------+
|
|
| # | Name | Data type |
|
|
+=====+====================+===========+
|
|
| 1 | state | String |
|
|
+-----+--------------------+-----------+
|
|
|
|
Field details:
|
|
^^^^^^^^^^^^^^
|
|
|
|
:state: contains the state of the player could be ''stopped'', ''playing'' or ''paused''
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
LightCapabilitiesContainer *extends RequestSucceededContainer*
|
|
--------------------------------------------------------------
|
|
|
|
Description:
|
|
^^^^^^^^^^^^
|
|
Wraps a list of Light Capabilities.
|
|
|
|
Object layout:
|
|
^^^^^^^^^^^^^^
|
|
|
|
+----------------+------------+
|
|
| Field name | Data type |
|
|
+================+============+
|
|
| capabilities | Array |
|
|
+----------------+------------+
|
|
|
|
The ``capabilities`` array contain the list as string of the light capabilities.
|
|
it could be:
|
|
|
|
* SwitchPower
|
|
* Dimming
|
|
* WhiteLight
|
|
* ColorLight
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
LightSwitchPowerContainer *extends RequestSucceededContainer*
|
|
-------------------------------------------------------------
|
|
|
|
Description:
|
|
^^^^^^^^^^^^
|
|
Wrap the Sate of the Light state is equal to ''true'' is the light is turn ''on'', ''false'' otherwise.
|
|
|
|
Object layout:
|
|
^^^^^^^^^^^^^^
|
|
|
|
+---------------+------------+
|
|
| Field name | Data type |
|
|
+===============+============+
|
|
| state | Boolean |
|
|
+---------------+------------+
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
LightDimmingContainer *extends RequestSucceededContainer*
|
|
---------------------------------------------------------
|
|
|
|
Description:
|
|
^^^^^^^^^^^^
|
|
return the level of dimming.
|
|
|
|
Object layout:
|
|
^^^^^^^^^^^^^^
|
|
|
|
+---------------+------------+-----------------------+-----------------------+
|
|
| Field name | Data type | Minimum allowed value | Maximum allowed value |
|
|
+===============+============+=======================+=======================+
|
|
| level | Integer | 0 | 100 |
|
|
+---------------+------------+-----------------------+-----------------------+
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
WhiteLightContainer *extends RequestSucceededContainer*
|
|
-------------------------------------------------------
|
|
|
|
Description:
|
|
^^^^^^^^^^^^
|
|
Return the informations about the White Light. the temperature and the brightness.
|
|
|
|
Object layout:
|
|
^^^^^^^^^^^^^^
|
|
|
|
+---------------+------------+-----------------------+-----------------------+
|
|
| Field name | Data type | Minimum allowed value | Maximum allowed value |
|
|
+===============+============+=======================+=======================+
|
|
| brightness | Integer | 0 | 100 |
|
|
+---------------+------------+-----------------------+-----------------------+
|
|
| temperature | Integer | 0 | 100 |
|
|
+---------------+------------+-----------------------+-----------------------+
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
ColorLightRGBContainer *extends RequestSucceededContainer*
|
|
----------------------------------------------------------
|
|
|
|
Description:
|
|
^^^^^^^^^^^^
|
|
|
|
Wrap the the current color of the light and returned as an rgb color object.
|
|
|
|
Object layout:
|
|
^^^^^^^^^^^^^^
|
|
|
|
+---------------+------------+
|
|
| Field name | Data type |
|
|
+===============+============+
|
|
| rgbcolor | Object |
|
|
+---------------+------------+
|
|
|
|
The ``rgbcolor`` object contains the following attributes :
|
|
|
|
:red: red composant of the color
|
|
|
|
:green: green composant of the color
|
|
|
|
:blue: blue composant of the color
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
ColorLightHSVContainer *extends RequestSucceededContainer*
|
|
----------------------------------------------------------
|
|
|
|
Description:
|
|
^^^^^^^^^^^^
|
|
|
|
Wrap the the current color of the light and returned as an hsv color object.
|
|
|
|
Object layout:
|
|
^^^^^^^^^^^^^^
|
|
|
|
+---------------+------------+
|
|
| Field name | Data type |
|
|
+===============+============+
|
|
| hsvcolor | Object |
|
|
+---------------+------------+
|
|
|
|
The ``hsvcolor`` object contains the following attributes :
|
|
|
|
+---------------+------------+-----------------------+-----------------------+
|
|
| Field name | Data type | Minimum allowed value | Maximum allowed value |
|
|
+===============+============+=======================+=======================+
|
|
| hue | Integer | 0 | 359 |
|
|
+---------------+------------+-----------------------+-----------------------+
|
|
| saturation | Integer | 0 | 255 |
|
|
+---------------+------------+-----------------------+-----------------------+
|
|
| value | Integer | 0 | 255 |
|
|
+---------------+------------+-----------------------+-----------------------+
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
SourceSelectionContainer *extends RequestSucceededContainer*
|
|
------------------------------------------------------------
|
|
|
|
Description:
|
|
^^^^^^^^^^^^
|
|
|
|
The source selection container contains a list of sources available into the device.
|
|
|
|
Object layout:
|
|
^^^^^^^^^^^^^^
|
|
|
|
The ``SourceSelectionContainer`` is an array of ``available_source`` objects. The layout of a ``available_source`` object is described as follow :
|
|
|
|
+---------------+------------+
|
|
| Field name | Data type |
|
|
+===============+============+
|
|
| id | Integer |
|
|
+---------------+------------+
|
|
| name | String |
|
|
+---------------+------------+
|
|
|
|
The ``SourceSelectionContainer`` contains a ''current_source'' object too. This object is always present into the object.
|
|
This object contains a shortcut to the current object of the available source.
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
SongQueueContentListContainer *extends RequestSucceededContainer*
|
|
-----------------------------------------------------------------
|
|
|
|
Description:
|
|
^^^^^^^^^^^^
|
|
Contains informations about the song queue of the AwoX Audio Device.
|
|
|
|
Object layout:
|
|
^^^^^^^^^^^^^^
|
|
|
|
+------------------------+------------+
|
|
| Field name | Data type |
|
|
+========================+============+
|
|
| song_queue | Array |
|
|
+------------------------+------------+
|
|
| repeat_mode | String |
|
|
+------------------------+------------+
|
|
| shuffle_mode | Boolean |
|
|
+------------------------+------------+
|
|
| song_selected_position | Integer |
|
|
+------------------------+------------+
|
|
| active_state | Boolean |
|
|
+------------------------+------------+
|
|
|
|
The ``song_queue`` attribute is an array of ``Song`` objects. The layout of a ``Song`` object is described as follow :
|
|
|
|
+------------------+------------+
|
|
| Field name | Data type |
|
|
+==================+============+
|
|
| uri | String |
|
|
+------------------+------------+
|
|
| info | Object |
|
|
+------------------+------------+
|
|
|
|
:repeat_mode: The pair value can be ''repeat_none'', ''repeat_one'' or ''repeat_all''
|
|
|
|
:shuffle_mode: The pair value is equal to ''true'' if the shuffle is turn on, ''false'' otherwise
|
|
|
|
:song_selected_position: The pair value is a number indicating the current song selected position. -1 is returned if no position has been set or if the song queue is empty
|
|
|
|
:active_state: The pair value is equal to ''true'' if the song queue is active, ''false'' otherwise
|
|
|
|
|
|
|
|
|
|
|
|