JeVois  1.5
JeVois Smart Embedded Machine Vision Toolkit
Share this page:
Command-line interface user guide

Command-line interface overview

In addition to interacting with your JeVois camera through a video capture software, you can also use any of two available serial ports:

  • Hardware serial port through the 4-pin connector on the smart camera (see above).
  • Serial-over-USB port that appears to your host computer at the same time as the video camera appears on the serial bus.

You, or another machine (e.g., an Arduino) can connect to JeVois and issue simple commands to the smart camera. These commands allow one to tune camera parameters, vision processing parameters, and general operation of the JeVois smart camera.

Things you can do with the JeVois command-line interface include:

  • adjust contrast, exposure, gain, white balance, etc of the camera sensor.
  • show basic information about JeVois, such as free RAM memory, CPU frequency, CPU temperature.
  • adjust machine vision parameters, depending on which vision module is currently loaded and running. Many machine vision modules expose parameters for thresholds, operating modes, etc which you can tune using the JeVois command-line interface.
  • run a script that contains any number of valid commands.
  • decide where to send output and log serial messages (to the hardware serial port, to serial-ver-USB, to both, or to none).
  • examine available video modes and machine vision algorithms, and select a particular one.
  • possibly execute custom commands that may be provided by a particular machine vision module.
Note
Note that by default, command echo is turned off, which means that, when you connect to JeVois over a serial link, you will not see what you type. This is to avoid sending back to an Arduino all the commands it might want to send to the JeVois camera. Most serial communication software have an option to "turn on local echo" which will allow you to see what you type but will be handled by your serial terminal program as opposed to having JeVois send back all the characters you type.
Because the command-line interface is mainly intended for machine-to-machine communication, no editing capability is provided at this point. That means that if you type an incorrect character and try to delete it, both the incorrect character and then the delete character will be sent to JeVois, and your command will just fail. If you have a tendency to make many typos as you type, just type your commands in any editor of your choice, and then simply copy and paste them into the JeVois command-line interface.

Follow these instructions to connect to JeVois using serial-over-USB:

Note
When running JeVois software in host mode, you can simply interact with JeVois by typing commands directly in the terminal window from which you started jevois-daemon. See The jevois-daemon executable for more details.

Command-line interface getting started

Once connected, you can use the command-line interface. Supported commands, general operation parameters, and camera sensor controls are as follows (further detailed in the following sections):

help - print help message
info - show system information including CPU speed, load and temperature
setpar <name> <value> - set a parameter value
getpar <name> - get a parameter value(s)
runscript <filename> - run script commands in specified file
setcam <ctrl> <val> - set camera control <ctrl> to value <val>
getcam <ctrl> - get value of camera control <ctrl>
listmappings - list all available video mappings
setmapping <num> - select video mapping <num>, only possible while not streaming
setmapping2 <CAMmode> <CAMwidth> <CAMheight> <CAMfps> <Vendor> <Module> - set no-USB-out video mapping defined on the fly, while not streaming
ping - returns 'ALIVE'
serlog <string> - forward string to the serial port(s) specified by the serlog parameter
serout <string> - forward string to the serial port(s) specified by the serout parameter
usbsd - export the JEVOIS partition of the microSD card as a virtual USB drive
sync - commit any pending data write to microSD
restart - restart the JeVois smart camera

General Options:
  --tracelevel (unsigned int) default=[0]
    Set the minimum trace level to display
       Exported By: engine

  --loglevel (jevois::manager::LogLevel) default=[info] List:[fatal|error|info|debug]
    Set the minimum log level to display
       Exported By: engine

Engine Options:
  --serout (jevois::engine::SerPort) default=[None] List:[None|All|Hard|USB]
    Send module serial messages to selected serial port(s)
       Exported By: engine

  --camreg (bool) default=[false]
    Enable raw access to camera registers through setcamreg and getcamreg
       Exported By: engine

  --cpumax (unsigned int) default=[1344] List:[120|240|312|408|480|504|600|648|720|816|912|1008|1044|1056|1080|1104|1116|1152|1200|1224|1248|1296|1344]
    CPU maximum frequency in MHz
       Exported By: engine

  --serlog (jevois::engine::SerPort) default=[None] List:[None|All|Hard|USB]
    Show log and debug messages on selected serial port(s)
       Exported By: engine

  --cpumode (jevois::engine::CPUmode) default=[Performance] List:[PowerSave|Conservative|OnDemand|Interactive|Performance]
    CPU frequency modulation mode
       Exported By: engine

AVAILABLE CAMERA CONTROLS:

- brightness [int] min=-3 max=3 step=1 def=0 curr=0
- contrast [int] min=0 max=6 step=1 def=3 curr=3
- saturation [int] min=0 max=4 step=1 def=2 curr=2
- autowb [bool] default=1 curr=0
- dowb [int] min=0 max=1 step=1 def=0 curr=1
- redbal [int] min=0 max=255 step=1 def=128 curr=125
- bluebal [int] min=0 max=255 step=1 def=128 curr=151
- autogain [bool] default=1 curr=1
- gain [int] min=16 max=1023 step=1 def=16 curr=58
- hflip [bool] default=0 curr=0
- vflip [bool] default=0 curr=0
- powerfreq [menu] values 0:disabled 1:50hz 2:60hz curr=2
- sharpness [int] min=0 max=32 step=1 def=6 curr=6
- autoexp [menu] values 0:auto 1:manual curr=0
- absexp [int] min=1 max=1000 step=1 def=1000 curr=500
- presetwb [menu] values 0:manual 1:auto 2:incandescent 3:fluorescent 4:fluorescent_h 5:horizon 6:daylight 7:flash 8:cloudy 9:shade curr=1

Additional parameters and additional commands may be available depending on which machine vision module is currently loaded. For example, the SaveVideo module allows two new commands, start (to start recording video to disk) and stop (to stop recording to disk). It also brings in a few new options which are specific to video encoding. When this module is loaded (by selecting the corresponding video resolution in your camera viewer software), typing help will show these new sections:

PARAMETERS:

Video Saving Options:  
  --fourcc (string) default=[MJPG] Regex:[^\w{4}$]
    FourCC of the codec to use. The OpenCV VideoWriter doc is unclear as to which codecs are supported. Presumably, the ffmpeg library is used inside OpenCV. Hence any video encoder supported by ffmpeg should work. Tested codecs include: MJPG, MP4V, AVC1. Make sure you also pick the right filename extension (e.g., .avi for MJPG, .mp4 for MP4V, etc)
       Exported By: SaveVideo

  --fps (double) default=[30]
    Video frames/sec as stored in the file and to be used during playback
       Exported By: SaveVideo

  --filename (string) default=[video%06d.avi]
    Name of the video file to write. If path is not absolute, /jevois/data/savevideo/ will be prepended to it. Name should contain a printf-like directive for one int argument, which will start at 0 and be incremented on each streamoff command.
       Exported By: SaveVideo

and

MODULE-SPECIFIC COMMANDS:

start - start saving video
stop - stop saving video and increment video file number

Command-line interface usage

Commands are case-sensitive and must be entered exactly as shown here. Because the command-line interface is mostly for use by machines (e.g., an Arduino) and to optimize speed, as mentioned above only very minimal forgiveness for typos and other deviations from the required command format are tolerated.

Serial communication types

JeVois distinguishes between two types of serial communications:

1) serlog: For log messages (error messages, notices to users, etc). Log messages are categorized into severity tiers, and always start with DBG (for debug level), INF (info level), ERR (error level), or FTL (fatal error level).

2) serout: For text-based outputs intended to be consumed by a machine (e.g., coordinates of an object detected by JeVois, to send to an Arduino).

The assignment of actual ports, such as hardware 4-pin connector vs serial-over-USB port, to serlog and serout is controlled by parameters, detailed below. The assignment is very flexible, for example, you can decide to send serlog messages to both the 4-pin hardware serial port and to the serial-over-USB port, or or to no port, or to just one port, etc while sending serout messages to the hardware 4-pin serial port only, or all ports, no ports, etc.

Command-line general behavior

When a command is received by the JeVois engine on a given serial port, it is executed and any output is sent back to that same serial port.

All successful commands end with a final line that says

OK

Failed commands issue some error message instead, which always starts with ERR, such as:

ERR Unsupported command

Many commands do not produce any additional outputs, and hence only return either a line that says OK or one that starts with ERR.

Command-line end-of-line markers

The default end-of-line behavior for JeVois is sloppy which consists of:

  • on input (strings sent to JeVois), any of CR (0x0d or [\r]), LF (0x0a or [\n]), CRLF, 0xd0 (issued by some keyboards instead of Return), or 0x00 [\0] are accepted as valid end-of-line markers. Characters received up to the end-of-line marker and exclusive of it will be considered one command which will be parsed and executed.
  • for outputs (strings sent by JeVois), the JeVois camera issues CRLF end of line characters.

This is configurable upon startup of the JeVois smart camera. Please see the jevois::serial::linestyle parameter of jevois::Serial for details. Note, however, that this paremeter becomes hidden after JeVois has started. Hence, you can only change serial end-of-line behavior through the initscript.cfg script that is executed upon boot up of the JeVois smart camera. See The jevois-daemon executable for details.

Command-line general commands and parameters

General commands always available irrespective of which vision module is loaded are described here.

help - print help message

Prints the help message. The help message is sent to the serial port that issued the help command only.

info - show system information including CPU speed, load and temperature

Shows some vital information about the JeVois smart camera:

INFO: JeVois 1.1
INFO: Linux version 3.4.39
INFO: CPU: 1344MHz, 32C, load: 1.02 1.01 0.86 1/50 83
INFO: MemTotal: 238452 kB, MemFree: 194292 kB
INFO: OUT: YUYV 640x300 @ 60fps CAM: YUYV 320x240 @ 60fps MOD: JeVois:DemoSaliency
OK

setpar <name> <val> - set a parameter value

For example, the command

setpar cpumax 1200

returns

OK

and a subsequent command

info

would show the updated CPU frequency of 1200 MHz:

INFO: JeVois 1.1
INFO: Linux version 3.4.39
INFO: CPU: 1200MHz, 31C, load: 1.00 1.01 0.89 1/50 83
INFO: MemTotal: 238452 kB, MemFree: 194292 kB
INFO: OUT: YUYV 640x300 @ 60fps CAM: YUYV 320x240 @ 60fps MOD: JeVois:DemoSaliency
OK

getpar <name> - get a parameter value(s)

The answer to this command consists of the parameter name followed by the current parameter value. For example, the command

getpar cpumax

returns (assuming the parameter has just been set to 1200 as above)

cpumax 1200
OK

runscript <filename> - run script commands in specified file

Runs a script, which is just a file that contains commands in exactly the same format as they would be typed interactively over the command-line interface. If the filename is not absolute (does not start with a / symbol), then the filename is assumed to be relative to the location of the currently-loaded vision module.

setcam <ctrl> <val> - set camera control <ctrl> to value <val>

Set a camera control. The help message gives a list of available camera controls and their permitted values. Beware that some controls are not effective in some modes, for example, you should turn autoexp (auto exposure control) off before you try setting a value to absexp (manual exposure value).

For example

setcam autogain 0
setcam gain 232

getcam <ctrl> - get value of camera control <ctrl>

For example, following the above setcam commands, issuing

getcam gain

would return

gain 232
OK

Note that sometimes the camera sensor hardware will modify values given through setcam, for example round them off, clip them, etc and getcam allows you to get back the value that was actually set into the sensor chip.

listmappings - list all available video mappings

Lists all the video mappings, which define the associations between a camera image size, frame rate, and pixel format, a USB output image size, frame rate, and pixel format, and which machine vision module to run. The definitions of mappings are in the videomappings.cfg file. The listmappings command allow you to obtain the numerical index of a given mapping in the list, shich you can later use with the setmapping command. For example:

listmappings

may return a list like (depending on the contents of videomappings.cfg)

AVAILABLE VIDEO MAPPINGS:

    0 - OUTPUT: NONE 0x0 @ 0fps CAMERA: YUYV 320x240 @ 60fps) MODULE: SaveVideo
    1 - OUTPUT: NONE 0x0 @ 0fps CAMERA: YUYV 320x240 @ 30fps) MODULE: RoadNavigation
    2 - OUTPUT: NONE 0x0 @ 0fps CAMERA: YUYV 320x240 @ 30fps) MODULE: SaveVideo
    3 - OUTPUT: NONE 0x0 @ 0fps CAMERA: YUYV 176x144 @ 120fps) MODULE: SaveVideo
    4 - OUTPUT: RGGB 640x480 @ 30fps CAMERA: RGGB 640x480 @ 30fps) MODULE: PassThrough
    5 - OUTPUT: RGGB 352x288 @ 60fps CAMERA: RGGB 352x288 @ 60fps) MODULE: PassThrough
    6 - OUTPUT: RGGB 176x144 @ 120fps CAMERA: RGGB 176x144 @ 120fps) MODULE: PassThrough
    7 - OUTPUT: MJPG 352x288 @ 60fps CAMERA: RGGB 352x288 @ 60fps) MODULE: Convert
    8 - OUTPUT: MJPG 320x240 @ 60fps CAMERA: RGBP 320x240 @ 60fps) MODULE: Convert
    9 - OUTPUT: MJPG 176x144 @ 120fps CAMERA: RGGB 176x144 @ 120fps) MODULE: Convert
   10 - OUTPUT: RGBP 320x240 @ 22fps CAMERA: YUYV 320x240 @ 22fps) MODULE: DemoGPU
   11 - OUTPUT: YUYV 960x240 @ 30fps CAMERA: YUYV 320x240 @ 30fps) MODULE: DemoNeon
   12 - OUTPUT: YUYV 640x312 @ 50fps CAMERA: YUYV 320x240 @ 50fps) MODULE: DemoSalGistFaceObj
   13 - OUTPUT: YUYV 640x300 @ 60fps CAMERA: YUYV 320x240 @ 60fps) MODULE: DemoSaliency
   14 - OUTPUT: YUYV 640x300 @ 10fps CAMERA: YUYV 320x240 @ 10fps) MODULE: BurnTest
   15 - OUTPUT: YUYV 352x288 @ 60fps CAMERA: YUYV 352x288 @ 60fps) MODULE: SaveVideo
   16 - OUTPUT: YUYV 320x288 @ 30fps CAMERA: YUYV 320x240 @ 30fps) MODULE: SaliencySURF
   17 - OUTPUT: YUYV 320x286 @ 30fps CAMERA: YUYV 320x240 @ 30fps) MODULE: DemoQRcode
   18 - OUTPUT: YUYV 320x260 @ 30fps CAMERA: YUYV 320x240 @ 30fps) MODULE: DemoArUco
   19 - OUTPUT: YUYV 320x256 @ 30fps CAMERA: YUYV 320x240 @ 30fps) MODULE: RoadNavigation
   20 - OUTPUT: YUYV 320x254 @ 60fps CAMERA: YUYV 320x240 @ 60fps) MODULE: ObjectTracker
   21 - OUTPUT: YUYV 320x252 @ 30fps CAMERA: YUYV 320x240 @ 30fps) MODULE: ObjectDetect
   22 - OUTPUT: YUYV 320x240 @ 60fps CAMERA: YUYV 320x240 @ 60fps) MODULE: SaveVideo
   23 - OUTPUT: YUYV 320x240 @ 30fps CAMERA: YUYV 320x240 @ 30fps) MODULE: SaveVideo
   24 - OUTPUT: YUYV 320x120 @ 30fps CAMERA: YUYV 160x120 @ 30fps) MODULE: DemoBackgroundSubtract
   25 - OUTPUT: YUYV 176x160 @ 120fps CAMERA: YUYV 176x144 @ 120fps) MODULE: RoadNavigation
   26 - OUTPUT: YUYV 176x144 @ 120fps CAMERA: YUYV 176x144 @ 120fps) MODULE: SaveVideo
   27 - OUTPUT: YUYV 160x120 @ 60fps CAMERA: YUYV 160x120 @ 60fps) MODULE: SaveVideo
   28 - OUTPUT: YUYV 88x72 @ 120fps CAMERA: YUYV 88x72 @ 120fps) MODULE: SaveVideo
   29 - OUTPUT: YUYV 64x192 @ 25fps CAMERA: YUYV 320x240 @ 25fps) MODULE: SalientRegions
   30 - OUTPUT: GREY 320x960 @ 45fps CAMERA: YUYV 320x240 @ 45fps) MODULE: EdgeDetectionX4
   31 - OUTPUT: GREY 320x240 @ 59fps CAMERA: YUYV 320x240 @ 59fps) MODULE: EdgeDetection
   32 - OUTPUT: GREY 320x240 @ 30fps CAMERA: YUYV 320x240 @ 30fps) MODULE: SuperPixelSeg
   33 - OUTPUT: GREY 176x288 @ 100fps CAMERA: YUYV 176x144 @ 100fps) MODULE: OpticalFlow
   34 - OUTPUT: GREY 176x144 @ 120fps CAMERA: YUYV 176x144 @ 120fps) MODULE: DemoEyeTracker
   35 - OUTPUT: GREY 176x144 @ 119fps CAMERA: YUYV 176x144 @ 119fps) MODULE: EdgeDetection
   36 - OUTPUT: GREY 160x495 @ 60fps CAMERA: YUYV 160x120 @ 60fps) MODULE: DemoCPUGPU
   37 - OUTPUT: GREY 128x117 @ 5fps CAMERA: YUYV 160x120 @ 5fps) MODULE: DenseSift
   38 - OUTPUT: GREY 120x25 @ 60fps CAMERA: YUYV 320x240 @ 60fps) MODULE: SaliencyGist
OK

See User guide to video modes and mappings for more information about video mappings.

setmapping <num> - select video mapping <num>, only possible while not streaming

Usually, video mappings are selected by the host computer, by selecting a given output resolution, frame rate, and pixel format. In some instances, however, setmapping is useful:

  1. If the current mapping has a USB output pixel format of NONE, i.e., there currently is no video being streamed over USB.
  2. If the host is currently not streaming from the JeVois camera and one (or an Arduino) wants to select a particular mapping (typically, this is useful to select a mapping with NONE usb output, as mappings with streaming video over USB will be selected when one starts a video camera software on th ehost computer anyway).

Example:

setmapping 0

will return

OK

if the host computer is not currently streaming video from JeVois over USB, and the mapping will then be changed to 0. But if video is streaming to the host computer, the answer will be:

ERR Command error [setmapping 0]: Cannot set mapping while streaming: Stop your webcam program on the host computer first.

Simply close your camera capture software on the host computer and try again.

Note
If you issue a setmapping command and then open a video viewing software on your host computer, most likely that software will override what you just did with setmapping, and will select a mapping of its own choice anyway. Hence, indeed, setmapping is usually only useful to select modes with NONE USB output. Also see setmapping2 which may be better in terms of avoiding confusion that may arise when setting a mapping by index, where that index may change as the videomapping.cfg file is edited.
For mappings that stream output video over USB, the host computer also determines when to start streaming (when you start your camera capture software on the host) and when to stop streaming (when you quit that program). However, for mappings where USB output is NONE, there is no camera capture software running on the host and hence one needs to instruct the JeVois camera to start or stop streaming (see streamon and streamoff commands below).
We do not automatically start sreaming when a mode with NONE USB output is selected because one may want to first do addtional configurations before streaming. For example, one may select a mode with the SaveVideo module that will save camera frames to disk, then set parameters of that module to select a given file name and video encoding format, and only then start streaming.

When a mode with USB output of type NONE is selected, two additional commands become available: streamon and streamoff, detailed below.

setmapping2 <CAMmode> <CAMwidth> <CAMheight> <CAMfps> <Vendor> <Module> - set no-USB-out video mapping defined on the fly, while not streaming

This allows one to define and set on the fly a new video mapping that has no USB output.

This command is very useful to configure the JeVois smart camera from an embedded system like an Arduino, which may not have knowledge of the mapping number in videomappings.cfg for a particular mapping it wishes to use.

See User guide to video modes and mappings for details. Here, because there is no USB output, we only need to specify camera format, resolution, and framerate, and which machine vision module to use.

For example:

setmapping2 YUYV 640 480 20.0 JeVois DemoArUco

will load up the DemoArUco module and run it with the camera configured for 640x480 @ 20fps YUYV video caoture.

Note
A similar command for mappings with USB output is not possible because the JeVois smart camera must announce to the host computer the complete list of all supported video resolutions that it can stream over USB, at the time it is first connected to the host computer.
For mappings with no video streaming over USB (as set using setmmapping2), there is no camera capture software running on the host that would instruct JeVois to start streaming video. Hence one needs to instruct the JeVois camera to start or stop streaming (see streamon and streamoff commands below). This is done manually so that users can decide when to start and stop streaming.
setmapping2 should be used only with machine vision modules that support processing with no USB output. Those will have a process(InputFrame && inframe) function in their source code. If your JeVois smart camera seems to not work after a given setmapping2 command, try a setpar serlog USB and connect to JeVois using a terminal and the serial-over-USB connection. If you see no messages, probably you forgot the streamon command. If you see error messages, probably your module does not supportprocessing with no USB output.

streamon - start camera video streaming

This command will only exist if the current video mapping has a USB output of type NONE (including modes selected using setmapping2).

It will instruct the JeVois smart camera to start streaming video frames from the camera sensor. It is necessary to issue a streamon command after a video mode with no USB output has been selected. Otherwise, the smart camera will just wait for this command indefinitely.

streamoff - stop camera video streaming

This command will only exist if the current video mapping has a USB output of type NONE (including modes selected using setmapping2). It will instruct the JeVois smart camera to stop streaming video frames from the camera sensor.

When using a mapping with USB output of type NONE, you must manually issue a streamoff command before you can issue your next setmapping or setmapping2 command.

ping - returns 'ALIVE'

The purpose of this command is to check whether the JeVois smart camera has crashed, for example while testing a new machine vision module currently vbeing developed and debugged.

serlog <string> - forward string to the serial port(s) specified by the serlog parameter

This works in conjunction with the serlog parameter, which determines which serial port is used for log messages. The serlog command just forwards the given string to the serial port selected by the serlog parameter.

This is useful, for example, to allow an Arduino connected to the hardware serial port of JeVois to send debug messages that can be read by a human connected to the serial-over-USB port of JeVois.

For example, an Arduino connected to the hardware 4-pin connector of JeVois may issue over its serial port:

setpar serlog USB
serlog Arduino started
serlog Arduino compass calibrated

and a human (or another machine) connected to the JeVois camera using the serial-over-USB port would then see:

Arduino started
Arduino compass calibrated

Remember that log messages (e.g., error messages) issued by the JeVois camera itself are also sent to the port selected by the serlog parameter.

serout <string> - forward string to the serial port(s) specified by the serout parameter

This operates like the serlog command but uses the serial port selected by the serout parameter.

For example, to interactively debug some Arduino code, one may want to manually type the kinds of strings that a JeVois machine vision module would issue, to make sure that the Arduino always correctly interprets them. Assume that we are debugging the pan/tilt Arduino code provided with JeVois. One may want to try to issue a number of "T2 targetx targety" messages by hand to check that the pan/tilt camera moves in the correct way. With the Arduino connected to the 4-pin hardware serial port of JeVois, and a human interacting with JeVois through the serial-over-USB port, the human could type:

setpar serout Hard
serout T2 0 0
serout T2 1000 1000
serout T2 -1000 -1000
serout T2 &^%$@ try to crash arduino by using buggy T2 command

The "T2 x y" strings would then be forwarded to the Arduino, which should move the pan/tilt motors accordingly. With the last (ill-formatted) T2 command, the Arduino should correctly reject it and not move the motors.

Remember that module data output messages (e.g., coordinates of a detected target object) issued by the JeVois camera itself are also sent to the port selected by the serout parameter.

usbsd - export the JEVOIS partition of the microSD card as a virtual USB drive

JeVois v1.1

This command allows one to access over USB the JEVOIS partition of the microSD card that is inside JeVois, as if it was a USB thumbdrive connected to the host computer. This command only works when not streaming video.

Writing to the microSD inside JeVois as it is also being used by JeVois poses data caching and synchronization problems, which are currently resolved as follows:

  • When the usbsd command is issued on the command line interface, the JEVOIS partition of the microSD is first made read-only to the JeVois processor. This means that JeVois will not be able to save data anymore (e.g., video files saved by some modules), and it will not be able to do other things that need to write to the microSD, such as automatically compiling Python modules as they are loaded up. The JEVOIS partition is then exported to the host computer as a virtual USB flash drive, with read and write access.
  • Users are then free to browse the contents of the microSD, add files, delete files, and modify files. JeVois will not immediately be made aware of these changes, though.
  • Users should then properly eject the virtual USB drive. JeVois will detect this and will restart to be able to use the modifications made by the users.

sync - commit any pending data write to microSD

JeVois v1.1

Issue this command to ensure that data being writtent to microSD has been committed to the card, for example before you restart or disconnect JeVois.

date [date and time] - get or set the system date and time

JeVois v1.1

JeVois platform hardware does not have a battery for a real-time clock. Hence, its time gets reset to The Epoch (January 1, 1970) on each reboot. Use this command to set the date and time or to get it. Syntax is the same as the Unix date command. This is useful, for example, to get accurate time stamps when recording videos. Since JeVois does not have a battery-powered clock, any date setting will be lost at the next power off.

restart - restart the JeVois smart camera

Platform Only JeVois v1.1

This command simply restarts the JeVois smart camera.

quit - quit this program

Host Only

When running in host mode, one can quit jevois-daemon by simply typing 'quit' in the terminal in which it was started.

General parameters available on the command line

As mentioned above, different machine vision modules will add parameters (and possibly new commands) available to users over the command line. Here we describe the parameters that are exported by the Engine. Those are always available, regardless of which machine vision module is currently loaded:

loglevel (jevois::manager::LogLevel) default=[info] List:[fatal|error|info|debug] - Set the minimum log level to display

Log messages are issued by JeVois code using provided commands LDEBUG(), LINFO(), LERROR() and LFATAL(). The loglevel parameter allows a user to select at runtime the level of log verbosity. Messages at the selected level or more severe will be displayed. For example, when selecting a loglevel of info, LINFO(), LERROR() and LFATAL() messages will be displayed.

Note
As an optimization of speed, one can disable at compile-time the DEBUG level log messages, thereby avoiding wasting some CPU to test for the current value of loglevel and to then decide whether or not to issue a debug message. When JEVOIS_LDEBUG_ENABLE is turned off during compilation of JeVois those tests are bypassed at compile-time and all LDEBUG() commands are simply no-operations (they do nothing and do not use any CPU, as if they just had been removed).
Hence, the possible value debug will not appear as one of the possible loglevel values if JEVOIS_LDEBUG_ENABLE was off during compilation of JeVois.

tracelevel (unsigned int) default=[0] - Set the minimum trace level to display

Programmers may use the JEVOIS_TRACE() macro to issue debugging messages that will tell a user when a particular function is executed. JEVOIS_TRACE() will issue one message when the function starts, and another when it ends. This is useful to detect where a module under development might be locking up and should be fixed.

JEVOIS_TRACE takes one argument, which is an integer number called level. The tracelevel parameter can then be adjusted to only show trace messages that have a level below the current value of tracelevel. The higher the tracelevel, the more messages you will see. Programmers decide on which trace level to use in various functions.

Note
Because JEVOIS_TRACE() issues its trace messages using LDEBUG(), those will not appear unless JeVois was compiled with JEVOIS_LDEBUG_ENABLE turned on, which is not the case by default. The reason for this is to avoid wasting time doing tests for whether or not we should issue a debug message when running in production model. Likewise, JeVois must have been compiled with JEVOIS_TRACE_ENABLE turned on for trace messages to work.

serout (jevois::engine::SerPort) default=[None] List:[None|All|Hard|USB] - Send module serial messages to selected serial port(s)

The value of this parameter indicates to which serial port(s) messages of type serout will be sent.

See discussion of the serout command above.

serlog (jevois::engine::SerPort) default=[None] List:[None|All|Hard|USB] - Show log and debug messages on selected serial port(s)

The value of this parameter indicates to which serial port(s) messages of type serlog will be sent.

See discussion of the serlog command above.

cpumax (unsigned int) default=[1344] List:[120|240|312|408|480|504|600|648|720|816|912|1008|1044|1056|1080|1104|1116|1152|1200|1224|1248|1296|1344] - CPU maximum frequency in MHz

Allows a user (or Arduino) to set the maximum frequency at which the JeVois CPU will run. This may be useful in some situations to limit CPU speed, for example when powering JeVois from a battery that is running low.

cpumode (jevois::engine::CPUmode) default=[Performance] List:[PowerSave|Conservative|OnDemand|Interactive|Performance] - CPU frequency modulation mode

Allows users to select different schemes for hoe the JeVois CPU frequency may be adjusted on the fly during operation. This is also known as a frequency governor in the Linux community.

By default, the assumption is that a JeVois smart camera will always be processing video at its maximum possible speed. Hence, by default cpumode is set to Performance. Other modes will slow the CPU down when it is not heavily used, for example while the CPU is waiting for the next image from the camera.

Note
Generally speaking, unless you are using your JeVois camera in some extreme situation, we recommend keeping cpumode at its default setting of Performance, as this will provide the most reliable frame rates. Large fluctuations in frame rates may appear when using other modes.

camreg (bool) default=[false] - Enable raw access to camera registers through setcamreg and getcamreg

This command allows one to enable direct access to the low-level registers on the sensor chip of the JeVois smart camera. It is turned off by default. This is for low-level hackers only, who are trying to improve image quality by trying different settings of the low-level camera sensor registers.

Warning
It is very easy to crash your JeVois smart camera when you fiddle with the low-level registers. You have been warned. One wrong value and the whole smart camera goes down.

When parameter camreg is set to true, two new commands become available:

  • setcamreg <reg> <val> - set raw camera register <reg> to value <val>
  • getcamreg <reg> - get value of raw camera register <reg>

In both cases, reg and val are unsigned 8-bit values. For convenience, both decimal values and hexadecimal values (using a prefix 0x to indicate hexadecimal) are supported.

Command-line scripts

Sometimes, it is useful to set some parameters or execute some commands when a module is loaded.

JeVois allows you to store parameter settings and commands in a file named script.cfg stored in the directory of a module. The file script.cfg may contain any sequence of commands as you would type them interactively in the JeVois command-line interface.

Here is an example for the ObjectTracker module, which tracks objects based on their color. For this module, it is a good idea to set the JeVois camera sensor to full manual mode, as automatic gain, exposure, and white balance would otherwise affect the RGB pixel values of the same object under different viewpoints and locations with respect to the light sources. Since tracking in the ObjectTracker is based on the color values returned by the sensor, full manual camera mode gives more reliable tracking.

# Demo configuration script for ObjectTracker module.
# Set camera to fixed color balance, gain, and exposure, so that we get more reliable colors than we would obtain under
# automatic mode:
setcam autowb 0
setcam autogain 0
setcam autoexp 0
setcam redbal 110
setcam bluebal 170
setcam gain 16
setcam absexp 500
# Detect a light blue flash drive by setting the appropriate value ranges for Hue, Saturation, and Value in the
# ObjectTracker module:
setpar hrange 95...110
setpar srange 100...255
setpar vrange 60...253

The script.cfg file for ObjectTracker is stored on your microSD at JEVOIS:/modules/JeVois/ObjectTracker/script.cfg source in ~/jevoisbase/src/Modules/ObjectTracker/script.cfg.