EEVid Command Line Utility

eevid is a command line utility for discovering, controlling, and capturing data from EEVideo cameras.
eevid 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.
eevid is offered under the permissive MIT open source license and can be buit and modified by users.
eevid is built on the goEEVideo libraries that are also available as open source.

Installing eevid

Download Binary and Extract

Download the release archive file and extract

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

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

Example file list after extraction

eevideo$ ls -al
total 8604
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
-rw-rw-r--   1 group user 2619728 date time eevid_v0.0.5_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

eevideo> dir


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


Mode                 LastWriteTime         Length Name
----                 -------------         ------ ----
-a----         date        time               206 eevconfig.yaml
-a----         date        time           6446592 eevid.exe
-a----         date        time           2707112 eevid_v0.0.5_windows_amd64.zip
-a----         date        time              1094 LICENSE
-a----         date        time              1984 README.md

The latest binary list is available here.

No installation is required.

Discovering Devices

Run discovery

Check for EEVideo devices on the network.

eevideo$ ./eevid disc

eevideo> .\eevid.exe disc

Typical response when a device is found

Using config file: /home/user/Path/To/eevideo/devices/eevconfig.yaml
discovery called
Wrote Device file: devices/(DeviceModelName)_(UserDefinedName)_(SerialNumber)_(Last3IP).yaml

Using config file: C:\Users\User\Path\To\eevideo\devices\eevconfig.yaml
discovery called
Wrote Device file: devices\(DeviceModelName)_(UserDefinedName)_(SerialNumber)_(Last3IP).yaml

Typical response when no device is found

Error during device discovery
  Error EEV DiscDevices: Error while discovering devices
  Error EEV getDiscResponses: No responses received.

Error during device discovery
  Error EEV DiscDevices: Error while discovering devices
  Error EEV getDiscResponses: No responses received.

Power up the device and connect it to the network.
Run eevid disc

eevid disc will report each EEVideo device found on the network.

IP Addresses

Many EEVideo devices are delivered pre-programmed with a static IP address set to 10.xx.xx.xx . Communicating with these devices requires the host NIC to have its own address assigned in the 10.xx.xx.xx/8 range (net-mask 255.0.0.0).

The static IP address of the EEVideo device can be changed to fit in the current host NIC address range. EEVideo devices may also get an IP address from a DHCP server if no static address is assigned and a DHCP server is active on the network.

Reassigning host NIC addressing and EEVideo device static addresses is outside the current scope of eevid.

Discovery Results

Device Files

Look for device files

eevideo$ ls ./devices

eevideo> dir .\devices\

As devices are discovered, eevid disc queries each device for its capabilities. These available capabilities and features of the device are compared to the EEVideo specification and master features list. Then a file is built with all the key information on the device, its capabilities, and the register addresses of all its features.

This way the time consuming discovery process is not required for each EEVideo management transaction. All the discovered information is stored for re-use. If a device is updated or its network location is changed, discovery can be re-run.

By default, these device files are stored in the ‘devices’ sub-directory.

If there is only a single device file in that directory, the EEVideo tools will default to that device. If more that one device file exists, the correct one may be selected from a terminal prompt, command line flag, or setting in the ’eevconfig.yaml’ file.

The device files are readable ASCII ‘*.yaml’ files, but typically a user is not required to open or understand them.

Reading and Writing Registers

Run eeevid reg

Read Register 0

eevideo$ ./eevid reg

eevideo> .\eevid.exe reg

Typical response

Using config file: /home/user/Path/To/eevideo/eevconfig.yaml
reg called
Read register 0x0 returned 0xe71d8001

Using config file: C:\Users\User\Path\To\eevideo\eevconfig.yaml
reg called
Read register 0x0 returned 0xe71d8001

The eevid reg command can read and write internal registers of the EEVideo device.

Without any options, eevid reg reads register 0. Register 0 of all EEVideo devices is required to report some ID characters and capability bits.

Validate Scratchpad Register

Check test0 register description

eevideo$ ./eevid reg -n test0_Description

eevideo> .\eevid.exe reg -n test0_Description

Typical results

Using config file: /home/user/Path/To/eevideo/eevconfig.yaml
reg called
Info: Register test0_Description is Scratchpad

Using config file: C:\Users\User\Path\To\eevideo\eevconfig.yaml
reg called
Info: Register test0_Description is Scratchpad

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 of eevid reg.

Read Test0 Register

Read the test0 register value

eevideo$ ./eevid reg -n test0_reg

eevideo> .\eevid.exe reg -n test0_reg

Typical results

Using config file: /home/user/Path/To/eevideo/eevconfig.yaml
reg called
Register        test0_reg = 0x0
Fields:
   byte0: 0x0
   byte1: 0x0
   byte2: 0x0
   byte3: 0x0
     lsb: 0x0
     msb: 0x0

Using config file: C:\Users\User\Path\To\eevideo\eevconfig.yaml
reg called
Register        test0_reg = 0x0
Fields:
   byte2: 0x0
   byte3: 0x0
     lsb: 0x0
     msb: 0x0
   byte0: 0x0
   byte1: 0x0

The address of this register is stored in the device file. eevid reg is able to use register names using the -n flag.

Write Test0 Register

Write the test0 register with a value

eevideo$ ./eevid reg -n test0_reg -v 0x12345678

eevideo> .\eevid.exe reg -n test0_reg -v 0x12345678

Typical results

Using config file: /home/user/Path/To/eevideo/eevconfig.yaml
reg called
Wrote register test0_reg to 0x12345678

Using config file: C:\Users\User\Path\To\eevideo\eevconfig.yaml
reg called
Wrote register test0_reg to 0x12345678

The -v flag indicates the eevid reg command is a write.

Read -n test0_reg again (as above) to verify write functionality.

Write Test0 Register Fields

Write a test0 register field with a value

eevideo$ ./eevid reg -n test0_reg -f lsb=1

eevideo> .\eevid.exe reg -n test0_reg -f lsb=1

Typical results

Using config file: /home/user/Path/To/eevideo/eevconfig.yaml
reg called
Register        test0_reg = 0x12345679
Fields:
   byte2: 0x56
   byte3: 0x79
     lsb: 0x1
     msb: 0x0
   byte0: 0x12
   byte1: 0x34

Using config file: C:\Users\User\Path\To\eevideo\eevconfig.yaml
reg called
Register        test0_reg = 0x12345679
Fields:
     lsb: 0x1
     msb: 0x0
   byte0: 0x12
   byte1: 0x34
	 byte2: 0x56
	 byte3: 0x79

The -f flag also indicates the eevid reg command is a write.

The test register feature includes several defined fields to support field functionality testing.

After writing a field you can re-run the read command to verify how field relationships work.

Capturing Video Frame Data

Run eevid cap

Capture 10 frames from Stream 0.

eevideo$ ./eevid cap

eevideo> .\eevid.exe cap

Typical response

Using config file: /home/user/Path/To/eevideo/eevconfig.yaml
cap called
Listening for EEVideo stream on IP:10.0.0.234:56765
Capture completed

Using config file: C:\Users\User\Path\To\eevideo\eevconfig.yaml
cap called
Listening for EEVideo stream on IP:10.0.0.234:56765
Capture completed

The eevid cap command is a simple way to validate EEVideo camera device streams.

Complete frames of uncompressed format data are stored in RAW binary files without any header information or useful file extension. If a Motion JPEG stream is being captured, the compressed frames will be saved as individual JPEG files.

These RAW files may be viewable with apps capable of interpreting raw data. One option is ‘ffplay’ which is part of the ‘ffmpeg’ package. Configuring the ‘ffplay’ command depends on the stream data format and is beyond the scope of this quick-start. JPEG files are typically viewable with a photo viewer application.

Stream Number Selection and Capture Count

Capture 3 frames from Stream 1.

eevideo$ ./eevid cap -n stream1  -c 3

eevideo> .\eevid.exe cap -n stream1 -c 3

Typical response

Using config file: /home/user/Path/To/eevideo/eevconfig.yaml
cap called
Listening for EEVideo stream on IP:10.0.0.234:56765
Capture completed

cap called
Listening for EEVideo stream on IP:10.0.0.234:56765
Capture completed

The stream number can be specified using the --streamNum (of -n) flag. This is done using the word “stream” followed by the number, (e.g. stream1). The number of image files captured is controllable using the --frameCount (or -c) flag value. The default is 10.

Image File Path and File Naming

Capture 10 frames from a Motion JPEG stream on Stream 1 to ./images/test with provided imageName and verbose level 1.

eevideo$ ./eevid cap -n stream1 -i .\images\test\ -f test_640x480 --verbose 1

eevideo> .\eevid.exe cap -n stream1 -i .\images\test\ -f test_640x480 --verbose 1

Typical response

Using config file: /home/user/Path/To/eevideo/eevconfig.yaml
cap called
Info EEV ReadDeviceYAML: Using Device YAML file "devices/(DeviceModelName)_(UserDefinedName)_(SerialNumber)_(Last3IP).yaml"
Listening for EEVideo stream on IP:10.0.0.243:56765
Info EEV saveImage: Saved frame 1 to images\test\frame_01_test_640x480.jpg
Info EEV saveImage: Saved frame 2 to images\test\frame_02_test_640x480.jpg
Info EEV saveImage: Saved frame 3 to images\test\frame_03_test_640x480.jpg
Info EEV saveImage: Saved frame 4 to images\test\frame_04_test_640x480.jpg
Info EEV saveImage: Saved frame 5 to images\test\frame_05_test_640x480.jpg
Info EEV saveImage: Saved frame 6 to images\test\frame_06_test_640x480.jpg
Info EEV saveImage: Saved frame 7 to images\test\frame_07_test_640x480.jpg
Info EEV saveImage: Saved frame 8 to images\test\frame_08_test_640x480.jpg
Info EEV saveImage: Saved frame 9 to images\test\frame_09_test_640x480.jpg
Info EEV saveImage: Saved frame 10 to images\test\frame_10_test_640x480.jpg
Info EEV ImgCapture: Capture completed successfully
Capture completed
Stream stream1 stopped

Using config file: C:\Users\User\Path\To\eevideo\eevconfig.yaml
cap called
Info EEV ReadDeviceYAML: Using Device YAML file "devices/(DeviceModelName)_(UserDefinedName)_(SerialNumber)_(Last3IP).yaml"
Listening for EEVideo stream on IP:10.0.0.243:56765
Info EEV saveImage: Saved frame 1 to images\test\frame_01_test_640x480.jpg
Info EEV saveImage: Saved frame 2 to images\test\frame_02_test_640x480.jpg
Info EEV saveImage: Saved frame 3 to images\test\frame_03_test_640x480.jpg
Info EEV saveImage: Saved frame 4 to images\test\frame_04_test_640x480.jpg
Info EEV saveImage: Saved frame 5 to images\test\frame_05_test_640x480.jpg
Info EEV saveImage: Saved frame 6 to images\test\frame_06_test_640x480.jpg
Info EEV saveImage: Saved frame 7 to images\test\frame_07_test_640x480.jpg
Info EEV saveImage: Saved frame 8 to images\test\frame_08_test_640x480.jpg
Info EEV saveImage: Saved frame 9 to images\test\frame_09_test_640x480.jpg
Info EEV saveImage: Saved frame 10 to images\test\frame_10_test_640x480.jpg
Info EEV ImgCapture: Capture completed successfully
Capture completed
Stream stream1 stopped

By default, the image files are stored in the ‘images’ sub-directory with the extension ‘.raw’ or ‘.jpg’. If you want to provide a different system path and/or file name, the --imagePath and --imageName flags (short flags -i and -f respectively) can be provided with flag values. The default image name is “frame_NN_W_H.ext”, i.e. frame number (NN), width (W), height (H), and file extension (ext). If the --imageName flag value is supplied, then the image name will be “frame_NN_<imageNameValue>.ext” instead.

The files should all be the same size for streams using an uncompressed format. File size should equal:
(pixels per line) * (lines per frame) * ((bits per pixel) / (8 bits per byte)).
Example: 640 * 480 * (16/8) = 614,400 (for a 640 width, 480 height, YUV422_8_UYVY pixel format)

The data in the raw files should match packet payload data captured by Wireshark or other Ethernet bus analyzers. Test pattern streams are very helpful for analyzing the bytes in raw files.

Setting Max Packet Size

Capture 10 frames from Stream 0 using a negotiated packet size.

eevideo$ ./eevid cap -m 0

eevideo> .\eevid.exe cap -m 0

Typical response

Using config file: /home/user/Path/To/eevideo/eevconfig.yaml
cap called
Info EEV StreamMaxPktSize: PacketSize size negotiated to 8000
Listening for EEVideo stream on IP:10.0.0.234:56765
Capture completed

Using config file: C:\Users\User\Path\To\eevideo\eevconfig.yaml
cap called
Info EEV StreamMaxPktSize: PacketSize size negotiated to 8000
Listening for EEVideo stream on IP:10.0.0.234:56765
Capture completed

The --maxPacket (or -m) flag value effectively sets the size for each stream packet from the device. A few smaller packets are expected with each frame. The ability to receive the packets is affected by the MTU (Maximum Transmission Unit) size setting of the NIC (Network Interface Card), typically found in the NIC driver settings in Windows or Network Configuration in Linux. The MTU is typically set to 1500 in most systems by default. The system MTU size must be equal or above the --maxPacket flag value in order to receive stream packets. This relates to what is commonly called Jumbo Frames which has a maximum value of 9014 bytes in systems/drivers. Therefore, for practical implementations, the --maxPacket flag should use a value between 200-9000, as supported by the system. Larger packet sizes generally reduce network overhead and increase performance. The receive buffer size for the NIC can also degrade performance if it configured incorrectly in relation to the provided --maxPacket size.
Additionally, a value of 0 will perform packet size negotiation starting at 9000 to the largest size within 100 bytes. If a negotiated value isn’t found than the MaxPacketSize will be set to 1000 on the device.

Manually Stopping the Stream

Stop a video stream.

eevideo$ ./eevid cap --stop

eevideo> .\eevid.exe cap --stop

Typical response

Using config file: /home/user/Path/To/eevideo/eevconfig.yaml
cap called
stream0 stopped

Using config file: C:\Users\User\Path\To\eevideo\eevconfig.yaml
cap called
stream0 stopped

Using the eevid cap command starts the stream for the provided stream number --streamNum (or -n) and then stops it upon completion. If there is an error and the stream isn’t stopped automatically, you can use the --stop flag to simply stop the provided stream number from streaming.

Device Updating

Run eevid prog

Program the device’s eevideo features (assumes EEV NVM Feature is implemented)

eevideo$ ./eevid prog -p .\flash -n eevid.bin

eevideo> .\eevid.exe prog -p .\flash -n eevid.bin

Typical response

Using config file: /home/user/Path/To/eevideo/eevconfig.yaml
prog called
Info: Provided Filename: eevid.bin
Opening file flash\eevDev_A02_eevid.bin
Working file erase, starting at address 0x160000, 1400 bytes
Info EEV SPIeraseBlocks: Erasing 1 block(s)
 100% |████████████████████████████████████████|
Erase Done
 100% |████████████████████████████████████████|  [0s:0s]
 Programming complete

Using config file: C:\Users\User\Path\To\eevideo\eevconfig.yaml
prog called
Info: Provided Filename: eevid.bin
Opening file flash\eevDev_A02_eevid.bin
Working file erase, starting at address 0x160000, 1400 bytes
Info EEV SPIeraseBlocks: Erasing 1 block(s)
 100% |████████████████████████████████████████|
Erase Done
 100% |████████████████████████████████████████|  [0s:0s]
 Programming complete

The eevid prog command provides a way to program accessible Non-Volatile Memory (NVM) devices attached to the EEVideo device. This allows updates to areas such as the device’s EEVideo Features List, user data, or device firmware. The contents of the programming file (typically a binary file) will be written and verified during the programming process.

The prog command also looks for NVM device information defined in the EEVideo Feature List. It attempts to procure and check the region name, starting address, maximum region size, and chip select.

The --binName (or -n) flag value must be provided. It can be part of the file name and/or NVM region name.

This is used along with the --binPath (or -p) flag (which defaults to the current directory) to specify the programming file system location.

Using Dry-Run to Check Programming Settings

Using the ‘–dry-run’ Flag

eevideo$ ./eevid prog -p .\flash -n eevid.bin --dry-run

eevideo> .\eevid.exe prog -p .\flash -n eevid.bin --dry-run

Typical response

Using config file: /home/user/Path/To/eevideo/eevconfig.yaml
prog called
Info: Provided Filename: eevid.bin
Info: Dry-run, configured to program flash\eevDev_A02_eevid.bin to address 0x160000,
      Bus: SPI, Chip Select: 0, AddrSize: 3 bytes

Using config file: C:\Users\User\Path\To\eevideo\eevconfig.yaml
prog called
Info: Provided Filename: eevid.bin
Info: Dry-run, configured to program flash\eevDev_A02_eevid.bin to address 0x160000,
      Bus: SPI, Chip Select: 0, AddrSize: 3 bytes

Use the --dry-run flag to verify settings without programming the NVM device. Items reported are what file will be used, the starting device address for writing, the device bus (i.e. SPI), chip select, and the number of address bytes.

Additionally, you can use the --rdid flag to read the device ID of an attached SPI Flash Device.

Binary File Revision

Specify the Binary File Revision

eevideo$ ./eevid prog -p .\flash -n eevid.bin --dry-run -r A01

eevideo> .\eevid.exe prog -p .\flash -n eevid.bin --dry-run -r A01

Typical response

Using config file: /home/user/Path/To/eevideo/eevconfig.yaml
prog called
Info: Provided Filename: eevid.bin
Info: Dry-run, configured to program flash\eevDev_A01_eevid.bin to address 0x160000,
      Bus: SPI, Chip Select: 0, AddrSize: 3 bytes

Using config file: C:\Users\User\Path\To\eevideo\eevconfig.yaml
prog called
Info: Provided Filename: eevid.bin
Info: Dry-run, configured to program flash\eevDev_A01_eevid.bin to address 0x160000,
      Bus: SPI, Chip Select: 0, AddrSize: 3 bytes

The --rev (or -r) flag may optionally be provided to specify the revision to be used that is part of the programming file name. This is specified between the first pair of underscores in the filename. For example, if one file in the binPath folder is named “eevDev_A01_eevid.bin” and another file is named “eevDev_A02_eevid.bin”, you could use --rev A01 to program the lower rev version. If the --rev flag is not provided, the highest rev file name in the folder will be used.

Specifying the Starting Address

Specify the Starting Address

eevideo$ ./eevid prog -p .\flash -n eevid.bin --dry-run -a 0x1E0000

eevideo> .\eevid.exe prog -p .\flash -n eevid.bin --dry-run -a 0x1E0000

Typical response

Using config file: /home/user/Path/To/eevideo/eevconfig.yaml
prog called
Info: Provided Filename: eevid.bin
Warning: Provided address 0x1E0000 doesn't match region address 0x160000
Info: Dry-run, configured to program flash\eevDev_A02_eevid.bin to address 0x1E0000,
      Bus: SPI, Chip Select: 0, AddrSize: 3 bytes

Using config file: C:\Users\User\Path\To\eevideo\eevconfig.yaml
prog called
Info: Provided Filename: eevid.bin
Warning: Provided address 0x1E0000 doesn't match region address 0x160000
Info: Dry-run, configured to program flash\eevDev_A02_eevid.bin to address 0x1E0000,
      Bus: SPI, Chip Select: 0, AddrSize: 3 bytes

Using the --addr (or -a) flag value, a programming start address can be specified. This must be provided if the device’s EEVideo Features List doesn’t include NVM device information. Otherwise, if provided, it will override the starting address procured from the NVM Feature List while additionally printing a warning.

NVM Device Parameters

Providing NVM parameters

eevideo$ ./eevid prog -n eevid.bin --dry-run -c 0 -s 3 -d 0

eevideo> .\eevid.exe prog -n eevid.bin --dry-run -c 0 -s 3 -d 0

Typical response

Using config file: /home/user/Path/To/eevideo/eevconfig.yaml
prog called
Info: Provided Filename: eevid.bin
Info: Dry-run, configured to program flash\eevDev_A01_eevid.bin to address 0x160000,
      Bus: SPI, Chip Select: 0, AddrSize: 3 bytes

Using config file: C:\Users\User\Path\To\eevideo\eevconfig.yaml
prog called
Info: Provided Filename: eevid.bin
Info: Dry-run, configured to program flash\eevDev_A01_eevid.bin to address 0x160000,
      Bus: SPI, Chip Select: 0, AddrSize: 3 bytes

The --cs (or -c) flag is used to specify the chip select number for the device on the bus (default is 0). The value used is system architecture dependent. The --addrSize (or s) flag is used to specify the NVM device’s address byte size (default is 3). This number is NVM device dependent. Additionally, the NVM Device number can be provided, using the --nvmDev (or -d) flag, as it relates the NVM Feature List (default is 0). Typically the defaults should be used.