Command Line interface

Created On15.05.2018

bywpincyma

Kwikwai 2.0r899 (2020-04-04)

The Command Line Interface is a text based protocol that can be used over TCP/IP, serial and/or USB. It supports most of the features of kwikwai and is designed to be easy to implement in Home Automation or other embedded controllers.

News

HDMI settings Controller settings
HPD management: hdmi:hpd:get
+5V management: hdmi:5v:get

Notes

The main serial interface to kwikwai is the USB port. It will get all logging messages and allow for firmware download.
To use the USB port, a driver available on the FTDI website is required.
In the default configuration, the USB port and the serial port of kwikwai are one and the same. You can use both ports at the same time, but you should be prepared to get on both ports the answers to commands sent by either port.
Kwikwai allows to configure the serial port to control other devices. In this case the serial port is no longer available for the CLI. In fact, characters received by the port are discarded.
Multiple individual connections are possible via TCP/IP.
Some commands are only available via TCP/IP (for example, exit).

Protocol basics

Connection

To connect via serial or USB, use 38400 bauds, no parity, 8 data bits, a stop bit (a.k.a 38400 8-N-1) and no flow control. Note that for interactive session, you may want to activate local echo. Also note that kwikwai accepts any combination of Carriage Return (CR, ASCII 0x0D) and Line Feed (LF, ASCII 0x0A) on input but answers with a single CR.

To connect via TCP/IP, open a connection to kwikwai’s IP address on port 9090. To try commands, you can use the telnet client of most operating systems.

Commands & replies

Client sends commands in the form:

  command <param1> <param2> ... <CR>

On success, kwikwai answers with:

  OK command <answer1> <answer2> ... <CR>

On failure, kwikwai answers with:

  ERR command <error_id> <string> <CR>

where <string> is some text describing the error (this text can contains spaces).

For example, the command to send some message on the bus is cec:send. It expects 2 parameters, the bus to send the command to and the message:

  cec:send A FF:36
  OK cec:send A FF:36

If there is an error in the message, for example targeting an inexistent bus:

  cec:send B FF:36
  ERR cec:send 4 Bus ID must be A in this version

Asynchronous messages

In addition to replying to commands, Kwikwai may also send two sorts of asynchronous messages:

for logging messages (on serial/usb, as controlled by the verbose:set command)
```
  ! <string>
```
As an example, the message provided to remember entering the password once connected through telnet :
```
  ! Password required
```
for events (as controlled by the cec:listen:set command)
```
  * command <data1> <data2>
```
A typical CEC message
```
  * cec:message A 00:02:09.380 4F:82:10:00#
```

Notes

For the client, examining the first char of the received message is enough to determine its type. Many implementations may safely discard anything starting with “!”.
Replies repeat the command, which enables the sender to “forget” its requests and only manage kwikwai’s answers. In other terms, kwikwai answers “done that” to the “do that” request, not just “done”.

Available commands

System level commands

`password <password>`

Authorize the telnet connection. If a password is required (i.e. the password is not empty in the settings), this must be the first command exchanged upon connection, otherwise kwikwai drops the connection.

        password kwikwai
        OK password

`version:get`

Returns kwikwai’s firmware version.

        version:get
        OK version:get 1.0r304

`mac:get`

Returns kwikwai’s MAC address.

        mac:get
        OK mac:get 00:50:C2:AD:80:00

`reboot:upgrade`

Reboots the device in the firmware upgrade mode. The telnet session is disconnected and the device waits for a firmware file to be uploaded through XMODEM or the web interface.

        reboot:upgrade
        OK reboot:upgrade

`exit`

TCP/IP only: terminates the TCP/IP connection.

        exit
        OK exit
        Connection closed by foreign host.
        unix$

Settings commands

`name:get`

Returns kwikwai’s network name.

        name:get
        OK name:get KWIKWAI

`name:set <name>`

Sets the network name. Max 15 alphanumerical characters.

        name:set myprecious
        OK name:set myprecious

`verbose:get`

Returns the verbosity level of the logging function. Debug messages are only sent over serial/USB.

        verbose:get
        OK verbose:get 0

`verbose:set <0|1|2|3|4>`

Sets the verbosity level of the logging function. 4 is the maximum level. Debug messages are only sent over serial/USB.

        verbose:set 4
        OK verbose:set 4

`ipsettings:get`

Returns the network settings: “DHCP” or “STATIC”, the ip address, mask, gateway and dns (the ip address, mask gateway and dns information are only relevant for static configurations).

        ipsettings:get
        OK ipsettings:get DHCP 192.168.10.200 255.255.255.0 192.168.10.1 192.168.10.1

`ipsettings:set <"DHCP"|"STATIC"> <ip> <mask> <gwy> <dns>`

Sets the network settings: “DHCP” or “STATIC”, the ip address, mask, gateway and dns. When done over telnet, the connection may be disconnected if kwiwai must be reconfigured.

        ipsettings:set STATIC 192.168.1.100 255.255.255.0 192.168.1.1 192.168.1.1
        OK ipsettings:set STATIC 192.168.1.100 255.255.255.0 192.168.1.1 192.168.1.1

`ipconfig:get`

Returns the currently allocated ip address, mask, gateway and dns.

        ipconfig:get
        OK ipconfig:get 192.168.1.61 255.255.255.0 192.168.1.1 192.168.1.1

`time:local:get`

Returns the local time

        time:local:get
        OK time:local:get 15:06:50

`time:local:set <HH:MM:SS>`

Sets the local time. If enabled, this time configuration is overwritten by the SNTP synchronization.

        time:local:set 12:34:56
        OK time:local:set 12:34:56

`time:offset:get`

Returns the offset (in seconds) between utc and local time.

        time:offset:get
        OK time:offset:get 0

`time:offset:set <offset_in_seconds>`

Configures the offset (in seconds) between utc and local time.

        time:offset:set 3600
        OK time:offset:set 3600

`time:sntp:get`

Returns the name or ip address of the Simple Network Time Protocol (SNTP) server kwikwai contacts regularly to get accurate time. If the string is empty, the feature is disabled.

        time:sntp:get
        OK time:sntp:get time.windows.com

`time:sntp:set <server_name>`

Sets the Simple Network Time Protocol (SNTP) server name. The synchronization is done regularly. Use an empty string to disable the synchronization. Name length is limited to 47, forbidden characters are controls, space and “\ / : * ? " ; | .”.

        time:sntp:set time.apple.com
        OK time:sntp:set time.apple.com

`password:set <password>`

Sets the password. Max 31 alphanumerical characters.

        password:set secret
        OK password:set ****

`cec:ack:get <bus_id>`

Returns the list of Destination Logical Addresses whose frames are acknowledged by kwikwai. Logical addresses are separated by commas and in hex.

        cec:ack:get A
        OK cec:ack:get A 5,7,8

`cec:ack:set <bus_id> <logical_address_list>`

Defines the list of Destination Logical Addresses whose frames are acknowledged by kwikwai.This enables kwikwai to emulate a CEC device (for example to add CEC to an HDMI device lacking the feature, like a PC video card). Logical addresses to acknowledge shall be in hex separated by commas. An empty lists clears all adresses (i.e. send cec:ack:set A.)

        cec:ack:set A 2,3,B
        OK cec:ack:set A 2,3,B

`cec:listen:get`

Returns the state of the listening feature for CEC messages.

        cec:listen:get
        OK cec:listen:get 0

`cec:listen:set <0|1|2|>`

Enables or disables the listening feature for CEC messages. Use 1 or 2 to enable, 0 to disable, and nothing to toggle (between 0 and 1). Mode 1 returns messages as defined by the CEC specification. Mode 2 returns additional information for debugging (values of the CEC blocks flags).

        cec:listen:set 1
        OK cec:listen:set

The listening feature results in CEC frames being sent asynchronously to the client as follows

        * cec:message <bus_id> <HH:MM:SS:MS> <frame>

where <bus_id> is the bus, <HH:MM:SS:MS> is the local time including milliseconds, and, for mode 1, <frame> is a sequence of bytes separated by “:”, potentially followed by “#” to indicate the frame was acknowledged. For example:

        * cec:message A 00:02:09.380 4F:82:10:00#

In mode 2 (i.e. cec:listen:set 2), the flags are appended to each byte (when set) using letters “a” for the ACK bit and “e” for the EOM bit. The global acknowledgement indicator “#” is no longer shown. Colons “:” are replaced by semicolons “;” to separate bytes (to distinguish the modes). For example, the message above would appear as:

        * cec:message A 00:02:09.380 4Fa;82a;10a;00ae

In both modes, additonal messages are reported as below to indicate a react filter match, or the rise or fall of 5V and HDP signals:

        * hdmi:match <bus_id> <HH:MM:SS:MS> <index>
        * hdmi:5v:get <bus_id> <HH:MM:SS:MS> <0|1>
        * hdmi:hpd:get <bus_id> <HH:MM:SS:MS> <0|1>

where <bus_id> is the bus and filter_id is the ID of the matching filter.

`cec:send [<bus_id>] <cec_string>`

Sends the CEC frame cec_string on bus bus_id. Currently only bus “A” is supported (“A”). The frame shall be formatted as byte:byte:byte:…

        cec:send A FF:36
        OK cec:send A FF:36

Error 8 indicates collision. Error 7 indicates timeout. In both cases, the sender should try re-sending the message (which for convenience is echoed between square brackets at the end of the error message).

`ddc:read[<bus_id>] [<page_no>]`

Reads the DDC information from the sink connected to bus bus_id (“A” for kwikwai k1-100). page_no is the ddc page number (which can be useful for a rare device having multiple pages – most don’t.) The results are returned asynchronously by 128-bytes blocks.

        ddc:read
        OK ddc:read A 0
        ...
        * OK ddc:read A 0 0x00 00:ff:ff:ff:ff:ff:ff:00:...
        * OK ddc:read A 0 0x80 00:b3:00:95:00:01:01:02:...

`hdmi:hpd:get [<bus_id>]`

Returns the state of the Hot Plug Detect signal of bus bus_id (“A” for all kwikwais so far). This will typically be true when a valid source-sink pair is connected to kwikwai (the HPD line is powered by the sink from the +5V of the source).

        hdmi:hpd:get A
        OK hdmi:hpd:get A 0

When listening (see command cec:listen:set), hpd value changes are returned as follows:

        * hdmi:hpd:get <bus_id> <HH:MM:SS:MS> <0|1>

`hdmi:5v:get [<bus_id>]`

Returns the state of the +5V signal of of bus bus_id (“A” for all kwikwais so far). This will typically be true when a valid source is connected to kwikwai.

        hdmi:5v:get A
        OK hdmi:5v:get A 0

When listening (see command cec:listen:set), 5v value changes are returned as follows:

        * hdmi:5v:get <bus_id> <HH:MM:SS:MS> <0|1>

Controller settings

`controller:serial:config:set <enable> [<baudrate> <config> <mintimtrm>]`

Configure the serial port for kwikwai’s controller feature. When the feature is enabled, the serial port can be used to send commands in reaction to events on the HDMI cable. When disabled, kwikwai’s serial port can be used for the Command Line Interterface (i.e. this API).

enable is 0 to disable, 1 to enable, and nothing to toggle.

baudrate is the baud rate in decimal.

config is either 96 (for 8N1), 102 (for 8E1) or 104 (for 8N2)

mintimtrm is the minimum time interval between transmissions on the serial port, in milliseconds (a number equal to or smaller than 9999).

        react:serial:config:set 1 14400 96 200
        OK react:serial:config:set 1 14400 96 200

`controller:serial:config:get`

Returns the configuration of the controller serial port. See above for parameters.

        react:serial:config:get
        OK react:serial:config:get 1 14400 96 200

`controller:rule:set <index> <bus_id> [<condition> [<cec_filter>] <output> <delay> "<command>"]`

Sets the index-th rule of the kwikwai controller. The command will be sent by kwikwai should condition occur on bus_id, after delay.

index is from 1 to 6.

bus_id may be either “A” (in which case all other parameters must be provided), or “_“, in which case the feature is disabled, for example temporarily. In this last case conditon and all following fields are optional.

conditon is the event on the bus to react to. 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 is only required/present for condition 5 and consists of an hex string separated by “:”. In the first byte, “?” is accepted to indicate any source or destination id. The string may finish with “:*” to indicate the message may be longer than the filter.

output is the output port to use to send command. 1 for CEC and 2 for Serial (if enabled).

delay is the delay in 1/10th seconds before sending command. Max 99.

For serial, command is an hex string which can contain spaces (spaces are ignored when sending). For CEC, command is an hex string win the standard kwikwai cec format (hex bytes separated by “:”).

        controller:rule:set 1 A 5 0?:36 2 "0C 88 AB"
        OK controller:rule:set 1 5 A 0?:36 2 "0C 88 AB"

        controller:rule:set 1 _
        OK controller:rule:set 1 _ 5 0?:36 2 "0C 88 AB"

        controller:rule:set 2 A 1 1 "0F:36"
        OK controller:rule:set 1 A 1 1 "0F:36"

When listening (see command cec:listen:set), matches are returned as follows:

        * hdmi:match <bus_id> <HH:MM:SS:MS> <rule_index>

`controller:rule:get <index>`

Returns the index-th rule of the kwikwai controller. index is from 1 to 6.

        controller:rule:get 1
        OK controller:rule:get 1 _ 0?:36 2 "0C 88 AB"

`controller:rule:test <index>`

Tests the index-th rule of the kwikwai controller. Sends the related command immediately, over CEC or serial. This command is mainly useful to test serial connectivity. index is from 1 to 6.

        controller:rule:test 1
        OK controller:rule:test 1

Error codes

Not authentified
Unknown command
Too many arguments (8 max.)
Bad argument
DDC time out
Serial not enabled – cannot test serial command
CEC send timeout
CEC send collision

Command Line interface

Kwikwai Command Line Interface (CLI)

Kwikwai 2.0r899 (2020-04-04)

News

Notes

Protocol basics

Connection

Commands & replies

Asynchronous messages

Notes

Available commands

System level commands

password <password>

version:get

mac:get

reboot:upgrade

exit

Settings commands

name:get

name:set <name>

verbose:get

verbose:set <0|1|2|3|4>

ipsettings:get

ipsettings:set <"DHCP"|"STATIC"> <ip> <mask> <gwy> <dns>

ipconfig:get

time:local:get

time:local:set <HH:MM:SS>

time:offset:get

time:offset:set <offset_in_seconds>

time:sntp:get

time:sntp:set <server_name>

password:set <password>

HDMI related commands

cec:ack:get <bus_id>

cec:ack:set <bus_id> <logical_address_list>

cec:listen:get

cec:listen:set <0|1|2|>

cec:send [<bus_id>] <cec_string>

ddc:read[<bus_id>] [<page_no>]

hdmi:hpd:get [<bus_id>]

hdmi:5v:get [<bus_id>]

Controller settings

controller:serial:config:set <enable> [<baudrate> <config> <mintimtrm>]

controller:serial:config:get

controller:rule:set <index> <bus_id> [<condition> [<cec_filter>] <output> <delay> "<command>"]

controller:rule:get <index>

controller:rule:test <index>

Error codes

`password <password>`

`version:get`

`mac:get`

`reboot:upgrade`

`exit`

`name:get`

`name:set <name>`

`verbose:get`

`verbose:set <0|1|2|3|4>`

`ipsettings:get`

`ipsettings:set <"DHCP"|"STATIC"> <ip> <mask> <gwy> <dns>`

`ipconfig:get`

`time:local:get`

`time:local:set <HH:MM:SS>`

`time:offset:get`

`time:offset:set <offset_in_seconds>`

`time:sntp:get`

`time:sntp:set <server_name>`

`password:set <password>`

`cec:ack:get <bus_id>`

`cec:ack:set <bus_id> <logical_address_list>`

`cec:listen:get`

`cec:listen:set <0|1|2|>`

`cec:send [<bus_id>] <cec_string>`

`ddc:read[<bus_id>] [<page_no>]`

`hdmi:hpd:get [<bus_id>]`

`hdmi:5v:get [<bus_id>]`

`controller:serial:config:set <enable> [<baudrate> <config> <mintimtrm>]`

`controller:serial:config:get`

`controller:rule:set <index> <bus_id> [<condition> [<cec_filter>] <output> <delay> "<command>"]`

`controller:rule:get <index>`

`controller:rule:test <index>`