KRAMER KDS-EN6 Video Encoder User Guide

API Guide
MODEL:
KDS-EN6, KDS-DEC6
Application Programming Interface

P/N:

SAFETY WARNING
Disconnect the unit from the power supply before opening and servicing
For the latest information on our products and a list of Kramer distributors, visit our Web site where updates to this user manual may be found.
We welcome your questions, comments, and feedback.
www.KramerAV.com
info@KramerAV.com

Introduction

Welcome to Kramer Electronics! Since 1981, Kramer Electronics has been providing a world of unique, creative, and affordable solutions to the vast range of problems that confront video, audio, presentation, and broadcasting professionals on a daily basis. In recent years, we have redesigned and upgraded most of our line, making the best even better!
Overview
This document describes the commands that can be used for the KDS-6 console for managing USB. KDS-6 uses Linux OS and the console is operated by a BusyBox shell. API supports KDS-6 firmware versions 7.2 and above.

Defaults:

•  Telnet port: 24.

•  User name: “admin”

•  Password: “admin” to log in.
  Terms

•  Commands starting with “$” – Console commands executed under the Linux shell console. The default value of multicast IP (multicast_ip) is 225.0.10x.xxx. Please use this multicast_ip value.

•  The ‘ast_send_event -1 xxx’ command has a new shortcut named ‘e’. All of the following ‘ast_send_evnt -1 xxx’ commands can be replaced with the shortcut command
  like ‘e xxx’. They are exactly the same.

•  USB (USB over IP) extension function. A ‘transparent’ type of ‘USB over IP’ extension function. Comparing to ‘KMoIP’ which is ‘emulation’ type.

• KMoIP (Keyboard/Mouse over IP) extension function. A USB extension, but uses ‘emulation’ technology instead of ‘transparent’ USBoIP, optimized for USB Interrupt mode of work, guarantee quick responses.

•  Host – KDS-EN6

•  Client – KDS-DEC6

Command Syntax Conventions

The following table describes the syntax used with the commands in this document.

one option.
xlly| Keywords or parameters separated by a double vertical bar allow you to choose any or all the options

All commands and parameters are case-sensitive.
“/ # “ in a command example refers to a command prompt and is not part of the command.
To access the console using Telnet
Every KDS-6 host/client FW has Telnet and a Telnet client built in. A developer can use KDS6’s Telnet client to connect to any other KDS-6 board or write their own program
using Telnet protocol to connect to any KDS-6 board through the Ethernet network.

• Default is Telnet port 24.
• Use “root” to log in.
• No password is required.

Astparam APIs Overview

KDS-6 series firmware includes many firmware features that are configurable. Most of the configuration is done by the “Configuration APIs” (called “Astparam”). Astparam is the console command to access these system configurations. We also name this system configuration Astparam.
Astparam can be saved in flash ROM. So that system configuration is not lost after a system power failure.
The Astparam format is simply a key=value string pair. Both the “key” and “value” are ANSI strings and case-sensitive. The firmware decides how to use it. The firmware does not validate the Astparam, so any typed error could cause unexpected results.
All configuration modifications are saved in RAM until astparam save command is called.

Accessing Astparam

The most fundamental and powerful way to access Astparam is through the Astparam Console API command. Most alternative approaches are just a wrap of Astparam commands. To learn more about Console API commands and how to use console APIs, see Console APIs on page 5) or reference the “Console APIs v2” document.
To use Astparam:
$ astparam OPTIONS [KEY] [VALUE]

OPTIONS:

• g: read from RW partition cache file. [KEY] is required.
•  s: write to RW partition cache file (not saved to flash ROM yet). [KEY] and [VALUE] are required. If [VALUE] is empty the [KEY] is removed.
• flush: clear all settings in RW partition cache file including random generated MAC address. “./astparam save” is needed to clear all settings in flash ROM.
• dump: dump all parameters in RW partition cache file.
•  save: save all parameters in RW partition cache file into flash ROM.

Start/Stop KMoIP [KDS-DEC6]

In order to manage KMoIP use np_kmoip Astparam:

Key| Description| Value (bold is FW default)| Decoder/Encoder
---|---|---|---
no_kmoip| Enable/disable KMoIP function.| y: disable KMoIP
n: enable KMoIP| Decoder/Encoder

Syntax [Start] >>astparam s no_kmoip n
Syntax [Stop] >>astparam s no_kmoip y
Usage Information:

• This command is for KMoIP.
• This command is used for runtime control.

Console APIs

Switch Channel [KDS-DEC6] Command client to connect to a specified channel. For API backward compatibility and easier usage, this command has 3 syntax formats. Channel can be specified by channel number (select) or host’s IP address (host-IP-address).
Syntax [legacy, refresh current connection] e e_reconnect
Syntax [specify channel, apply to all services] e e_reconnect:: {ch- select|host-ip-addr}
Parameters

• ch-select:

•  Enter 4 digit decimal numbers from 0000 to 9999. It must be in 4 digit format prepending with 0.
  Example: 0000, 0001, 0100, 1000, 3456, 1342, 8888, 9999….

•  Default value: Determined from on-board 4-bits DIP switch. Since it is 4-bits 0 or 1, it can only represent 16 channels in total. They are 0000, 0001, 0010, 0011, 0100,
  0101,…, 1111. Default values are also interpreted as decimal numbers instead of binary values.

• host-IP-address:

•  Enter an IP address in dotted-decimal format. Used to specify the host’s IP address to connect to.
  Example: 169.254.11.22

•  {{Z}|{v||u||a| }}:
  Used to specify which function to apply.
  v: video over IP
  u: USB over IP
  a: Audio over IP
  Z: all features except video over IP
  Usage Information

•  The command supports ch-select from 0000 to 9999, which means there are a maximum of 10000 host channels that can be used.

•  To simplify the configuration process, FW will automatically map

•  ‘channel’ to ‘multicast IP’. Users don’t have to specify ‘multicast IP’.

•  For a trick to improve video switching time, please see Ex5 in the following examples section.

Version History
FW >= A7.0.0
Examples
Ex1: Start to connecting all services to the ‘current’ channel. ‘current’ channel is by default got from onboard 4-bits DIP switch. Only this command triggers FW to re-read the 4-bits DIP switch value.
/ # e e_reconnect
/ #
Ex2: Start connect all services to channel ‘9810’.
/ # e e_reconnect::9810
/ #
Ex3: Above command equals to following command:
/ # e e_reconnect::9810::Z
/ #
Ex4: Start to connect ‘video over IP’ to channel ‘9810’. The others use the ‘current’ channel.
/ # e e_reconnect::9810::v
/ #
Ex5: Use following command (without specifying ‘functions’) can switch video under only 1
second.
/ # e e_reconnect::1222
/ #
Ex8: Connect ‘USB over IP’ to ‘169.254.2.3’
/ # e e_reconnect::169.254.2.3::u
/ #

“Switch to X”, where X=Channel number command is a legacy command being used for switch channel. It is still being supported but we strongly encourage using the e_reconnect command instead. Its support will be discontinued in the next KDS-6 major release.

Stop Link [KDS-DEC6]

Used to stop services.
Syntax [stop all] e e_stop_link
Usage Information

•  All services will be stopped.
• Client’s ‘e_stop_link’ state will NOT persist between client reboot.
  Version History
  FW >= A7.0.0
  Examples
  Ex1: Stop services.
  / # e e_stop_link
  / #

Get Video Manager State

Syntax lmparam g STATE

Result

•  Encoder
•  s_init: The system is under initialization.
•  s_idle: System is idle. Services are stopped.
•  s_attaching: Services are started, but no client attached or no video source.
•  s_srv_on: Services are started.
•  s_error: Fatal error.
•  Decoder
•  s_init: The system is under initialization.
• s_idle: System is idle. Services are stopped.
•  s_srv_on: Services are started.
•  s_error: fatal error.

Example
Ex1: Get video manager current state.
/# lmparam g STATE
s_srv_on
/#

Get Attached Client IP [KDS-EN6]

Syntax lmparam g USB_CLIENT_IP
Result
• xxx.xxx.xxx.xxx: Return the IP address of last requested USBoIP client. If there is no one requested, it returns ‘0.0.0.0’.
Usage Information
Version History
FW >= A7.0.0
Examples
Ex1: Get current USBoIP status. The current requested client’s IP is ‘169.254.10.167’.
/ # lmparam g USB_CLIENT_IP
169.254.10.167/ #

Example

Astparam APIs

Generic

Key

| Description|

Value

| Host/ Client
---|---|---|---
multicast_on| Configure casting mode| y: Multicast mode  n: Unicast mode (default)| H/C
pwr_led_type| | share_usb: (default)| H/C
en_log| ‘y’ show debug message on debug console.| y: Display (default) n: Hide| H/C
ui_show_text| ‘y’ to display diagnostic information on the bottom of GUI. ‘n’ to hide it.| y: Display (default) n: Hide| C

IP Network Setting

When “hostnamebydipswitch” is “y”, “hostname_id”‘s default value is the value of “ch_select” where default get from on-board 4-bits DIP switch.

| y: (host default) n: (client default)| H/C
hostname_id| Overwrite “hostnamebydipswitch”. [FW >= A7.0.0] In FW < A7.0.0, client maps ch_select to host’s hostname in order to find and connect to host. In FW

Use a new approach to discover the host’s IP address and the host’s hostname is no more bonded to the channel resolution process. This means the host’s Astparam, hostname_id, can be any value as the user’s wish in FW >= 7.2. However, FW by default will still update hostname based on ch_select. To set hostname_id other than ch_select, please set ‘hostnamebydipswitch’ to ‘n’.

| | H/C
Key| Description| Value| Host/ Client
---|---|---|---
hostname_tx_middle| [FW >= 7.2] The default hostname of a host is ‘ast3-gateway XXXX’s. This
the parameter is used to change the ‘gateway’ part.
Both host and client need the same setting.| Gateway (default)| H/C
hostname_rx_middle| [FW >= 7.2] The default hostname of a host is ast3clientXXXXXXXXXXXX’. This parameter is used to change the ‘client’
part.
Both host and client need the same setting.| Client (default)| H/C
ch_select| Default channel value. Default value from on-board 4-bits DIP switch.
[FW >= 7.2][client] Due to the support of free routing, this value is only used
as the default value of following
‘ch_select_x’ parameters:
ch_select_v: video
ch_select_u: USB
ch_select_a: audio
ch_select_r: IR
ch_select_s: Serial
ch_select_p: GPIO/Push Button
[FW >= 7.2] ch_select_c: CEC
Change ‘ch_select’ won’t affect anything if ‘ch_select_x’ is already
specified.| | H/C
ch_select_v
ch_select_u
ch_select_a
ch_select_r
ch_select_s
ch_select_p
ch_select_c| Like ‘ch_select’ but for specific services.
Default value from ‘ch_select’:
ch_select_v: video
ch_select_u: USB
ch_select_a: audio
ch_select_r: IR
ch_select_s: Serial
ch_select_p: GPIO/Push Button
ch_select_c: CEC| | H/C
multicast_leave_force| [FW >= 7.2] Auto send IGMP to leave packet when received multicast packets that are not interested in. Specifying a value higher than 0 will enable this feature. However, DO NOT use a value that is too small. The smaller the value the higher load Ethernet switch may impact. Just using default value should be good to go. The specified time interval is used to specify the minimum interval of sending the IGMP leave packet.| 8000: Enable with 8000 ms
interval (default)
0: Disable| H/C

Video over IP

Examples:
00000000: Pass-Through
80000010: Full HD 1080p60
8000001F: Full HD 1080p50
8000005F: Ultra HD 2160p30
8000005E: Ultra HD 2160p25
80000004: HD 720p60
81004048: WXGA 1366×768@60
81004021: WXGA+ 1440×900@60
81004032: WUXGA 1920×1200@60
8100401D: SXGA+ 1400×1050@60| 0: Pass-Through (default)| C
v_src_unavailable_timeout| Wait for a v_src_unavailable_timeout ms before entering power save. Set to ‘-1’ means never timeout.| 10000: 10 seconds (default)
-1: never timeout| C
v_hdmi_hdr_mode| | 0: HDR passthrough (default)
1: Force HDR off| C
v_frame_rate| Used to control the frame rate of video encode. Default set to ‘0’ means ‘no limitation’ use best effort. Set to other value will
limit the maximum video encode framerate. Valid range: 0,1,2,…,60. Frame rate = (v_frame_rate / 60) input refresh rate For example, set to ‘30’ under 1080p60Hz: Frame rate =
(30/60) 60 = 30 FPS| 0: Best effort (default)| H
v_hdmi_force_rgb_output| ‘v_hdmi_force_rgb_output’ is used to change this behavior.
Default is ‘5’. You can use ‘osd_pic_on.sh’ under 2160p video
source. Set to ‘1’ to use YUV format under the 2160p case. Which can get better picture quality but can’t use ‘osd_pic_on.sh’ under 2160p. Set to ‘0’ means ‘pass-through’. The client will output the same color format as the Host input. Note that doing this will break features like ‘video fast switching’ and ‘osd_pic_on.sh’.| 5: all output RGB (default)
1: non-4K RGB, 4K YUV
0: pass-through| C

Video Wall

Astparam,
web_ui_cfg, for the video wall Web UI.| y: enable
n: disable (default)| H/C
vw_rotate| Clock-wise rotate output picture. Console API: echo 3

/sys/devices/platform/display/vw_rotate| 0: No rotate (default)
3: 180 degree
6: 270 degree| C
vw_stretch_type| Video wall stretching type: 1: Stretch out 2: Fit in| 1: Stretch out
2: Fit in (default)|
vw_ver| Specify video wall control APIs
version:
1: Default. Specify monitor layout and auto calculate coordinate.
2: Manually specify coordinate. Easier for mosaic style video wall configuration.
Following Astparam will be used when
‘vw_ver’ is ‘2’:
• vw_v2_x1
• vw_v2_y1
• vw_v2_x2| 1: Default 2: v2. Specify coordinate| C

HDCP

Key| Description| Value| Host/
Client
---|---|---|---
hdcp_always_on| Always enable HDCP 1.4| y: enable
n: disable (default)| H/C
hdcp_always_on_22| Always enable HDCP 2.2| y: enable
n: disable (default)| H/C
v_reject_hdcp| Don’t accept HDCP video sources.| y: enable
n: disable (default)| H

Audio

Default value ‘-1’ means use driver built-in default value.
This setting requires system reset to take effect. To runtime change the
volume, please use following command:
echo [value] >
/sys/devices/platform/150
0_i2s/analog_in_vol| -1,0,1,2 ~100| H/C
a_analog_out_vol| Set analog audio’s output volume. Range from 0 to 100 %.
Default value ‘-1’ means use driver built-in default value.
This setting requires system reset to take effect. To runtime change the
volume, please use following command:
echo [value] >
/sys/devices/platform/150
0_i2s/analog_out_vol| -1,0,1,2 ~100| H/C

IR over IP

feature The format is:
[device address][code for 0][code
for 1][code for 2]..[code for
8][code for 9] each variable is a decimal number and the valid device address is 0~65535
If the device address is 65535 (default), IR software decode function only displays decoded NEC result includes device
address and button code. This is for remote control learning purposes.| 65535_0_1_2_3_4_5_6_7_8_9| C

Serial over IP

Key

| Description| Value|

Host/ Client

---|---|---|---
no_soip| | y: Disable SoIP (default)
n: Enable SoIP| H/C
soip_type2 [FW < 7.2] soip_type [FW >= 7.2]| Specify Serial over IP operating type. [ FW >= 7.2] Introduced new ‘soip_type’. It will overwrite ‘soip_type2″s setting if defined. Otherwise, ‘soip_type”s default value comes from the setting of ‘soip_type2’.| y: Use type 2 (default)
n: Use type 1| H/C
1: Use type 1
2: Use type 2 (default)
3: Use type 3| H/C
soip_guest_on| | y:

n: (default)

| H/C
sO_baudrate| | 115200-8n1| H/C
soip_type2_token_timeout soip_token_timeout| For type 2 only.| 1,2,3… seconds| H/C
For type 2 and type 3. Default value from ‘soip_type2_token_timeout’.| H/C
ch_select_soip2 ch_select_s| Default value from from ‘ch select’.| N/A| C
Default SoIP channel.| |

CEC over IP

Disable CECoIP
n: Enable CECoIP (default)| H/C
cec_drv_option| 32bits bitmap CEC driver options to tweak driver behavior. Default value is 0. 0x00000001: Disable CEC extension| 0: (default)| H/C

All brand names, product names, and trademarks are the property of their respective owners.

KDS-EN6, KDS-DEC6 – Astparam APIs

Read User Manual Online (PDF format)

Read User Manual Online (PDF format)  >>

Download This Manual (PDF format)

Download this manual  >>