The JeVois programmer software development kit (SDK) allows you to create your own machine vision modules for JeVois. The SDK is a complex beast as it not only comprises the JeVois core software, but also a custom Linux kernel for your JeVois camera, and the full Linux operating system and set of utilities that run inside the JeVois camera.

Getting started with the JeVois Programmer SDK

To get started with the programmer SDK, either install a pre-compiled deb package for it, or build it from source, as detailed in JeVois Ubuntu packages and source code repositories

Writing new modules: A single standalone module

A script jevois-create-module has been created in /usr/bin (source in ~/jevois/scripts/) to automate the process of creating a new module. It basically clones https://github.com/jevois/samplemodule and changes some names in there to new names you provide:

# USAGE: jevois-create-module <VendorName> <ModuleName>
# Creates a project directory with name tolower(ModuleName) and populates it:

jevois-create-module MyVendor MyAlgo

# Module is setup in myalgo/

Now edit your module to actually do something interesting, and update all the custom doxygen tags in the inline doc of the module, such as @videomapping, and so on (see below for more info on custom doxygen tags).

Also check out icon.png and other files in the directory where the source code is, and update them as appropriate.

You can then compile using

./rebuild-host.sh
./rebuild-platform.sh
./rebuild-pro-host.sh
./rebuild-pro-platform-pdeb.sh

as you did with jevois and jevoisbase.

Note: If you get an error cc1plus: fatal error: jevois/Config/Config.H: No such file or directory, just run rebuild-platform.sh in your jevois repository. See Compiling JeVois core software from source

JeVois-Pro: Installing your module on the camera

After running ./rebuild-pro-platform-pdeb.sh a .deb file is created in ppdbuild/

Copy it to your microSD.
Start your camera with that microSD in it.
In the JeVois-Pro console, type shell dpkg -i /path/to/your-module-package.deb. If you already had a previous version installed, run shell dpkg -r your-module-package first to remove it.
In the Config tab, edit videomappings.cfg to add a new mapping for your module. Save the file.
Your module should now appear under the menu of available modules and you can select it and run it.

JeVois-A33: Adding your module to a microSD card: live microSD card

Insert a properly installed JeVois MicroSD (follow the steps at JeVois Start to make one from a disk image) into your computer, either physically inserted into your host computer using a microSD-to-USB adapter, or exported live by JeVois using the usbsd command in the JeVois command-line interface). The microSD card must be be available under /media/username/JEVOIS/ where username is your Linux user name.

Run:

./rebuild-platform.sh --microsd

Modules, config files, etc will be installed to the live microSD card at /media/username/JEVOIS/ where username is your Linux user name.

Note: Once you select a destination in rebuild-platform.sh (none, staging, or microsd), that will remain for subsequent make install commands, until you change it by re-running rebuild-platform.sh with another destination.

Here is a simple command to export the microSD of a live JeVois camera without having to start a terminal program, etc (make sure JeVois is not streaming video):

sudo sh -c 'echo usbsd > /dev/ttyACM0'

With JeVois v1.2 and later, you can just instead type jevois-usbsd start to start exporting the microSD, and jevois-usbsd stop to eject it and restart JeVois.

With JeVois v1.3 and later, you do not need to manually take out or even manually export the microSD inside JeVois anymore. A new build option --live can do it automatically. Just connect JeVois and allow it to start, then type:

./rebuild-platform.sh --live

which will:

cross-compile the module for platform
issue a jevois-usbsd start to instruct JeVois to export its microSD as a virtual flash drive
install the cross-compiled module to the microSD inside JeVois
issue a jevois-usbsd stop to eject the virtual flash drive and restart JeVois.

JeVois-A33: Adding your module to a microSD card: jvpkg

This approach is useful if you also want to share your module with friends. You can just send them your jvpkg file.

Once you have all the compiled and auxiliary files (icon.png, etc) in myalgo/jvpkg, you are ready to pack it:

cd pbuild
make jvpkg

This creates a file

myalgo/MyVendor_MyAlgo.jvpkg

Insert a properly installed JeVois MicroSD (follow the steps at JeVois Start to make one from a disk image) into your computer, and copy the .jvpkg file into the JEVOIS:/packages/ directory of your microSD.

Your smart camera will unpack, configure, and delete the .jvpkg file next time it starts up.

Make sure you allow enough time for it to do that work. It may take several minutes (depending on your module's file size, microSD card speed, etc).

Remember to also edit config/videomappings.cfg in the JEVOIS partition of your microSD to add a new mapping that will use your module.

For more information:

jvpkg packages are created by /usr/bin/jevois-jvpkg (source in ~/jevois/scripts/jevois-jvpkg), which is invoked by make jvpkg
and they are unpacked by /usr/bin/jevois.sh (source ~/jevois/bin/jevois.sh) running on the platform when it boots up.

Module documentation and metadata

A really nasty perl script, /usr/bin/jevois-modinfo (source in ~/jevois/scripts/jevois-modinfo), will parse your module to generate a single-page documentation for it. This script is a mess and its operation is quite brittle. It is invoked automatically when you compile your module (see rules in ~/jevois/CMakeModules/JeVois.cmake).

The script creates modinfo.html (and modinfo.yaml, currently not used) by parsing your modules and other files in its directory.

Special doxygen tags in your module's doc will be parsed, here are some examples:

@author Sample Author
@displayname My Algo (only needed if you want to display a different name than the class name)
@videomapping YUYV 640 480 28.5 YUYV 640 480 28.5 SampleVendor SampleModule
@modulecommand mycommand - description of the module-specific command
@youtubevideo AbcDe567 - link to a youtube video, will be shown in the doc along with the screenshots
@email sampleemail@samplecompany.com
@address 123 First Street, Los Angeles, CA 90012
@copyright Copyright (C) 2017 by Sample Author
@mainurl http://samplecompany.com
@supporturl http://samplecompany.com/support
@otherurl http://samplecompany.com/about
@license GPL v3
@distribution Unrestricted
@restrictions None

Specially named files will also be used if present:

icon.png (or any other extension, like .jpg, etc): an icon for your module.
screenshot*.*: screenshots, will appear in the doc in the same order as ls lists them.
video*.*: demo videos, will appear in the doc in the same order as ls lists them.
postinstall: a script that will be executed after your module is unpacked. You may use command jevois-add-videomapping (installed in /usr/bin/, source in ~/jevois/src/Apps/) in this script to add to the videomappings.cfg file any videomappings that should be installed when your module is installed. This usually is a subset of all the mappings listed in the doc using the doxygen tags.
params.cfg: parameters values that should get set when the module is loaded. These are set before the module is initialized.
script.cfg: script of jevois comand-line interface commands that should be run when the module is loaded. This is run after the module is initialized.
jvpkg-exclude.cfg: list of files that should not be included into the jvpkg package. Same format as in tar --exclude-from

Partial compilation

The scripts rebuild-host.sh and rebuild-platform.sh clear and recompile everything.

You should run them at least once.

Then, if you are just changing a few files, you can only recompile what is needed, as follows:

JeVois-A33: for host
```
cd hbuild
make -j
sudo make install
```

JeVois-A33: for platform

cd pbuild
make -j
make install
make jvpkg

JeVois-Pro: for host

cd phbuild
make -j
sudo make install
make doc     # optional; if desired

JeVois-Pro: for platform

cd ppdbuild
make -j
sudo make install
sudo cpack # will re-generate the deb package into ppdbuild/

Writing new modules: A collection with shared components

In this more complex scenario, you wish to create a collection of modules, and some component algorithms will be shared by several modules.

The preferred approach is then to write the shared algorithms as jevois Component objects, and to compile them all into a shared library (.so). Each module that uses some of the components will then automatically trigger the loading of the shared library. This is the approach taken in jevoisbase

For guidance on this, inspect the CMakeLists.txt in jevoisbase.

Note how several CMake macros have been defined to assist you; those are in jevois/CMakeModules/JeVois.cmake

In jevoisbase, we compile everything that is under src/Components into libjevoisbase.so

Then, we compile each module under src/Modules into one .so file each, which is marked as depending upon libjevoisbase.so

To create your own, roughly the first 50 lines of the jevoisbase CMakeLists.txt should be preserved and modified for your project. The rest of the jevoisbase CMakeLists.txt is basically to add required dependencies, such as on the ZBar library, the OpenCV library, etc and those will vary with your specific project.

Make sure you keep the call to jevois_project_finalize() at the end of your CMakeLists.txt file.