ncast serial interface specification · ncast presentation recorder serial interface specification...

NCast Presentation Recorder Serial Interface Specification

NCast Product Documentation

Presentation Recorder Hydra

Serial Interface Specification

Revision 1.3

Software Release 9.2.0

March 10th, 2016

Copyright © NCast Corporation, 2016

NCast Corporation Version 1.3


Table of Contents - Serial Command Reference 1 Introduction........................................................................................................................................................... 3

1.1 Purpose.......................................................................................................................................................... 3 1.2 Document Overview....................................................................................................................................... 3

2 Serial Port Interface.............................................................................................................................................. 4

2.1 Serial Port Connector..................................................................................................................................... 4 2.2 Serial Port Interface....................................................................................................................................... 4 2.3 Serial Port Settings........................................................................................................................................ 4 2.4 Serial Pinouts................................................................................................................................................. 4 2.5 Control 2 Interface.......................................................................................................................................... 5 2.6 Telnet Interface.............................................................................................................................................. 5

3 Command Format................................................................................................................................................. 7

3.1 Command Strings.......................................................................................................................................... 7 3.2 Command Response..................................................................................................................................... 7 3.3 Command Processing.................................................................................................................................... 7 3.4 Essential Commands..................................................................................................................................... 8

4 Command Table................................................................................................................................................... 9

4.1 Command List................................................................................................................................................ 9 4.2 Command Responses.................................................................................................................................. 14 4.3 Common Problems...................................................................................................................................... 15

5 Special Functions............................................................................................................................................... 16

5.1 Purpose........................................................................................................................................................ 16 5.2 Identification Exchange................................................................................................................................ 16 5.3 System Information...................................................................................................................................... 16 5.4 Response Codes.......................................................................................................................................... 17 5.4.1 Presentation Recorder Status................................................................................................................... 17 5.4.2 Error Reports............................................................................................................................................. 18 5.4.3 Asynchronous Interrupt............................................................................................................................. 19 5.4.4 Command Execution Acknowledgment ....................................................................................................19 5.4.5 Command Reply....................................................................................................................................... 19 5.5 Commands for Channel Change.................................................................................................................. 19 5.5.1 Select a Channel ................................................................................................................................... 19 5.5.2 Becoming a Streaming Receiver ...........................................................................................................19 5.5.3 Becoming a Streaming Sender................................................................................................................. 19 5.5.4 Starting RTMP Streaming......................................................................................................................... 20 5.5.5 Commence Local Recording..................................................................................................................... 20 5.5.6 Changing Channels with Default Conditions .........................................................................................20 5.5.7 Getting and Setting Channel Options........................................................................................................20 5.6 Program Begin, Starting a Session..............................................................................................................22 5.7 Program End, Ending a Session.................................................................................................................. 22 5.8 Upload Progress.......................................................................................................................................... 22 5.9 Power Down, Shutdown............................................................................................................................... 22 5.10 Loopback: L0, L1........................................................................................................................................ 22 5.11 Recording Commands................................................................................................................................ 22 5.12 Audio Level Commands............................................................................................................................. 25 5.13 Subtitle Commands.................................................................................................................................... 26

6 Sample Code...................................................................................................................................................... 28

6.1 Java Program Example................................................................................................................................ 28

7 Revision History.................................................................................................................................................. 29



1 Introduction

1.1 PURPOSE

The NCast Serial Specification outlines the design implementation for an RS-232 interface to control the Presentation Recorder by external controllers such as a Crestron or AMX device. This same serial command set may be used on a Telnet connection using an IP network as the control link.

1.2 DOCUMENT OVERVIEW

This document is divided into several sections. There is a description of the physical interface, command structure, available commands and status responses.



2 Serial Port Interface

2.1 SERIAL PORT CONNECTOR

The serial interface connector is located at the back of the Presentation Recorder. This is a male DE-9-P type connector.

2.2 SERIAL PORT INTERFACE

The serial port interface conforms to the RS-232 Specification and is configured as a DTE.

2.3 SERIAL PORT SETTINGS

The default speed for the serial link in each direction will be 38,400 bps. Each character will consist of one start bit, eight data bits and one stop bit. The high-order data bit will be normally unused and set to zero. There will be no parity bit.

Parameter Setting

Data Bits per Second 38,400

Data Bits 8

Parity None

Stop Bits 1

Flow Control None

2.4 SERIAL PINOUTS

For proper operation of the serial interface a minimum of three connecting wires are needed: Rx Data, Tx Data and Ground



Pin Signal Description

1 DCD Data Carrier Detect

2 Rx Data Serial In, Received Data

3 Tx Data Serial Out, Transmit Data

4 DTR Data Terminal Ready

5 GND Ground

6 DSR Data Set Ready

7 RTS Request to Send

8 CTS Clear to Send

9 RI Ring Indicate

2.5 CONTROL 2 INTERFACE

In addition, there is a second serial connection on the Control 2 connector (reserved for future use). Pinouts for this connector:

Pin Signal Description

1 Tx Data Serial Out, Transmit Data

2 Rx Data Serial In, Received Data

3 GND Ground

4 Reset Active low, drive with relay

5 GND Ground for Reset line

6 Power On/Off

Active low, drive with relay

The Reset contact closure reboots the unit. Power On/Off has the same functionality as the front panel power switch. Neither of these are part of a standard RS-232 interface.

2.6 TELNET INTERFACE

The Telnet Interface is reached through use of a Telnet program or its equivalent. A TCP connection is made to the default Telnet port (currently port 7474) and an initial Id command is sent to initiate communication with the Presentation Recorder. The port number used may be changed on the Telnet configuration web page. A non-standard port was chosen to reduce intrusive attacks on the system.

Example:

telnet pr.mycompany.com 7474

IdTelnet,002,my.password (Note: uppercase eye, lowercase dee)

The password is set on the Telnet configuration page. An IP restriction may also be set. The IP restriction controlswhich IP addresses are permitted to connect to the Telnet port. As Telnet passwords are sent in clear-text, propersecurity controls should be in place to restrict the range of IP addresses which may issue commands to the Presentation Recorder.

An IP restriction entry is either a single IP address:

w.x.y.z

or a range of IP addresses:



w.x.y.*

or a subset of a network:

w.x.y.0/24

or a list (comma separated) of IP addresses or ranges:

a.b.c.d, m.n.o.*, w.x.y.z

To exit from a Telnet session, simply issue the Quit command (QT):

QT<lf>

The TCP connection will then be closed and a new login will be required.

If the Telnet TCP connection does not receive a keep-alive protocol response within the timeout period (15 minutes), the connection will be closed and must be re-opened by the Telnet client.



3 Command Format

3.1 COMMAND STRINGS

A standard command consists of alpha-numeric characters followed by a line feed:

AA<lf>

where the first character is always an alphabetic character (A-Z, a-z) and <lf> stands for the line feed character (hex 0x0a). Examples:

L0<lf> Display loopback is off.

C2<lf> Change operation to Channel 2.

Upper-case and lower-case must be treated uniquely, so the commands

aa<lf>

Aa<lf>

aA<lf>

AA<lf>

represent four different commands in the command set.

Commands may be terminated with a carriage return-line feed <cr><lf> pair. The <cr> will be discarded. For example,

AA<cr><lf>

produces the same result as

AA<lf>

but

AA<cr>

Is not a valid command.

3.2 COMMAND RESPONSE

After a command is sent to the Presentation Recorder, a command confirmation response is generated, indicatingthat the command has been received:

&<lf>

This response does not indicate that the command is finished or that it has completed execution. It simply confirms that the command string has been received by the Presentation Recorder.

3.3 COMMAND PROCESSING

After reception of the command string, the Presentation Recorder executes the command. Once processing has completed the Presentation Recorder will return the following strings:

+<command><lf> Command has executed properly

-<command><lf> Command has not executed properly



In the case of a command which returns a value, the command return value is sent in the lines between "&<lf>" and "+<command>"

Here is an example of a complete dialog to start a Presentation Recorder on Channel 1:

Controller: “IdSerial,002<lf>” (Note: uppercase eye, lowercase dee)

PR-Hydra: “&<lf>”

PR-Hydra: “@NCast,002<lf>”

PR-Hydra: “+IdSerial,002<lf>” (Note: uppercase eye, lowercase dee)

Controller: "C1<lf>"

PR-Hydra: "&<lf>"

PR-Hydra: “+C1<lf>"

To end the Session, only the following command is required:

Controller: "PE<lf>"

PR-Hydra: "&<lf>"

PR-Hydra: “+PE<lf>"

NOTE: The Id command must be the first command issued to open the link. Please see Section 5.2 for additional details. (Note: uppercase eye, lowercase dee) Use “Serial,002” exactly as shown.

3.4 ESSENTIAL COMMANDS

In the table below, the minimal commands required to control a Presentation Recorder are the Id (Identification), Cn (Channel Start) and PE (Program End). Once those have been implemented the next level would probably include R0/R1 (Record Stop/Start). Finally, there might be a need to switch Main or Pip input devices (Gn, Vn) or do an input swap (SW). These few commands are the only ones required for simple operation of the unit.

Note: The Recording commands (R0, R1) are a subset of the Channel Start/Stop commands. They will not activate recording unless a Channel Session has already been started (e.g. C1). A Channel may be configured for“Auto-Start Recording” which will initiate recording when the Channel starts, thus eliminating the need for R1 or R0 altogether. Recording will stop when the Channel stops (PE).



4 Command Table

4.1 COMMAND LIST

Featured below is a table defining all commands for the Serial Interface. Included are the ASCII commands, with the <lf> sequence assumed to be following every outlined command.

Function Input Commands Result if Processed

Audio Input Mic A1 Enables Audio Mic Input

Audio Input Mic, Gain A1,<num> Enables Audio Mic Input, set Gain to 0-100

Audio Input Line A2 Enables Audio Line Input

Audio Input Line, Gain A2,<num> Enables Audio Line Input, set Gain to 0-100

Audio Input USB A3 Enables Audio USB Input, Gain fixed at 100

Audio Input XLR A4 Enables Audio XLR Input

Audio Input XLR, Gain A4,<num> Enables Audio XLR Input, set Gain to 0-100

Audio Input HDMI-1 A5 Enables Audio HDMI-1 Input, Gain fixed at 100

Audio Input HDMI-2 A6 Enables Audio HDMI-2 Input, Gain fixed at 100

Audio Input SDI A7 Enables Audio SDI Input, Gain fixed at 100

Border for PIP Off b0 Set PIP window border off

Border for PIP On b1 Set PIP window border on

Select Channel 1-25 C1…25 Selects Channel 1-25, and starts a session

Select Channel C<num>,N Select Channel 1-25, change layouts, do not start

Select Channel with Change of role

C<num>,<role> Select Channel 1-25, and start a session with a given role. Roles can be R=Receive, S=Send, L=Local Recording, T=RTMP Streaming

Get the value of a Channel Option

C<num>,option Report the value of a Channel setting. See Section 5.5.7for details on the options available.

Set the value of a Channel Option

C<num>,option,value Report the value of a Channel setting. See Section 5.5.7for details on the options available.

Set display colorspace dc<0|1> Display colorspace command (0 - RGB, 1 - YPBPR)

Set display framerate df,<1|2|4|12|60> Display framerate command (1 - full, 60 - 1/16)

Set display resolution dm<1|2> Display output command (1 - 720p, 2 - 1080i). This is only for 1080 capable recorders.

Fullscreen layout f<0|1|2> Full screen command (0 - None, 1 - Main, 2 - PIP)

Graphics Input Composite G1 Enables Graphics Input from Composite Input

Graphics Input VGA G3 Enables Graphics Input from VGA

Graphics Input DVI-D G4 Enables Graphics Input from DVI-D input

Graphics Input DVI-A G6 Enables Graphcs Input from DVI-A input

Graphics Input HDMI-1 G7 Enables Graphics Input from HDMI-1 input




Graphics Input Displayport G8 Enables Graphics Input from Displayport

Graphics Input 3G-SDI G9 Enables Graphics Input from 3G-SDI input

Graphics Input HDMI-2 G10 Enables Graphics Input from HDMI-2 input

Graphics Input Adjustments G1,brt,cntr,sat,hue,s Set Composite video input adjustment values: brightness (0-100), contrast (0-100), saturation (0-100), hue (0-100), sharpness (0-44).

Graphics Input Adjustments G3,brt,cntr,sat,hue Set graphics VGA input adjustment values: brightness (0-100), contrast (0-100), saturation (0-100), hue (0-100).

Graphics Input Adjustments G4,brt,cntr,sat,hue Set graphics DVI-D input adjustment values: brightness (0-100), contrast (0-100), saturation (0-100), hue (0-100).

Graphics Input Adjustments G6,brt,cntr,sat,hue Set graphics DVI-A input adjustment values: brightness (0-100), contrast (0-100), saturation (0-100), hue (0-100).

Graphics Input Adjustments G7,brt,cntr,sat,hue Set graphics HDMI-1 input adjustment values: brightness (0-100), contrast (0-100), saturation (0-100), hue (0-100).

Graphics Auto Adjustment GA Send command to auto-adjust image centering.

Graphics Signal GS Report the resolution and type of the graphics input signal: :1024x768p or :1280x720i or :0x0p (no signal)

Graphics Adjustment GD, GL, GR, GU Graphics adjustment Down, Left, Right, Up.

Identification Id<controller>,<rev> Identify controller and software revision (Note: uppercase eye-lowercase dee)

IP Address Ip Request IP Address of unit. (Note: uppercase eye-lowercase pee).

Information on System Is Request serial number and system information. (Note: uppercase eye-lowercase es)

Captured Graphics Loopback OFF

L0 Do not display captured graphics locally

Captured Graphics Loopback ON

L1 Display captured graphics locally. This impacts the CPUat the transmitting site and should not be used for peak performance.

Loopback Swap OFF LS0 Main display on HDMI Out, Dual display on VGA Out

Loopback Swap ON LS1 Main display on VGA Out, Dual display on HDMI Out

Meter OFF m0 Audio meter off.

Meter ON m1 Audio meter on.

Meter Position m<nw|ne|sw|se> Audio meter position is top-left, top-right, bottom-left, bottom-right

Measured Audio Levels ma Report all audio levels in dB: local left, local right, network left, network right. Max value 0.0 dB, Min value –100.0 dB




Measured Audio Local ml Report local audio levels in dB: local left, local right. Maxvalue 0.0 dB, Min value –100.0 dB

Measured Audio Network mn Report network audio levels in dB: network left, network right. Max value 0.0 dB, Min value –100.0 dB

Output Audio Gain O0,<num> Set Audio Output Gain to 0-100

Output Loopback Gain O1,<num> Set Audio Output Loopback Gain to 0-100

Overlay Graphics Off OG0 Disable all overlay graphics

Overlay Graphics 1 OG1,n Enable (n=1) or disable (n=0) overlay graphic 1




Overlay Text Erase OS0 Sets empty text on all four text overlays

Overlay Text Update OS[1|2|3|4],TEXT Set TEXT text on the given text overlay. TEXT can include special parameters (%H, %M, %S etc., \n for new line and \\ for \).

Overlay Text Off OT0 Disables all four text overlays

Overlay Text On/Off OT[1|2|3|4],n Enable (n=1) or disable (n=0) text overlay [1|2|3|4]

Program Begin PB Program begin. Starts the Active Session.

Program End PE Program end. Ends the Active Session.

Processor Reboot PR Reboot the Presentation Recorder.

Power Down, Shutdown PS Shuts down the Presentation Recorder.

Power Down, Shutdown when Idle

PSI Shuts down the Presentation Recorder when Idle (transcoding, uploads have been completed) for at least 1 minute.

PIP Disabled p0 PIP is Off.

PIP Enabled p1 PIP is On.

Quit Telnet Session QT Quit the Telnet session and disconnect

Record Off R0 Recording of this session is Off.

Record On R1 Recording of this session is On.

Record Pause R2 Recording of this session is Paused.

Record Continue R3 Recording of this session is Continued.

Recording Contents, Primary

RC Get the current primary recording details (title, presenter, channel name, start time, duration and size).

Recording Contents, Primary

RC1 Get the current primary recording details (title, presenter, channel name, start time, duration and size).

Recording Contents, Dual RC2 Get the current dual recording details (title, presenter, channel name, start time, duration and size).

Record Disk RD Report disk information. Format is “u.uu t.tt”, with used space and total space in GB.




Record Empty Trash RE Remove all files from the trash can.

Record Filename RF Report the filename of the next file to be recorded. A blank entry means the name will be generated automatically. The filename will be reported without any extension and will be prefixed with a “>” character.

Record Filename RF,name Set the recording filename. This command must be executed before the recording has started. The “name” should not include the “.mp4” extension.

Record Filename, Primary RF1,name Set the recording filename for the Primary recording.

Record Filename, Dual RF2,name Set the recording filename for the Dual recording.

Recording Information RI,description Set description information for the current recording. This command must be executed after the current recording has started.

Recorded List RL Report list of recorded filenames. Each filename is returned as a single line with no extension and prefixed with a “>” character. All archives are reported, even if not yet ready and still being processed.

Recorded List with Descriptions

RL,SNFD... Report list of recorded filenames with descriptions. Eachlist item is prefixed with “>”. Descriptors available are S – status ( one of F=Ready, P=Processing, T=Transcoding, R=Recording, C=Captured, B=Blocked,X=Corrupted), N – filename, F - format (mp4), D – duration. Use descriptors in any order or combination. See Section 5.11 for full details on all descriptors available.

Remove Recording RM,pattern Remove all archive files matching “pattern”, where “*” may be used to match any filename, and “?” may be used as a wildcard to match any individual character.

Recording Presenter RP,presenter Set presenter information for the current recording. This command must be executed after the current recording has started.

Recording Title RT,title Set title information for the current recording. This command must be executed after the current recording has started.

Recording Upload RU,pattern Schedule an upload of the file(s) given by pattern.

Swap Main and PIP SW Swap the Main and PIP inputs

Subtitle with Duration s<duration>,<text> Add subtitle with duration in milliseconds

Subtitle with Auto-duration sa,<text> Add subtitle with auto-duration

Subtitle without Duration sn,<text> Add subtitle without duration

Subtitle end Duration s End last subtitle added with sn,<text> command

Text Variable Get TA – TJ Get custom text field A to J (format variables %0-%9).

Text Variable Set TA,text – TJ,text Set custom text field A to J (format variables %0-%9).

Upload Progress UP Returns upload progress (0-100%). See Section 5.8 .

PIP Input Composite V1 Enables PIP Input from Composite Input




PIP Input VGA V3 Enables PIP Input from VGA

PIP Input DVI-D V4 Enables PIP Input from DVI-D input

PIP Input DVI-A V6 Enables PIP Input from DVI-A input

PIP Input HDMI-1 V7 Enables PIP Input from HDMI-1 input

PIP Input Displayport V8 Enables PIP Input from Displayport

PIP Input 3G-SDI V9 Enables PIP Input from 3G-SDI input

PIP Input HDMI-2 V10 Enables PIP Input from HDMI-2 input

Video Signal VS Report the resolution and type of the video input signal: :1024x768p or :1280x720i or :0x0p (no signal)

Window Settings (main) W<F|L|R|

NW|NE|SW|SE|

A|B|C|D|E|F|G|H|I|J>

Set graphics main window to F=full-screen, L=left side, R=right side, NW=top-left corner, NE=top-right corner, SW=bottom-left corner, SE=bottom-right corner, A=Custom-1, B=Custom-2, C=Custom-3, D=Custom-4, E=Custom-5, F=Custom-6, G=Custom-7, H=Custom-8, I=Custom-9, J=Custom-10

Window Settings (main) W,x,y,w,h Set graphics main window to (x,y,w,h)

Window Position W<A|B|C|D|E|

F|G|H|I|J>,x,y,w,h

Set custom window (A|B|C|D|E|F|G|H|I|J) to position (x, y) and size width x height. The position and size can be given in percents (0-100 for x and y, 1-100 for w and h) or pixels (0-1600 for x, 0-1200 for y, 128-1600 for w, 128-1200 for h).

Window Settings (PIP) w<f|l|r|

nw|ne|sw|se|

a|b|c|d|e|f|g|h|i|j>

Set PIP window to f=full-screen, l=left side, r=right side, nw=top-left corner, ne=top-right corner, sw=bottom-left corner, se=bottom-right corner, a=Custom-1, b=Custom-2, c=Custom-3, d=Custom-4, e=Custom-5, f=Custom-6, g=Custom-7, h=Custom-8, i=Custom-9, j=Custom-10

Window Settings (PIP) w,x,y,w,h Set PIP window to (x,y,w,h)

Dual Input Selector - HDMI Y0 Enable Dual Input from HDMI-2

Dual Input Selector - SDI Y1 Enable Dual Input from 3G-SDI

Dual Signal YS Report the resolution and type of the dual input signal: :1920x1080p or :1280x720i or :0x0p (no signal)

Presentation Recorder Status

? Displays current status of the Presentation Recorder.

Presentation Recorder Status

?,x

?,xyz

Displays one or more status conditions where x or xyz represents one or more status variables.

Command Termination Character

<lf> Required as the terminating character of a command line. Hex 0x0a

Command Termination Character

<cr> Discarded. Hex 0x0d



4.2 COMMAND RESPONSES

Featured below is a table defining all command responses for the Serial Interface:

Response Type Response String Description

Status Response, current state of the controls followed by “*”

*G3,N:1, … Readout of the current status of the Presentation Recorder

Command Completion Acknowledgment by Presentation Recorder

+L1 Presentation Recorder generates a reply because of an executed command from interface; acknowledgment will be “+” followed by the command.

Error -C101 Error is a “-“ reply followed by the command. In this example, Channel 101 has been selected, which is invalid

Change in State ! Asynchronous interrupt from the Presentation Recorder indicates that a change in state has occurred, and a new status command must be issued.

Command Reply & A reply to the RS-232 interface from the Presentation Recorder indicating that a command has been received

Filename prefix > Prefix for an archive filename response from the RF, RL or RD commands.

Participant list prefix = Prefix used in response to a request for a participant list

Audio level prefix $ Prefix used in response to a request for audio levels

Identification Reply @NCast,<rev> Identification reply with software revision number

IP Address Reply #a.a.a.a,m.m.m.m,g.g.g.g,d.d.d.d

IP address reply, where a.a.a.a is the IP address of the unit, m.m.m.m is the netmask, g.g.g.g is the gateway and d.d.d.d is the DNS server

System Information Reply #s,a,r,d,m,f System information reply, where s=serial number, a=architecture, r=revision, d=date, m=microcontroller version, f=FPGA version

Resolution information :wxht Report frame/capture resolution and type

Custom Text Field Information ^text Return setting of custom text from TA-TJ

Upload Progress Indicator _%d Return percent of upload completed



4.3 COMMON PROBLEMS

Customers who “cannot get a response from the unit” should check the items listed below:

1. The RS-232 interface does not need to be activated. It is enabled when the system boots. The IP serial interface needs to be enabled from the telnet administrative web page. It uses a non-standard telnet port.

2. The serial interface runs at 38,400 bps and not the more common 9600 bps. The interface does not auto-sense speed, so the settings must be (38400, 8, N, 1).

3. The initial command to the unit MUST be the Identification “Id” command (e.g. “IdSerial,002<lf>” or “IdTelnet,002,pswd<lf>”). The unit will not respond until this command is received. See Section ?? below for additional information. (Note: uppercase eye, lowercase dee).

4. If testing the link from a Windows machine using Hyperterminal, note that the Enter key does not send therequired <lf> code. A Ctrl-J key will issue the required <lf> character.



5 Special Functions

5.1 PURPOSE

The following is an additional description on special commands from the interface.

5.2 IDENTIFICATION EXCHANGE

After initial power on the serial interface will wait for an Identification command. This informs the Presentation Recorder’s software of the type of controller (e.g. Serial, Crestron, AMX, PTZ camera, etc.) which is driving the interface and the software revision level. (Note: uppercase eye – lowercase dee).

Id<controller>,<rev>

The reply will be

@NCast,<rev>

Example:

Controller: IdSerial,002<lf>

PR-Hydra: &<lf>

PR-Hydra: @NCast,002<lf>

PR-Hydra: +IdSerial,002<lf>

For Telnet sessions the form of the command is

Id<controller>,<rev>,<password>

Example:

Controller: IdTelnet,002,my.favorite.password

5.3 SYSTEM INFORMATION

A command is available to retrieve system information including the system serial number and software revision levels. Example:

Controller: Is<lf> (Note: uppercase eye – lowercase es)

PR-Hydra: &<lf>

PR-Hydra: #serial,architecture,revision,date,micro,fpga<lf>

PR-Hydra: +Is<lf>

where

serial Serial number of the unit

architecture System hardware architecture

revision Software revision level

date Software revision date

micro Microcontroller software revision level

fpga FPGA code revision level



5.4 RESPONSE CODES

5.4.1 PRESENTATION RECORDER STATUS

As was described in Section 4, the Serial Interface will make requests for the current state of the Presentation Recorder. The “?<lf>” character requests from the Presentation Recorder the current status. Following this, a reply is sent via the Presentation Recorder indicating the command was received. In this case, the character would be “+?<lf>”. An example response acknowledging a readout of the current state would be an asterisk “*” followed by something similar to the following: "E:0,G3,C3,L1,M0,I1,S0,R0,T:N,V:0" The readout is translated as: Error code 0 (successful completion), Graphics Input is VGA, Channel 3, Loopback enabled, Mute off, Input active, not sending graphics, Receive off, this unit is not in Session, no passive Viewers.

The command “?,x<lf>” or “?,xy<lf>” or “?,xyz<lf>” will return individual status codes “x” or “x,y” or “x,y,z”.

In future revisions of this product or specification additional status information may be added. A controller must ignore unknown letter codes and skip the following data until the next “,” character or end of status.

Character Description

A<source>:<gain> Audio input <source>:<gain> 1=Mic, 2=Line, 3=USB, 4=XLR, 5=HDMI-1, 6=HDMI-2, 7=3G-SDI. Gain 0-100. For USB, HDMI, SDI gain fixed at 100.

aw:h Aspect ratio is w:h, e.g. a16:9

b<0|1> Border for PIP window: 0=Off, 1=On

C<num> Current channel number

cwxh Frame capture size is w (width) x h (height) in pixels, e.g. c1920x1080

D<0|1> USB stick indicator: 0=none, 1=USB available/inserted

d<0|1> Dual capture mode: 0=Off, 1=On

E:<num> The letter for the last error code is "E" followed by ":" and then an error code number. The codes in the status field are without the "-" sign.D_ERR_NO_ERROR 0D_ERR_INTERNAL_ERROR -1D_ERR_BAD_SYNTAX -2D_ERR_WRONG_PARAMETERS -3D_ERR_NO_SESSION -8D_ERR_RECORDING_IS_RUNNING -11D_ERR_RECORDING_IS_STOPPED -12D_ERR_RECORDING_IS_PAUSED -13D_ERR_PERMISSION_DENIED -14D_ERR_NO_SPACE -15D_ERR_NOT_SUPPORTED -16D_ERR_CONNECTION_ERROR -17D_ERR_TRANSFER_FAILED -21D_ERR_DIRECTORY_FAILED -22D_ERR_CANCELED -23

After successful command execution the error code is cleared. This means that after getting the current status with a "?" command, the next "?" always returns "E:0".

f<0|1|2> Full screen status (0=None, 1=Main, 2=PIP)

G<num> Selected graphics input, 1=Composite, 3=VGA, 4=DVI-D, 6=DVI-A, 7=HDMI-1, 8=Displayport, 9=3G-SDI, 10=HDMI-2

I<0|1> Main input signal state, 1 if a signal was correctly detected, 0 otherwise

J<0|1> PIP input signal state, 1 if a signal was correctly detected, 0 otherwise



K<0|1> Dual input signal state, 1 if a signal was correctly detected, 0 otherwise

L<0|1> Loopback state, 1 when loopback is on, 0 otherwise

M<0|1> Mute state, 1 when muted (no stream being sent), 0 otherwise

m<0|1> Audio meter Off or On.

m<nw|ne|sw|se> Audio meter position: nw=top-left, ne=top-right, sw=bottom-left, se=bottom-right

N:x Devices count

O0:<num> Output audio level, gain is in the range 0-100

O1:<num> Output loopback level, gain is in the range 0-100

o<1|2|3|4><0|1> Overlay graphics [1|2|3|4] is Off=0 or On=1 (enabled and visible).

p<0|1> PIP state, 0=Off, 1=On (enabled)

Q<0|1> Processing Queue Inactive=0, Active=1

R<0|1> Receiving and displaying a graphics stream, 1 when a stream is received and displayed, 0 otherwise. Note that when mute is on then a 0 will be returned here.

r<0|1|2> Record state: 0 if not recording, 1 if recording, 2 if paused.

S<0|1> Sending a graphics stream, 1 when a stream is being sent, 0 otherwise.

s<0|1> Local display swap state: Default state=0, Swapped=1. In the swapped state Main/PIP → VGA and Dual → HDMI Out. By default, Main/PIP → HDMI Out.

T:<A|L|N|R|S|T> Current role: ‘L’ – record only mode, ‘N’ – there is no session, ‘R’ – a streaming receiver, ‘S’ – a streaming sender, 'T' – RTMP streaming.

t<1|2|3|4><0|1> Text overlay [1|2|3|4] is Off=0, On=1 (enabled and visible).

U<0|1> Uploading Inactive=0, Active=1

u:x Upload status error code for last operation. Set to zero at start of the upload operation. 15 implies USB disk full.

V<num> Selected PIP input, 1=Composite, 3=VGA, 4=DVI-D, 6=DVI-A, 7=HDMI-1, 8=Displayport, 9=3G-SDI, 10=HDMI-2

V:<num> Number of passive viewers. Returned only when a streaming session is active.

Wx:y:w:h Main window (x,y) position and width x height

wx:y:w:h PIP window (x,y) position and width x height

xw:h Aspect ratio for Dual is w:h, e.g. x16:9

Y<1|2> Dual input state, 1=HDMI-2, 2=3G-SDI

zwxh Frame capture size for Dual is w (width) x h (height) in pixels, e.g. z1920x1080

5.4.2 ERROR REPORTS

The error function is the result of a reply from an invalid selection or request. For instance, if a user selects to view Channel 101 using the Serial Interface then it will generate an error as a request for Channel 101 is invalid. Therefore, in this instance an error will be reported with a “-“ followed by the function “-C101<lf>”. To determine the exact cause of the error via the error code, issue a status command.



5.4.3 ASYNCHRONOUS INTERRUPT

An Asynchronous Interrupt indicates that a change in state has occurred. This is useful for reporting status changes as a result of operations using the web interface. The character for reporting a change in state is “!<lf>”. The controller should issue a new status command to update its status conditions.

5.4.4 COMMAND EXECUTION ACKNOWLEDGMENT

Once new commands have been issued from the RS-232 Interface to the Presentation Recorder, an acknowledgment will be generated from the Presentation Recorder. This reply will only be generated by the Presentation Recorder in the case that the command was executed successfully. The reply for acknowledging a command will be “+” followed by the command. An example of this is the following: “+G1<lf>”. The readout is translated as successful execution of selection of Graphic Input Composite.

5.4.5 COMMAND REPLY

After commands are sent to the Presentation Recorder, an initial reply will be generated by the Presentation Recorder to indicate the command was received. This reply applies to all commands. An example of the command reply is as follows:

&<lf>

+C1<lf>

5.5 COMMANDS FOR CHANNEL CHANGE

The following commands change the Presentation Recorder to the requested channel and starts an active session with the new settings:

C<num>

or

C<num>,<role>

where

<num> stands for the channel number, 1 to the number of defined channels

<role> stands for what we want to do on a channel (A=Announce, RTSP Streaming, L=Local record, R=Receive, S=Stream, T=RTMP Streaming)

No other characters are permitted and there should be no spaces in this command string.

5.5.1 SELECT A CHANNEL

The following command

C1,N

will select a new channel, change layouts and apply other settings, but will not start a new Session.

5.5.2 BECOMING A STREAMING RECEIVER


C1,R

will configure the recorder to receive data from the settings of Channel 1.

5.5.3 BECOMING A STREAMING SENDER




C1,S

will initiate multicast streaming on Channel 1.

5.5.4 STARTING RTMP STREAMING


C1,T

will place Channel 1 in RTMP streaming mode.

5.5.5 COMMENCE LOCAL RECORDING


C1,L

will begin a record-only Session Channel 1.

5.5.6 CHANGING CHANNELS WITH DEFAULT CONDITIONS

C1

This command says: go to the channel, and activate the default channel settings. If it will be a streaming receive channel, the command is equal to C1,R. The Mute condition is set to Off by default for any channel change.

5.5.7 GETTING AND SETTING CHANNEL OPTIONS

Normally Channel settings and parameters are modified using the Channel Edit button on the Channels tab of theweb interface. Some of these settings may now be queried or modified using serial commands.

C<num>,option Queries or gets the value or state of a Channel option

C<num>,option,value Sets the value of a Channel option

The following options may be set/queried with this command:

name

type

dual_capture (0/1)

auto_start

slave_auto_start

video_format

video_bitrate_1, video_bitrate_2

video_framerate_1, video_framerate_2

audio_format

recording (0/1)

max_recording_time

frame_size_1,w,h , frame_size_2,w,h

aspect_ratio_1x,y , aspect_ratio_2,x,y

main_window

pip_window



pip

auto_upload

remove_after_upload

start_auto_upload

upload_protocol or upload_protocol_1

ftp_server or ftp_server_1

ftp_port or ftp_port_1

ftp_username or ftp_username_1

ftp_password or ftp_password_1

ftp_upload_directory or ftp_upload_directory_1

ftp_anonymous_login or ftp_anonymous_login_1

ftp_upload_xml or ftp_upload_xml_1

ftp_upload_kl_df_xml or ftp_upload_kl_df_xml_1

sftp_server or sftp_server_1

sftp_port or sftp_port_1

sftp_username or sftp_username_1

sftp_password or sftp_password_1

sftp_upload_directory or sftp_upload_directory_1

sftp_upload_xml or sftp_upload_xml_1

sftp_upload_kl_df_xml or sftp_upload_kl_df_xml_1

usb_upload_directory or usb_upload_directory_1

usb_upload_xml or usb_upload_xml_1

upload_protocol_2

ftp_server_2

ftp_port_2

ftp_username_2

ftp_password_2

ftp_upload_directory_2

ftp_anonymous_login_2

ftp_upload_xml_2

ftp_upload_kl_df_xml_2

sftp_server_2

sftp_port_2

sftp_username_2

sftp_password_2

sftp_upload_directory_2

sftp_upload_xml_2

sftp_upload_kl_df_xml_2



usb_upload_directory_2

usb_upload_xml_2

For example, “C1,name,Video Presentation<lf>” will modify the Channel's name. Use text strings similar to those entered on the web interface as values.

5.6 PROGRAM BEGIN, STARTING A SESSION

The command to start a Session is “PB” or “Program Begin”. The Session parameters used will be taken from the last Channel which was activated or selected on the web interface. This command allows operators to select a Channel from the web interface and then start/stop it using a very simple serial controller which might only have a single start/stop button. Commands “C1”, “C2”, etc., would normally be used for complete activation of a Channel with loading of all required Session parameters and layouts.

5.7 PROGRAM END, ENDING A SESSION

The command to end a Session is “PE” or “Program End”. This operation is equal to Stop Session on the web interface. The box will disengage from all multicast groups.

5.8 UPLOAD PROGRESS

The UP command allows for reporting of file transfer progress during file uploads or transfer to an external USB drive. The status returned may be used to update a progress bar or other indicator for the user. Some USB file transfers may be lengthy and transfer progress will keep the user from disconnecting the USB drive prematurely.

Please note the following items while using this command:

• The format returned is “_%d” (underscore followed by percent of transfer as an integer).

• Prior to retrieving upload progress you have to check the upload status (?,U command) to know whether upload is active or not.

• When the upload finishes progress goes back to 0. It doesn't stop at 100.

5.9 POWER DOWN, SHUTDOWN

To invoke a “Power Shutdown” use command “PS”. It ends the session, and shuts down the Presentation Recorder. There is an additional command “PSI” which waits until the unit is idle (transcoding and uploading is finished).

5.10 LOOPBACK: L0, L1

The Loopback command sets the variable Loopback to TRUE or FALSE. This will cause the display to go into local loopback mode if set to TRUE. Local loopback display generation consumes CPU resources and should not be used if absolute peak performance is required.

5.11 RECORDING COMMANDS

There are a group of commands which control or affect the recording process and the creation of archive files:

R0 Stop recording

R1 Start recording

R2 Pause recording

R3 Continue recording

The Channel must be enabled for manual or automatic recording for these commands to have effect.



The RL command returns a list of all archive files, even those not in the Ready state:

RL

&

>20051110-045140-001

>20051110-045202-001

>20051110-045205-001

>20051110-045208-001

>20051110-045210-001

+RL

The “>” is a command response prefix and is not part of the filename.

An alternate form of the RL command uses descriptors (S, N, F, D, ...):

RL,SNF

will return:

>F,20090305-150858-022.wmv,wmv

while:

RL,ND

will return:

>20090305-150858-022.wmv,00:30:00

where the following descriptors are available:

• S – the current status of the file:F = Finished or ReadyP = Processing (multiplexing of video and audio)T = Transcoding to another format or resolutionC = Captured and waiting for processingR = Recording and not yet complete

◦ B = Blocked, awaiting free archive spaceX = Corrupted, some error occurred with the file

• N – filename with extension• F – format (mp4)• D – duration as HH:MM:SS• T – title• P – presenter• C – channel name• R – start time as YYYY-MM-DD HH:MM:SS• L – size in MB• A – audio format (aac)• V – video format (mpeg4, h264)• s – frame size as WxH• a – aspect ratio as W:H• b – bitrate in kbps• f – framerate

The filename of the next archive file to be created may be set with the RF command. This command must be issued prior to the start of recording:

RF,filename



&

+RF,filename

Do not include the .mp4 extension. An RF command with no argument returns the current filename. A blank filename implies that the filename will be generated automatically:

RF

&

>filename

+RF

To set title information for the presentation detail file, use the RT command after recording has commenced:

RT,title info about the current presentation

To setup information about the current presenter or speaker associated with the recording, use the RP command after recording has commenced:

RP,John Smith – CEO

Set description information for the current recording. This command must be executed after the current recording has started:

RI,description

Recording information may be retrieved with the RC command:

RC

&

>Discussion on Presentation Recorder Features

>NCast CEO

>Streaming 1

>2006-04-10 07:15:51

>00:00:05

>0.04

+RC

Starting from the top it lists:

- title

- presenter

- channel name

- start time as YYYY-MM-DD HH:MM:SS

- duration as HH:MM:SS

- size in MB

Recording(s) may be uploaded with the RU command:

RU,pattern Uploads all files matching “pattern” ( * matches any string, ? Matches a character )

Recordings may be removed with the RM command:

RM,* Removes all archive files

RM,test* Removes all archive files starting with “test”

RM,20051111* Removes all archives created on 11 Nov 2005.



Disk space available for recording will be reported with the RD command:

RD

&

>0.00 111.78

+RD

Where the first number is space used in GB, and the second number is space available in GB.

The RE command empties the Trash Can to clear archive file space. The Trash is usually automatically emptied to make space at the beginning of a recording session. Permits complete deletion of confidential files.

5.12 AUDIO LEVEL COMMANDS

There are three commands which allow remote readout of the audio meter levels. This will permit easy monitoringof audio activity on the Presentation Recorder from a centralized control point or network operations room.

ma – Report all audio levels (local left, local right, net left, net right):

ma

&

$-26.6,-36.0,-100.0,-100.0

+ma

ml – Report local audio levels (left, right):

ml

&

$-26.6,-35.9

+ml

mn – Report network audio levels (left, right):

mn

&

$-100.0,-100.0

+mn

All levels are reported in a dB scale (maximum value is 0.0 dB, minimum is –100.0 dB). Power is calculated separately for the local and net streams and for the left and right channels. The power is calculated over 1024 samples regardless of the selected audio format.

The calculation used is as follows:

Denote the samples as:

s(1), s(2), s(3), ..., s(1024)

where

-32768 <= s(i) <= 32767

First we calculate the absolute maximum of samples:

ams = max(abs(s(1)), abs(s(2)), ..., abs(s(1024)))

Then final power in a dB scale:

if ams == 0 (this can happen for net stream)



power = -100.0

else

power = 10 * log10((ams*ams) / (32768 * 32768))

In last line the smallest value we can get is:

10 * log10(1/(32768*32768)) = -90.308998

and largest value is:

10 * log10((32768*32768)/(32768*32768)) = 0.000

5.13 SUBTITLE COMMANDS

There does not appear to be a single, widely adopted standard for recording timed-event information for use either in sub-titles or chaptering. Some client players use various forms of .txt files and others use .xml files.

The Presentation Recorder implementation has adopted one format which is simple to use and has some existingsupport in the open-source community and works with several players.

The format is an ".srt" text file type which you may read about here:

http://en.wikipedia.org/wiki/SubRip

New serial commands have been added to receive text information and automatically create ".srt" files during a recording.

These files will be:

Available on the Archives page for download

Available for download via our http interface

Uploaded automatically via the FTP upload service

Upon receipt of this file a program can easily extract the timing information of interest and create a web page with playback start points of interest. For example, Quicktime uses the "STARTTIME" parameter:

http://www.apple.com/quicktime/tutorials/embed2.html

<embed src="sample.mp4" width="320" height="240" starttime="00:15:22.5">

There are four serial commands which deal with subtitles:

sa,text - adds a subtitle with auto-duration, where the subtitle duration is based on the number of characters in “text”, for example:

sa,This is test subtitle

sduration,text - adds a subtitle with given duration in msec. The duration must be > 0, for example:

s250,This is test subtitle

sn,text - adds a subtitle without duration. The subtitle will end when the next subtitle command is passed or recording is stopped, for example:

sn,This is first subtitle

s - ends last subtitle

All commands work in real-time, as the subtitles are synchronized to what is seen on the screen.

For chaptering we suggest use of the sn,text command like this:

sn,Chapter 1

sn,Chapter 2



sn,Chapter 3

...

After recording is finished and there is at least one subtitle, an .srt subtitle file is created which can be downloaded from the web-page or HTTP interface. The .srt format is very simple, this example has two subtitles:

100:00:20,000 --> 00:00:24,400Subtitle 1

200:00:24,600 --> 00:00:27,800Subtitle 2

Here is an example using the "sn" command only to record the timing of overlay pushbuttons using small Python application:

100:00:07,281 --> 00:00:07,281Overlay 1 is 0

200:00:08,776 --> 00:00:08,776Overlay 1 is 1 300:00:10,769 --> 00:00:10,769Overlay 2 is 1

400:00:12,745 --> 00:00:12,745Overlay 2 is 0

500:00:14,738 --> 00:00:14,738Overlay 3 is 1



6 Sample Code

6.1 JAVA PROGRAM EXAMPLE

Java is a language which is often available by default on many PCs. It's easy to use this language to create a serial interface application. The Hydra Management System (Java Edition) provides a comprehensive example of procedures which address the serial interface over the Telnet IP link.

Please check the website for the latest version:

http://www.ncast.com/ncastdocuments.html


http://www.ncast.com/ncastdocuments.html


7 Revision History

Revision 1.3 – Added YS command reporting signal input resolution and type for dual input.

Revision 1.2 – Added GS and VS commands reporting signal input resolution and type.

Revision 1.1 – Added LS0/LS1 commands for display output swap. Added “s” swap state status.

Revision 1.0 – Initial release for Presentation Recorder Hydra, software revision 9.0.0.


ncast serial interface specification · ncast presentation recorder serial interface specification...

Documents