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:
|
Encoder:X### | Value must be one of the following options:
|
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:
|
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:
The device name must be one of the following options (See Rayfin Software for a full list):
|
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:
|
NtpServer | Get the address of the currently configured NTP Server. |
SystemDateTime | Get the current date and time of the system. |
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 |
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:
|
LogDataOnStill:XXX | Sets whether to log data when a still is taken. Value must be one of the following options:
|
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
|
Example 2 - Set Stills Settings |
CODE
|
Example 3 - Set Exposure |
CODE
|
Example 4 - Dynamically Adjust the Focus |
CODE
|
Example 5 - Switch to Auto Exposure and Take 10 Stills 1 Minute Apart |
CODE
|
Example 6 - Change the Video Name, Start Recording, and Take 3 Pictures 6 Seconds Apart |
CODE
|
Example 7 - Record 20 Seconds of Video Every 20 Seconds, Take a Picture Every 5 Seconds. Repeat Indefinitely |
CODE
|
Example 8 - When Recording, Enable Manual Exposure |
CODE
|
Example 9 - Start Continuous Stills at 11:00 |
CODE
|
Example 10 - Start Recording when depth exceeds 2000m |
CODE
|
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
// 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