EEVLark Scripting Utility

eevlark is a command line utility for excuting Python-like script of commands to configure, control, and monitor EEVideo cameras.
eevlark is written in Go and available as pre-compiled binaries for several operating systems and processors. This enables testing on PCs then implementation on embedded system SoCs.
eevlark is offered under the permissive MIT open source license and can be buit and modified by users.
eevlark is built on the goEEVideo libraries that are also available as open source.

Prerequisite : eevid disc

To enable eevlark, first install and run eevid disc to discover the EEVideo devices on the network. Look here for the eevid installation instructions.

eevid disc will create device files for all discovered devices in the devices sub-directory. eevlark uses those device files to initiate communication with the EEV devices.

If there is only one device file, eevlark will use it by default. If there is more than one, use the --deviceName and --devicePath flags on the command line or in ’eevconfig.yaml’ file. If no flags are found, eevlark will list the available devices and request a selection.

Installing eevlark

Download Binary and Extract

Download the release archive file and extract (use the same directory as eevid)

cd eevideo
curl -O -L https://gitlab.com/eevideo/eevlark/-/releases/v0.0.8/downloads/eevlark_v0.0.8_linux_amd64.tar.gz
tar -xzf eevlark_v0.0.8_linux_amd64.tar.gz

cd eevideo
curl.exe -L -o eevlark_v0.0.8_windows_amd64.zip "https://gitlab.com/eevideo/eevlark/-/releases/v0.0.8/downloads/eevlark_v0.0.8_windows_amd64.zip"
Expand-Archive -Path "$PWD\eevlark_v0.0.8_windows_amd64.zip" -DestinationPath "$PWD" -Force

Example file list after extraction

eevideo$ ls -al
total 17932
drwxrwxr-x   2 group user    4096 date time .
drwxr-x---+ 38 group user    4096 date time ..
-rw-rw-r--   1 group user     206 date time eevconfig.yaml
-rwxr-xr-x   1 group user 6164642 date time eevid
-rwxr-xr-x   1 group user 5705314 date time eevlark
-rw-rw-r--   1 group user 2619728 date time eevid_v0.0.5_linux_amd64.tar.gz
-rw-rw-r--   1 group user 2836594 date time eevlark_v0.0.6_linux_amd64.tar.gz
-rw-rw-r--   1 group user    1094 date time LICENSE
-rw-rw-r--   1 group user    1984 date time README.md
drwxrwxr-x   1 group user    4096 date time scripts

eevideo> dir


    Directory: C:\Users\User\Path\To\eevideo\


Mode                 LastWriteTime         Length Name
----                 -------------         ------ ----
d-----         date        time                   scripts
-a----         date        time               219 eevconfig.yaml
-a----         date        time           6799872 eevid.exe
-a----         date        time           2815670 eevid_v0.0.7_windows_amd64.zip
-a----         date        time           7078912 eevlark.exe
-a----         date        time           2961780 eevlark_v0.0.7_windows_amd64.zip
-a----         date        time              1068 LICENSE
-a----         date        time              1655 README.md

Look here for the latest eevlark binary packages.

No installation is required.

Script Examples

The eevlark download includes a few example scripts in the scripts subfolder.

Not all of them are useful for all EEVideo devices. Some are included as examples to be customized.

Sample file details TBD

Reading and Writing Registers

Read Test0 Register

Run the reg_rw.py script to Read and Write the test0 register value

eevideo$ ./eevlark -s reg_rw.py

eevideo> .\eevlark.exe -s reg_rw.py

Typical results

Using config file: /home/user/configs/eevconfig.yaml
/home/user/configs/devices/
Initializing device /home/user/configs/devices/
0x0
{"byte1": 0, "byte2": 0, "byte3": 0, "lsb": 0, "msb": 0, "byte0": 0}
Writing  register test0_reg: map[byte3:51]
Writing  register test0_reg: map[byte2:34]
Writing  register test0_reg: map[byte1:17]
Writing  register test0_reg: map[byte0:170]

Using config file: C:\Users\User\Path\To\eevideo\eevconfig.yaml
C:\Users\User\configs\devices\
Initializing device C:\Users\User\configs\devices\/
0x0
{"byte1": 0, "byte2": 0, "byte3": 0, "lsb": 0, "msb": 0, "byte0": 0}
Writing  register test0_reg: map[byte3:51]
Writing  register test0_reg: map[byte2:34]
Writing  register test0_reg: map[byte1:17]
Writing  register test0_reg: map[byte0:170]

Test registers are one of the optional features that may be included in EEVideo devices.

Many EEVideo devices offer a scratchpad test register named “test0”, but it is not required. The purpose of a scratchpad register is communication testing like we are performing here. No device functionality is affected by reading or writing this register.

If the test0_Description = “Scratchpad” then it can be used for testing the read and write functionality

The address of this register is stored in the device file, in this case “test0_reg”. The eevlark ‘reg_rg.py’ script is able to use the register name in the read_register() and write_register() function calls.

The test register feature includes several defined “byte#” fields to support field functionality testing.

Other EEVideo device registers may be read and written following the example in the script.

Built-In Functions

EEVideo Functions

eevlark extends the base functionality of Starlark with several EEVideo specific commands.

InitDevice

init_device(devicePath&Filename, verbose_level) initializes communication with a target EEVideo device. It loads the device configuration from the discovered device files created by eevid disc and establishes the connection for subsequent commands. This is typically the first function called in a script. It can accept optional parameters for device name or path if multiple devices are present. Proper initialization is required before using any hardware-specific functions like register access or streaming.

ReadRegister

read_register(addr_name) reads a value from a device register at the specified address. It returns the register value, which can be used for status checking, configuration verification, or debugging. The address is usually provided as an integer (often in hex). This low-level access allows scripts to inspect hardware state directly. Results are often printed or stored in variables for further processing.

WriteRegister

write_register(addr_name, field_value) writes a specified value to a device register at the given address. It is used to configure hardware settings, enable features, or change operating modes. Both address and value are typically integers. This function provides direct control over the device’s low-level behavior. Scripts commonly use it after InitDevice to set up the camera or peripherals.

ReadI2C

read_i2c(busNum, addr, length) reads one or more bytes from the I2C peripheral register. It returns the read data for inspection or processing. This is useful for querying sensor status, reading chip IDs, or retrieving configuration values. The function supports variable read lengths depending on the peripheral requirements.

ReadI2cAddr

read_i2c_addr(busNum, i2c_dev_addr, addr, length) performs a combined write-then-read operation on an I2C device (register address write followed by data read). It is the standard way to read from devices that require a register pointer first. This builtin simplifies interaction with most I2C sensors and peripherals. The returned data can be parsed or logged within the script.

WriteI2C

write_i2c(busNum, i2c_dev_addr, addr, bytes_val) writes data to an I2C device on a specified bus at the given slave address. The data can be a single byte or a list of bytes for register configuration. It is commonly used to program sensors, serializers, or other I2C peripherals attached to the EEVideo hardware. This function enables flexible external hardware control from scripts.

StreamCapture

stream_capture(stream_num, dest_port, delay, max_pkt_size, frame_count, image_path, image_name) captures a specified number of frames or images from the active video stream. Captured data is typically saved to the configured image/output directory. It is useful for grabbing stills or short bursts for testing and validation. The function works in conjunction with an active stream and respects the global frame count settings when applicable.

StreamStart

stream_start(stream_num, dest_port, delay, max_pkt_size) starts video streaming on the specified stream (e.g., “stream0”). It activates the camera pipeline and begins outputting video data over Ethernet. This function is essential before performing captures or live viewing. Optional parameters may allow configuration of stream-specific settings.

StreamStop

stream_stop(stream_num) stops the video stream on the specified stream number. It cleanly shuts down the streaming pipeline and releases associated resources. This helps prevent unnecessary network traffic and power consumption when streaming is no longer needed. It is the counterpart to StreamStart.

Misc Functions

Sleep

sleep(ms) pauses script execution for the specified number of milliseconds. It is commonly used to allow hardware time to settle after register writes, I2C transactions, or stream start commands. This builtin helps create reliable timing sequences in automation scripts. It accepts an integer value representing milliseconds.

Keyboard

keyboard(status_msg) provides interactive input handling or key-event monitoring within scripts. It enables scripts to respond to user key presses for menus, pausing, or manual control during execution. This makes scripts more interactive during development and testing. It is particularly useful for long-running or demonstration scripts. An optional status message can be provided and overwrittten after each keypress or set to "" if not needed.

Command Help

Run eevlark -h

eevideo$ ./eevlark -h

eevideo> .\eevlark.exe -h

Typical response

eevlark accepts a text file containing a Python like Starlark syntax
script and executes selected functions on a Embedded Ethernet
Video Device (camera).

Usage:
  eevlark [flags]

Flags:
      --config string       config file (default is $HOME/eevconfig.yaml)
      --deviceName string   Name of eev device file to use
      --devicePath string   Path to directory containing eev device files (default "./devices/")
  -c, --frameCount int      Number of images or frames to capture (default 10)
  -h, --help                help for eevlark
  -f, --imageName string    File name for captured image(s)
  -i, --imagePath string    File system location to save captures (default "./images/")
  -s, --scriptName string   Filename of script to run (default "test.py")
  -p, --scriptPath string   Path to script directory (default "./scripts")
  -n, --streamNum string    Stream number to control/view for stream commands (default "stream0")
      --verbose int         verbose output level
  -v, --version             version for eevlark

The eevlark --help (or -h) command lists all the available command flags with brief descriptions.

Flag values may also be stored in ’eevconfig.yaml’ so they do not all need to be provided for every call. Flags on the command line take precedence over the same command in ’eevconfig.yaml'.