////////////////////////////////////////////////////////////////////////////////////////////
//////
//////  WARNING  WARNING  WARNING  WARNING  WARNING  WARNING  WARNING  WARNING  WARNING
//////
//////  The contents of this file are DEPRECATED. You should NOT use them unless you
//////  have an existing application. The older APIs are also deprecated but will continue to
//////  operate in support of existing clients.
//////
//////  The new AJA REST API should be used for all new development. It can be found here:
//////
//////      http://mykiproipaddress/rest.tmpl
//////
//////  The AJA REST API page documents how to control the Ki Pro using HTTP and includes
//////  interactive controls so you can interact with your Ki Pro unit using the API directly
//////  from the page. Also included is a REST Console that allows you to inspect the HTTP
//////  request and response data.
//////
//////  For a complete listing of all available parameters, navigate to this url on your Ki Pro unit.
//////
//////      http://mykiproaddress/descriptors
//////
//////  WARNING  WARNING  WARNING  WARNING  WARNING  WARNING  WARNING  WARNING  WARNING
//////
////////////////////////////////////////////////////////////////////////////////////////////

Ki-Pro Automation API v4.1.0

New in ver 4.1.0

+ Added an example python script that will monitor a Ki Pro unit and download all files that appear on the currently
mounted media. See: polling_for_clips.py

Ki-Pro Automation API v0.92

New in ver 0.92:

+ Example python script to go clip with a given name and park on the first frame

New in ver 0.91:

+ Example python script to record a clip with a given name
+ Example python script to play a clip with a given name

The Ki-Pro automation API allows remote systems to control the Ki-Pro with HTTP POST and GET requests using what is commonly 
refered to as a Representational State Transfer (REST) interface. This allows any scripting language or web 2.0 tool to control
the Ki-Pro.


Interactions follow the REST constraints including requiring that any request which may change the state of the ki-pro must be
a POST request type while any request which simply returns information may be a GET request type. Attempting to set a read only 
parameter will result in an HTTP error 400 Bad Request.


Common Operations:

get : http://mykipro/options?eParamID_MyParam - returns JSON encoding of supplied parameter's valid enumerated name/value pairs
post: http://mykipro/options?paramName=eParamID_MyParam&newValue=myValue - set a parameter to a new value
post: http://mykipro/options?transport_command=next_clip - advance one clip relative to the "current" clip, 200 response OK
post: http://mykipro/options?transport_command=prev_clip - reverse one clip relative to the "current" clip, 200 response OK
post: http://mykipro/options?transport_command=next_slot - select the next available slot, 200 response OK

Examples:

get : http://mykipro/options?eParamID_DetectInputFormat

[

   {value:"0", text:"No Input", short_text:"No Input", selected:"false"},
   {value:"1", text:"Error", short_text:"Error", selected:"false"},
   {value:"2", text:"1080i 30", short_text:"1080i 30", selected:"false"},
   {value:"3", text:"1080i 29.97", short_text:"1080i 29.97", selected:"true"},   <-- currently detected input
   {value:"4", text:"1080i 25", short_text:"1080i 25", selected:"false"},
   {value:"5", text:"1080PsF 24", short_text:"1080PsF 24", selected:"false"},
   {value:"6", text:"1080PsF 23.98", short_text:"1080PsF 23.98", selected:"false"},
   {value:"7", text:"720p 60", short_text:"720p 60", selected:"false"},
   {value:"8", text:"720p 59.94", short_text:"720p 59.94", selected:"false"},
   {value:"9", text:"720p 50", short_text:"720p 50", selected:"false"},
   {value:"10", text:"525i 29.97", short_text:"525i 29.97", selected:"false"},
   {value:"11", text:"625i 25", short_text:"625i 25", selected:"false"}
];


post: http://mykipro/options?paramName=eParamID_EncodeType&newValue=1

post: http://mykipro/options?paramName=eParamID_TransportCommand&newValue=1

get : http://mykipro/options?eParamID_Alarm

[
   {value:"0", text:"None", short_text:"None", selected:"true"},     <-- current alarm value (multi-selected enums possible for alarms)
   {value:"1", text:"HW Error", short_text:"HW Error", selected:"false"},
   {value:"2", text:"SW Error", short_text:"SW Error", selected:"false"},
   {value:"4", text:"Format Error", short_text:"Format Error", selected:"false"},
...
   {value:"16777216", text:"Backup and Reformat", short_text:"Backup and Reformat", selected:"false"},
   {value:"33554432", text:"Frame Skipped", short_text:"Frame Skipped", selected:"false"}
];


Deleting Clips:

get:  http://mykipro/clips - returns JSON array of clips in the AJA folder (no path, URL encoded filename + other attributes)
post: http://mykipro/clips?action=delete&clipname=clipname - delete a specific clip in the AJA folder (no path, URL encoded filename)

Examples:

get:  http://mykipro/clips

[ 
   { clipname: "Clip1ATK2.MOV", timestamp: "09/18/09 02:25:01", fourcc: "apch", width: "720", height: "486", framecount: "474", framerate: "29.97", interlace: "0" },
   { clipname: "Clip1ATK6.MOV", timestamp: "09/20/09 01:38:35", fourcc: "apch", width: "1920", height: "1080", framecount: "3625", framerate: "29.97", interlace: "0" },
   { clipname: "Clip1ATK5.MOV", timestamp: "09/20/09 01:38:35", fourcc: "apch", width: "1920", height: "1080", framecount: "1897", framerate: "29.97", interlace: "0" },
   { clipname: "Clip1ATK43.mov", timestamp: "12/14/09 20:11:30", fourcc: "apcn", width: "1920", height: "1080", framecount: "2334", framerate: "29.97", interlace: "1" }
];


Retrieving Current Settings:

get:  http://mykipro/values?eParamID_MyParam - returns JSON encoding of a parameter's "current" value without enumerated options
post: http://mykipro/values?eParamID_MyParam&paramName=eParamID_MyParam&newValue=myValue - sets a parameter's value

Examples:

get:  http://mykipro/values?eParamID_TransportState

var param_val = { name:"Transport State", value:"3" };  <-- NOTE: 3 means Playing Forward

get:  http://mykipro/values?eParamID_SystemName

var param_val = { name:"System Name", value:"Jibbin" };  <-- NOTE: variable declaration will be removed in the future (deprecated)

get:  http://90.0.7.125/values?eParamID_Alarm

var param_val = { name:"Alarm Status", value:"0" };  <-- NOTE: variable declaration will be removed in the future (deprecated)

post: http://mykipro/values?paramName=eParamID_TransportCommand&newValue=1


Available Parameters (descriptors) as HTML:

The descriptors page contains information describing each setable parameter and all legal values for each parameter in the Ki-Pro API. This is documentation, not a machine readable transaction.

Navigate with your browser to:

http://mykipro/desc.html


Available Parameters (descriptors) as JSON:

The descriptors handler, when given the paramid=* argument generates a machine readable (JSON) output for all parameters.

The generated JSON is an array of descriptors with each descriptor supplying meta-data and all legal values for each paramater in the Ki-Pro API.

get: http://mykipro/descriptors?paramid=*

Examples (whitespace added for clarity):

[
{"param_type":"enum",
"param_id":"eParamID_VideoInSelect",
"param_name":"Video Input",
"class_names":[],
"string_attributes":[{"name":"description","value":"Selects a video input source from the video input connections available.  This is the video that will be recorded and/or passed through."}],
"integer_attributes":[],
"enum_values":[{"value":0,"text":"SDI","short_text":"SDI"},{"value":1,"text":"HDMI","short_text":"HDMI"},{"value":2,"text":"Component","short_text":"Cmpnt"}],
"min_value":0,
"max_value":2,
"default_value":0,
"adjust_by":1,
"scale_by":1,
"offset_by":0,
"display_precision":0,
"units":""},

{"param_type":"enum",
"param_id":"eParamID_AudioInSelect",
"param_name":"Audio Input",
"class_names":[],
"string_attributes":[{"name":"description","value":"Selects an audio input source from the audio input connections available, including embedded SDI audio which requires an SDI video source and HDMI audio, which requires and HDMI video source."}],
"integer_attributes":[],
"enum_values":[{"value":0,"text":"SDI","short_text":"SDI"},{"value":1,"text":"RCA","short_text":"RCA"},{"value":2,"text":"XLR","short_text":"XLR"},{"value":3,"text":"HDMI","short_text":"HDMI"}],
"min_value":0,
"max_value":3,
"default_value":0,
"adjust_by":1,
"scale_by":1,
"offset_by":0,
"display_precision":0,
"units":""}
]

Less Common Operations: Gang Control

Please see the Ki-Pro Manual for an explanation of Gang control. The following API provides access to the capabilities as those 
provided in the Web user interface.

To find out what other Ki-Pros are available on the local subnet.
get : http://mykipro/nubs?action=discover_nubs&board_type=128

The first time, the Ki-Pro will respond with:
[
];

This means the cache is empty, but the unit is scanning the network for other Ki-Pros.
The time this operation takes depends on the latency, size and Ki-Pro population of your network subnet. When it is finished making the request again:
get : http://mykipro/nubs?action=discover_nubs&board_type=128

Will respond with something like:

[
{hostname:"10.1.1.90", description:"AJA Ki Pro", boardType:"128", boardNumber:"0", boardID:"270811392"  },
{hostname:"10.1.1.51", description:"AJA Ki Pro", boardType:"128", boardNumber:"0", boardID:"270811392"  },
{hostname:"10.1.1.212", description:"AJA Ki Pro", boardType:"128", boardNumber:"0", boardID:"270811392"  }
];


You can also specify parameters to control how the results of the search are cached.

http://mykipro/nubs?action=discover_nubs&board_type=128&force_discover=[true|false]&really=really

The parameters mean:

action - only discover_nubs is allowed (or required...). In truth, only the text "discover_nubs" needs to be present *anywhere* in the query string.
board_type - specify that we are looking for Ki-Pros (OEMs will find this number familiar from NTV2BoardType)
force_discover - if true, temporarily disables server-side logic that rate limits discovery attempts
really - if "really", forces a flush of the server-side cache and forces a discovery cycle

   1. This handler only returns what is in it's "discovered boards" cache which is initially empty.
   2. Discovery *only* happens *after* the server has sent a response to the client and runs asynchronously to additional requests. This prevents long delays when obtaining a list of discovered boards since all requests are satisfied out of the cache.
   3. Discovery is rate limited to every DISCOVERY_INTERVAL (30 seconds) so that a user or script can't overwhelm the proc. This also helps prevent flooding the network with multicast discovery traffic.
   4. The server-side board cache is cleared (completely) every CLEARING_INTERVAL (150 seconds) as a simple way of aging out entries in the cache (units that get powered off or lose network connectivity.) In the future we may age individual cache entries.
   5. No ongoing discovery is performed if there are no clients polling this handler. See #2 above.
   6. No discovery is performed if the target processor is too busy, ie. when /proc/loadavg for one minute window > PROC_BUSY_THRESHOLD (0.75) - exception: when really=really or when the cache is cleared. Note: if only force_discover=true, no discovery is done if the proc is too busy, hence the really=really option.

For instance a request like:

http://mykipro/nubs?action=discover_nubs&board_type=128&force_discover=true&really=really

Will block, waiting for a forced scan of the subnet for Ki-Pros. The advantage is that even on the first call this request will contain any other Ki-Pros found in the scan. The drawback is that the call can take some time and may cause single-threaded client to seem unresponsive. 

The results will be similar to:

[
{hostname:"10.1.1.90", description:"AJA Ki Pro", boardType:"128", boardNumber:"0", boardID:"270811392"  },
{hostname:"10.1.1.51", description:"AJA Ki Pro", boardType:"128", boardNumber:"0", boardID:"270811392"  },
{hostname:"10.1.1.212", description:"AJA Ki Pro", boardType:"128", boardNumber:"0", boardID:"270811392"  }
];


Waiting For Configuration Events, including Timecode:

Clients can perform a blocking wait for configuration events (parameter changes) via a two step process:

1) Create a connection for tracking events on a per-connection basis. This is typically only done once per application.
2) Wait for events - using the connection obtained in step #1. This is typically done repeatedly - after obtaining events, re-request the same url to obtain more

The associated urls are:

Create a connection:

http://mykipro/json?action=connect&configid=0

Example response:

{"connectionid":"20"}

After obtaining a connectionid, you must wait for events at least once per minute or else the connectionid will be expired by the server
and subsequent requests to wait for events will fail.

Wait for events:

http://mykipro/json?action=wait_for_config_events&configid=0&connectionid=xyz
[where xyz is a connectionid obtained from the connect response]

Example response (whitespace added for clarity):

[
{"param_id":"eParamID_DisplayTimecode","param_type":"12","int_value":"0","str_value":"00:00:00:00","last_config_update":"0"},
{"param_id":"eParamID_TransportCommand","param_type":"3","int_value":"4","str_value":"Stop Command","last_config_update":"6"}
]

Each response will usually contain an eParamID_DisplayTimecode and any other parameter changes that have occured since the previous
wait for events request was received for the given connectionid.

Cueing to a Timecode:

You can tell the Ki-Pro to cue to a certain timecode by setting eParamID_CueToTimecode to a timecode string (eg. "01:00:01:00") then
setting eParamID_TransportCommand to the value for eTCCue (14 at the time of writing but this could change);

For an example see cue.py in the python directory.
