Web API

You are here:
< Back

Kwikwai 1.1r879 (2018-04-14)

The web API is used by kwikwai’s web interface and supports most of its features.

Kwikwai answers to standard HTTP/1.0 queries on port 80 (https is not supported). All calls return JSON data. POST (along with CSRF protection) is used for any requests having side effects.

Note

  • Kwikwai’s Web Interface (for K1-10x models) mainly uses this API; it may however use URLs or objects which are not documented below. Anything not documented is private and may change or disappear between firmware revisions of kwikwai.
  • JSONP is supported. Append parameter “callback” to any get request (f.e. GET /ARI?callback=<function_to_call>).

GET /ARI

Returns a JSON object representing kwikwai’s current configuration, containing the following name/value pairs:

version
firmware version of kwikwai, for example “1.0r345”
name
Name assigned to kwikwai, for example “KWIKWAI”
sntp
time server ip address or name, for example “time.windows.com”
timezone_offset
offset in seconds between UTC and local time, for example “-32400” (for Alaska)
utc_time
time in UTC (in milliseconds) as known to kwikwai, for example “1262951839000”
random
random value, used to secure POST requests
MAC
MAC address (serial number) of kwikwai, for example “00:50:C2:AD:80:00”
ip
current IP address, for example “192.168.1.23”. If use_fixed_ip is true, then this has the same value than fixed_ip below.
mask
current mask, for example “255.255.255.0”. If use_fixed_ip is true, then this has the same value than fixed_mask below.
gateway
IP address of the current default gateway, for example “192.168.1.1”. If use_fixed_ip is true, then this has the same value than fixed_gateway below.
dns
IP address of the current DNS server, for example “192.168.1.1”. If use_fixed_ip is true, then this has the same value than fixed_dns below.
use_fixed_ip
“false” if using DHCP, “true” if using the fixed ip parameters below
fixed_ip
fixed IP address to use (if use_fixed_ip is true), for example “192.168.1.23”
fixed_mask
fixed mask to use (if use_fixed_ip is true), for example “255.255.255.0”
fixed_gateway
IP address of the gateway to use (if use_fixed_ip is true), for example “192.168.1.1”
fixed_dns
IP address of the DNS server to use (if use_fixed_ip is true), for example “192.168.1.1”
controller_uses_serial
“false” if using serial port for CLI, “true” if using it using the parameters below
baudrate
baudrate of the serial port (when used in react serial mode)
serial_config
bitmap defining the serial port configuration (when used in react serial mode). Only 96 (=8N1), 104 (=8N2) and 102 (=8E1) are supported today.
serial_mintimtrm
Min interval between transmissions in milliseconds. Max 9999.
controller_rules
Array of objects (max 6) containing the following name/value pairs:
  bus
“A” or “_” to disable the command
  condition
One of the following values:

  1. +5V raising
  2. +5V falling
  3. HPD raising (Hot Plug Detect)
  4. HPD falling
  5. CEC filter
  cec_filter
String containing the pseudo regexp to filter messages triggering the command. Hex string separated by ‘:’. The first byte may have ? to indicate any source/dest. The string may be terminated by “:*” to match any message length.
  output
Output port to use for the command. One of the following values:

  1. CEC
  2. Serial
  delay
Delay in 1/10th of a second before sending the command.
  command
The command string (in hex) to send in case of a match. Spaces in the string are allowed and ignored.
signals
Object containing the following name/value pairs:
  5V
Value of 5V signal.
  HPD
Value of the HPD signal.

GET /ARD

Returns a JSON object describing the devices discovered on the CEC bus, containing the following name/value pairs:

bus
Always “A” in kwikwai model k1-100
devices
Array of 15 objects (0x00 to 0x0E), each containing either ‘null’ or an object containing the following name/value pairs:
  osd_name
If known, the name of the device. Kwikwai used to automatically query device names but this is disabled in recent builds so this field is always empty.
  will_ack
If true, kwikwai acks this logical address.

In other terms, the command returns something like:

{
 "bus":"A",
 "devices":
  [
    {},                             <- the TV at 0x00 has no name but exists
    null,                           <- no 0x01 device found
    {"will_ack":"true"},                 <- kwikwai acks 0x02
    null,
    { "osd_name":"DVDP"},           <- a player at 0x04 named "DVDP"
    ...
  ]
}

GET /ART

Reads the connected device E-EDID and returns the raw data, or an error. Kwikwai shall be connected between a source and a sink for this to succeed. For bus “A” (the only one) in kwikwai k1-100.

The returned object contains the following name/value pairs:

error
“timeout error”
This name/value pair is only present in case of error.
ddc
[0,255,255,255,255,255,255,0, …
JSON array of 256 JSON numbers. This name/value pair is only returned in case of success.
bus
always “A” in this version

GET /ARK

Returns CEC messages exchanged on the CEC bus. Uses long polling and only returns when messages are available (or times out).

Parameters:

index
Index of the last received message (or 0), f.e. GET /ARK?index=23.

Returns

Returned name/value pairs:

next
Index to use for next call to GET /ARK
messages
Returns an array of message object, each containing the following name/value pairs:
  type
Type of the message; 1 for CEC messages or 4 for signals (HPD/5V)
  timestamp
Date and time of arrival (in millisecond) of the message/event
  ack
‘1’ if the message (as a whole) is acknowledged. To be ignored for signals.
  sent
‘true’ if the message was sent by kwikwai. To be ignored for signals.
  blocks
For CEC messages, array of message blocks as JSON number. Each block is 2 bytes, in order to encode the full 10 bits of the CEC blocks (see HDMI spec). For signals, the first block is 1 for 5V and 2 for HDP. The second block provides the pin value.
  matches
Array of indexes matching react filters
  bus
Always “A” in this version
timeout
Returned with value ‘1’ instead of messages in case of time out.

Below is a sample object.

{
 "messages":
 [
  {
    "timestamp":1281801681920,
    "ack":0,
    "blocks":[65344, 29248, 192],
    "bus":"A"
   }
  ],
 "next":12
}

POST /SF

Change general settings. Expects all of the following parameters (encoded as application/x-www-form-urlencoded in the POST message body):

random
must be equal to the random value returned by the last call to #GET /ARI and provided in all cases
name
Name
sntp
time server name or IP address
timezone
offset in seconds from UTC
fixed
‘true’ to used fixed IP address settings below (that must be provided) or ‘false’ to use DHCP
ip
fixed IP address
mask
fixed mask
gateway
fixed default gateway IP address
dns
fixed DNS name server IP address
password-current
current password
password-new
new password
password-new-repeat
new password repeated

Returns

Returns a JSON object containing the following name/value pairs:

error
Any value different than 0 means an error in changing the settings
reconfig
Set to 1 if the saving the settings caused a reconfiguration of the IP stack, which may result in kwikwai changing its IP address.

POST /AF

Change controller settings. Expects all of the following parameters (encoded as application/x-www-form-urlencoded in the POST message body):

random
must be equal to the random value returned by the last call to #GET /ARI and provided in all cases
controller_uses_serial
‘true’ to send commands via serial, ‘false’ to use the serial port for the CLI.
baudrate
serial baudrate to use to send serial commands.
serialconfig
serial bits and parity configuration. One of 96 (=8N1), 104 (=8N2) or 102 (=8E1).
smtt
Min interval between transmissions in milliseconds. Smaller or equal to 9999 ms.
bus<x>
’_‘to disable or ’A’ in this version. <x> is 0 to 5 in this and the following fields.
condition<x>
One of the following values:

  1. +5V raising
  2. +5V falling
  3. HPD raising (Hot Plug Detect)
  4. HPD falling
  5. CEC filter
cf<x>
String containing the pseudo regexp to filter messages triggering the command. Hex string separated by ‘:’. The first byte may have ? to indicate any source/dest. The string may be terminated by “:*” to match any message length.
output<x>
Output to use for the command. One of the following values:

  1. CEC
  2. Serial
delay<x>
Delay before sending the command, in 1/10th of a second. Smaller or equal to 99.
cmd<x>
The command string (in hex) to send. For serial commands, spaces in the string are allowed and ignored. CEC commands are formatted as usual (with a seperating ‘:’).
logical_address_list_bus
“A” for model k1-100
logical_address_list
A string of hex bytes separated by ‘,’ (comma), for example ‘1,2,B’. Kwikwai will ack these devices ID on the bus logical_address_list_bus.

Returns

Returns a JSON object containing the following name/value pairs:

error
Any value different than 0 means an error in changing the settings

POST /CEC

Sends a CEC message. Expects 3 parameters (encoded as application/x-www-form-urlencoded in the POST message body):

bus
“A” for model k1-100
random
Must be equal to the random value returned by the last call to #GET /ARI
message
A string of hex bytes separated by ‘:’, for example ‘0F:36’

Returns

Returns a JSON object containing the following name/value pairs:

error
Any value different than 0 means an error in sending the message

POST /TEST

Sends the command linked to a controller rule, over CEC or serial. Expects 2 parameters (encoded as application/x-www-form-urlencoded in the POST message body):

random
Must be equal to the random value returned by the last call to #GET /ARI
index
A number between 0 and 5 corresponding to the rule to test.

Returns

Returns a JSON object containing the following name/value pairs:

error
Any value different than 0 means an error in sending the message. 66 is returned if the rule refers to a serial command but the serial port is not assigned to the controller (see controller\_uses\_serial field in POST /AF above)

POST /ACK

This command is deprecated. Please use #POST /AF.

Changes the list of Logical Addresses being acknowledged by kwikwai. Expects 3 parameters (encoded as application/x-www-form-urlencoded in the POST message body):

bus
“A” for model k1-100
random
Must be equal to the random value returned by the last call to #GET /ARI
logical_address_list
A string of hex bytes separated by ‘,’ (comma), for example ‘1,2,B’

Returns

Returns a JSON object containing the following name/value pairs:

error
Any value different than 0 means an error in changing the list
devices
Same content as returned by #GET /ARD.