Rayfin Scripting API for v3

The Rayfin supports the ability to write scripting files to program your camera to perform complex tasks. Scripts are written in the Rayfin Scripting Language (RSL) which utilizes SubC’s Rayfin API. Flexible, real-time programs can be created that utilize all of the camera’s features.

This article contains a list of many of the scripting commands that can be used with Rayfin as well as some examples. Commands are case-sensitive.

Video Settings

Script Line	Description
Preset:XXX##	Preset resolution that video will be recorded at. Value must be one of the following options: UHD30 (4K video at 30 fps) FHD30 (1080p HD video at 30 fps)
Encoder:X###	Value must be one of the following options: H264 H265
Bitrate:###	Sets the video encoding (1-100)
VideoName:name	Set a name for the video file. This must be done before a video is taken.
VideosDirectory:/name	Create and name the folder where video will be saved after they have been recorded.
StartRecording	Start a video recording.
StopRecording	Stop a video recording.

Digital Stills

Script Line	Description
ImageFormat:XXXX	Preset format that stills will be saved in. Value must be one of the following options: RAW (Stills taken will be saved in RAW format) JPEG (Stills taken will be saved in JPEG format)
JPEGQuality:###	Sets the JPEG Compression percentage. This should only be done if the image format is set to JPEG. Value must be within the specified range. (25 - 100)
StillName:name	Set a name for the digital still. This must be done before a still is taken.
StillsDirectory:/name	Create and name the folder where stills will be saved after they are taken.
TakeStill	Take a digital still.
TakeStill:HH-mm-ss	Take a digital still at the specified time.

Continuous Digital Stills

Script Line	Description
BurstRate:#	The frequency of continuous stills in Hz. Value must be within the specified range. (1 - 4)
BurstDirectory:/name	Create and name the folder where continuous stills will be saved after they are taken.
StartContinuous	Start taking continuous stills.
StopContinuous	Stop taking continuous stills.

Exposure Settings

Script Line	Description
AutoExposure	Sets the Exposure setting to Automatic.
ManualExposure	Sets the Exposure setting to Manual.
ExposureValue:###	Sets the Exposure value when in manual mode. Value must be within the specified range. (-12 - +12)
UpdateISO:###	Sets the ISO value. Value must be within the specified range. (50 - 3200)
UpdateShutterSpeed:###	Sets the Shutter Speed value. Value must be within specified range. (15000 - 500000000) nanoseconds
UseNearestShutter:False	Use this command to allow setting of shutter speed to any value. When true shutter speed will be clamped to pre-defined settings.
LockShutter:#	When in AutoExposure the shutter speed is locked to a preset value. AutoExposure adjusts ISO only. (30 or 60)
UnlockShutter	Releases the AutoExposure shutter lock
IsShutterLocked	Returns true if shutter is locked.

Lens

Script Line	Description
AutoFocus	Sets the Focus to automatic.
ManualFocus	Sets the Focus to manual.
UpdateFocus:###	Sets the Focus value when in manual mode. Value must be within the specified range. (0.1 - 15)
FocusNear	Moves the Focus one full step nearer. Only available when Focus is in manual.
FocusFar	Moves the Focus one full step farther. Only available when Focus is in manual.
FocusDistance	Returns the current focus value
Zoom:##.#	Sets the Zoom value. Value must be within the specified range. (1.0 - 10.0)

Aux Ports and Devices

Script Line	Description
Device:#,deviceName	Sets the specified aux port to the specified device. The port number must be one of the following options: 0 (Specifies Aux 0) 1 (Specifies Aux 1) The device name must be one of the following options (See Rayfin Software for a full list): Aquorea Mk3 TTL Laser Controller
EnableStrobe	Enables the Strobe function.
DisableStrobe	Disables the strobe function.
LampBrightness:###	Only relevant if Aquorea Mk3 is connected to the Rayfin. Sets the brightness of an Aquorea Mk3. Value must be within the specified range. (0 - 100)
ExposureStops:###	Sets the exposure shift that occurs when taking a still with strobe enabled. Value must be within the specified range. (-12 - +12)
LaserBrightness:###	Only relevant if Skate Mk2 is connected to the Rayfin. Sets the brightness of a Skate Mk2. Value must be within the specified range. (0 - 100)
SerialAddress:SUBC#####	If more than one Aquorea Mk3 is attached to the system, enter the serial number of one of the LEDs to enable individual control of the specified LED.
ClearSerialAddress	If one Aquorea Mk3 is being individually controlled, this command resets the system to control both LEDs at once.

Timing Functions

All commands have a 1000ms parsing time which should be accounted for in your timing.

Script Line	Description
ClockMode	Get the clock mode. Returns one of the following: Manual Auto
NtpServer	Get the address of the currently configured NTP Server.
SystemDateTime	Get the current date and time of the system. During scripting you may use the following in conditional statements: SystemDateTime.Hour, SystemDateTime.Minute, SystemDateTime.Second
EnableNtp:{NTP server},{TimeZone},{force}	Sets ClockMode to Auto and configures time.google.com as the NTP server. Sets the system time zone to America/St_Johns. The final argument forces this change even if the NTP address appears to be invalid. For the last argument you should submit “true”
EnableNtp:{NTP server},{force}	Sets ClockMode to Auto and configures time.google.com as the NTP server. The final argument forces this change even if the NTP address appears to be invalid.
SetDateTime:yyyy/MM/dd HH:mm:ss.fff	Sets the ClockMode to Manual and sets the current date and time of the system.
SetTime:########,{TimeZone}	Sets the ClockMode to Manual and sets the current date and time of the system according to the first argument that specifies the number of seconds since the unix epoch. Sets the system time zone to America/St_Johns.
SetTime:########	Sets the ClockMode to Manual and sets the current date and time of the system according to the first argument that specifies the number of seconds since the unix epoch.
SetTimeZone:{TimeZone}	Sets the system time zone to America/St_Johns.
TimeZone	Returns the current time zone of the system.
SystemTimeMillis	Returns the system date and time in the format MM/dd/yyyy - HH-mm-ss.fff
WaitFor:####	Delays the script for a specified period of time in milliseconds.
WaitFor:hh:mm:ss	Delays the script for a specified period of time in hours:minutes:seconds.

Repeat and Concurrent Functions

Script Line	Description
Repeat:command1\|command2\|#	Perform several commands that will happen a specified number of times. (Use -1 for infinity)
Concurrent	Allows multiple repeating functions to happen simultaneously.
StopConcurrent	Encapsulates the concurrent functions.

When Conditional Function

Conditional statements can be used for advanced functions, see provided scripts for usage examples. The “When” function is checked each time a function changes to see if the condition is met.

Script Line	Description
When:condition\|command	Sets a condition and performs the command when the condition is met.

RTSP IP Video

Script Line	Description
UpdateRTSP: Resolution, Bitrate	Resolution: 720x480, 1280x720, 1920x1080, 3840x2160 Bitrate: [1 - 100] Kbps

Expansion Board

Script Line	Description
IsFaulted	This function will return True if in a fault state.
Off:#	Turns off the specified breaker. Value must be within the specified range. (1 - 4)
On:#	Turns on the specified breaker. Value must be within the specified range. (1 - 4)

Data Logging

Script Line	Description
Altitude	Gets the altitude if sensor is connected.
Depth	Gets the depth if sensor is connected.
Tilt	Gets the tilt of the camera.
Roll	Gets the roll of the camera.
SetIMUZero	Sets the IMU zero point to current.
ResetIMU	Resets the IMU zero point to default.
StartLogging	Starts data logging to CSV.
StopLogging	Stops data logging.
LogDataOnRecording:XXX	Sets whether to log data when a video recording is started. Value must be one of the following options: True False
LogDataOnStill:XXX	Sets whether to log data when a still is taken. Value must be one of the following options: True False
RecordingLogInterval:##	Sets the interval between which each log point. Value must be within the specified range. (1 - 10)
IsLogging	Returns True if the system is logging data.

Debug

Script Line	Description
FormatMedia	Deletes all of the content in the Media folder.
LoadScript:XXXXX.rsl	Loads the specified script.
ExecuteScript	Executes the loaded script.
IsScriptRunning	Returns True if a script is running.
Script	Returns the file name of the loaded script.
StopScript	Stops the script that is currently executing.
HDMIPowerOff	Turns off the connected HDMI device.
HDMIPowerOn	Turns on the connected HDMI device.
Reboot	Performs a soft reboot of the Rayfin operating system.
Firmware:XXXXX	Firmware commands can be entered here for advanced device controls.
IsSerialConnected	Query the App to see if the microcontroller is running
ConfigureSerial	Reconnect the microcontroller to the App
AutoConfigureSerial:#	(0 - 600). For noisy environments and long duration deployments. Checks if micro is connected to the App and if it isn’t, auto reconnects it. Default is 0, disabled.

Script Examples

There are example scripts pre-installed on the Rayfin and on the USB stick that is delivered with the product.

Example 1 - Record for 1 Minute

CODE

StartRecording
WaitFor:60000
StopRecording

Example 2 - Set Stills Settings

CODE

ImageFormat:RAW
EnableStrobe
StillName:stop-motion${yyyy}-${MM}-${dd} - ${hh}${mm}${ss}

Example 3 - Set Exposure

CODE

ManualExposure
ISO:100
ShutterSpeed:8000000

Example 4 - Dynamically Adjust the Focus

CODE

AutoExposure
AutoFocus
WaitFor:2000
ManualFocus

Example 5 - Switch to Auto Exposure and Take 10 Stills 1 Minute Apart

CODE

AutoExposure
Repeat:TakeStill|WaitFor:60000|10

Example 6 - Change the Video Name, Start Recording, and Take 3 Pictures 6 Seconds Apart

CODE

VideoName:StillsTest
StartRecording
Repeat:TakeStill|WaitFor:5000|3
StopRecording

Example 7 - Record 20 Seconds of Video Every 20 Seconds, Take a Picture Every 5 Seconds. Repeat Indefinitely

CODE

Concurrent
Repeat:StartRecording|WaitFor:20000|StopRecording|WaitFor:20000|-1
Repeat:TakeStill|WaitFor:5000|-1
StopConcurrent

Example 8 - When Recording, Enable Manual Exposure

CODE

When:IsRecording|ManualExposure

Example 9 - Start Continuous Stills at 11:00

CODE

When:SystemDateTime.Hour = 11|StartContinuous

Example 10 - Start Recording when depth exceeds 2000m

CODE

Encoder:H264
VideoName:Depth2000 ${yyyy}-${MM}-${dd} - ${hh}${mm}${ss}
ClearWhen
TakeStill
When:Depth > 2000 AND IsRecording = False|StartRecording
Repeat:WaitFor:60000|StopRecording|-1

Detailed Scripting Example

In this example, we are recording while running on battery power. The camera will keep recording until it runs out of storage or battery, whichever happens first.

Decrease the Lamp Brightness to increase the battery life.

If battery power was lost during a recording, that recording may become corrupted

CODE

// Set Aux Devices to Aquore Mk3
SetDevice:0,Aquorea Mk3
SetDevice:1,Aquorea Mk3
// Set to 4K preset
Preset:UHD30
// Recording bitrate. This can be manually adjusted.
Bitrate:100

// Set the encoder to H265, this results in higher quality video
Encoder:H265
VideoName:battery_record ${yyyy}-${MM}-${dd} - ${hh}${mm}${ss}

// Set Exposure to Auto (Can also be set to manual)
AutoExposure

// Flash the LEDs to indicate the script has started. Each command has a 1 second delay
LampBrightness:5
LampBrightness:0
LampBrightness:5
LampBrightness:0

// Record until battery runs out.
LampBrightness:100
ClearWhen
When:IsRecording = False|StartRecording
StartRecording