Tutorial: Use C++ code in your Reactive Block application with BridJ

Summary. These tutorials explains how to use foreign (as in non-Java) code in your Reactive Block application. Another term for foreign is native, because embedding non-Java code usually introduces platform and portability issues.

Make sure you have read the intro foreign-code-intro to prepare what you need for this tutorial.

Doing the tutorial

Alt text

Download the tutorial named “(Level 3) Foreign code v2: BridJ (C++)”

Part 1 - Build shared library on Raspberry-Pi

  • Look at the project in the Package Explorer view. You will see the c++code directory. Inside there you will find four files, one script, one header file and two cpp files.

Alt text

  • Transfer the files to your Raspberry-Pi. You may need to set the execute bit on the script.
  • Compile shared library with command: buildall.sh
  • The shared library is called libwd-bridj.so
  • Test the shared library with separate test program test-wd-bridj. Note that you may need to set LD_LIBRARY_PATH

Alt text

Part 2 - Understand functions of shared library

Alt text

The functions we are going to make available from Java are:

  • void setDeviceName(const char *deviceName);: Set filename of watchdog device.
  • const char *getErrorMessage();: Gets most recent error message. The message is allocated in C++ heap and a pointer is returned to Java application.
  • void clearErrorMessage();: Clear last error message and release memory.
  • int enable(int timeout);: Enable watchdog, parameter is timeout value.
  • int getRemainingTime();: Returns remaining time until watchdog fires, this is similar to the stupid countdown timer on all atomic bombs in old James Bond movies.
  • int getTimeout();: Return current timeout value.
  • int disable();: Disable watchdog
  • int heartbeat();: Send heartbeat to reset watchdog counter.
  • void destroy();: Destroy object and release memory.

All int return values < 0 indicates error.

Note that we avoid using std::string and other STL containers in C++ class we are going to use from Java. JNAerator and/or BridJ does not like STL and vice versa. There is no problem using STL containers in C++ classes not visible to Java.

Part 3 - Generate Java class for shared library

Download and launch JNAeratorStudio from this page and launch it. It is (obviously) written in Java and some browsers (eg. Chrome) may refuse to download it.

Alt text

Generate Java class to interface shared library like this:

  • Paste the code from wd-bridj.h into work window
  • Set Target Runtime to BridJ
  • Set Output Mode to Jar
  • Set Library name to wd-bridj
  • Press JNAerate!

The generated file will appear to the right. You can also do this process manually, but using this tool gives you a good starting point.

In the project you downloaded earlier you will see that the generated file (src/com/bitreactive/tutorial/foreigncode/bridj/wdbridj/WatchdogInterface.java) is already in place. You can replace it with the one that is generated now. You will need to change package name, but other than that no changes needs to be done (We removed the member variables, since we did not use them, but that is not necessary).

In addition you must add the bridj.jar library to the project. (It has also already been done).

Now you are ready to use the C++ library from your Reactive Blocks application.

You can also read more about more complex datatypes than const char * here. It is relatively straight forward, as long as you stay away from STL.

Part 4 - Understand reactive block and functions

Alt text

The block is shown in the image above and with exception of the init and stop pin, all functions the same as in the C++ library. In addition we have added a state check to query if watchdog is enabled.

We will take a closer look at some of the Java functions we made:

init and stop functions:

Alt text

The C++ interface is allocated just as any other object, and note that clearing the reference will not call the destructor on the C++ side, so you need to handle that separately.

The Pointer class contains helpers to convert between Java String and C++ character pointers.


Alt text

enable functions does take one parameter, the watchdog time which is transferred to C++ library.

Part 5 - Build application and execute on Raspberry-Pi

  • Select Test WD BridJ application, press Build from rightclick menu and build Java executable. Select Java SE as project type.
  • Export the generated project (located in com.bitreactive.tutorial.foreigncode.bridj.testwdbridj_exe) as Runnable JAR and transfer to your Raspberry-Pi to the same directory as the shared library you generated in part 1.

Alt text

  • Try it (Hint: Note you have to use sudo because of file rights)

Alt text