Skip to main content
Skip table of contents

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 
JavaScript errors detected

Please note, these errors can depend on your browser setup.

If this problem persists, please contact our support.