A Maven archetype to generate Pi4J V2 project skeletons

This Maven archetype can generate Pi4J V2 project templates with remote build, run and debug capability. A template project generated with this archetype can:

• Handle a connection to many Raspberry Pi targets, configured in the pom.xml file
• Compile your code, packing the compiled code in a jar, uploading it and all the other required jars on the selected remote target
• Run the program on the remote target
• Open a remote debugging session

The archetype is IDE agnostic (I tested it using Netbeans) and depends only on Maven and ant. You should be able to use it with your preferred IDE program (Netbeans, Eclipse, Idea or whatever else).

Getting started

Follow these steps to set up the archetype and use it:

Install Maven

You must have the Maven tool installed on your computer. If not, you can download it from https://maven.apache.org/

Install the archetype to your local .m2 repository

Download this Github Pi4J Project by clicking on the green "Code" button and selecting "Download ZIP".

• Unzip the archetype file in a FOLDER
• cd FOLDER/pi4j-maven-archetype-main
• mvn install

How to generate a new PI4J V2 skeleton project

Now suppose you want to begin a new PI4J-V2 project my-project:

• mkdir my-project
• cd my-project
• mvn archetype:generate -DarchetypeCatalog=local
• answer to the questions asked (see below for details)

Configuring your new project

Before starting the new project generation, the archetype asks you some configuration data:

1. Choose archetype: select the pi4j-maven-archetype from the list shown
2. Define value for property 'groupId': choose the Maven groupId for your project. (If don't know what is a groupId, don't worry, just type com.example)
3. Define value for property 'artifactId': choose a name for the program executable your project will produce
4. Define value for property 'version': 1.0-SNAPSHOT: type Enter to accept the default value shown, or type the initial version, something like 1.0.0
5. Define value for property 'package': com.example: type Enter to accept the default value shown

The archetype now presents to you a summary of the configuration parameters you have just typed in, plus the values proposed for the main-class and package parameters. If the list is ok for you, reply Y to accept, otherwise reply N to change one or more values (you will have to re-type all parameter values ...)

After the list confirmation, the archetype generates a new maven project for you. You should be able to open the new project with your preferred java IDE. The IDE should be able to recognize the project as a valid Maven project.

How to generate from a remote repository (optional)

If you deploy the archetype in a remote repository, use this command to generate a new skeleton project:

mvn archetype:generate -DarchetypeGroupId=com.pi4j -DarchetypeArtifactId=pi4j-maven-archetype -DarchetypeVersion=1.0-SNAPSHOT

The generated skeleton project

You can now freely modify the new project, adding your code. The following is a guide on using the new project features.

How it works

This project skeleton allows you to write the source code of your RPI programs using a destop computer (Linux or Windows) and your preferred IDE as development station, uploading the executable code to a remote RPI board, running and also debugging your code remotely.

What do you need

• The development station must be connected to your local network
• A target RPI board must also be connected to the same network
• You must configure the target RPI for a Headless connection with the development computer, i.e. the ssh server must be enabled in your RPI board and you must be able to connect with a ssh terminal.

How to configure

The configuration data about the target RPI remote board is stored in the file platform/raspberry.properties. Actually the folder platform can contain as many target_name.properties as the RPI boards you may want to connect to. The maven property target.platform.name, defined in the pom.xml file, points to the right file in the platform folder. The default configuration file is platform/raspberry.properties and the target.platform.name = raspberry

Configure the platform/raspberry.properties file

Each xxxx.properties file in the platform must be edited to describe the configuration data of a specific RPI board, as follow:

• the target RPI IP address, the ssh connection port, the username and password
• instead of using a password, if your RPI is configured to accept a ssh key, you can specify your ssh key.
• the location of the java JRE / JDK on remote target, the folder where the program executables must be uploaded
• ... other details described in the raspberry.properties

How to build, run and debug your project

The project declares in the pom.xml the following maven/ant goals that you can execute with the command shown :

• mvn clean : delete all compiled files from local and remote project
• mvn install : builds the project, uploads the required jars to the remote target RPI board
• mvn antrun:run@exec : runs the program on the remote target
• mvn antrun:run@debug : runs a remote debugging session on the target RPI.

All the modern IDE programs have a mechanism to configure new GUI commands linked to a specific maven goal. See below for an example of such a GUI configuration of the Netbeans IDE.

Note on running a debug session

To start a debugging session:

• run the command mvn antrun:run@debug, the program on the remote target starts with JVM in debug mode, waiting for a debugger connection on the port configured for the target
• in your IDE start the debugger setting the host IP = target IP and port = port configured in raspberry.properties You should be able to set remote breakpoints, execute step by step, examine variables on your remote program.

Note on the Java runtime

If you are not using the default Raspberry Pi OS full edition and/or included Java, you may get this kind of error:

[ERROR] Failed to execute goal org.apache.maven.plugins:maven-antrun-plugin:3.0.0:run (exec) on project ...: An Ant BuildException has occured: The following error occurred while executing this line:
[ERROR] ...\antrun\build.xml:166: The following error occurred while executing this line:
[ERROR] ...\antrun\build.xml:123: Remote command failed with exit status 1
[ERROR] around Ant part ...... @ 9:59 in ...\antrun\build-main.xml

This can be caused by a mis-configured Java runtime. The default value in raspberry.properties is:

target.remote.jre=/usr/lib/jvm/default-java

Check if this value exists and links to your Java runtime, or find the location of your installed JDK with sudo find / -iname java and use the result in your configuration.

For instance: a Raspberry Pi Zero (type 1) with ARMv6 requires a specific Java version for this type of processor. This is described more in detail on "Java for ARMv6/7/8". If you use Azul Zulu JDK, you will need to change the configuration to:

target.remote.jre=/usr/lib/jvm/zulu11.41.75-ca-jdk11.0.8-linux_aarch32hf

Some final notes

PI4J version

The pom.xml file adds the pi4j v.2.1.0 jar dependencies to the project classpath. You may want to update to the latest version

File "nbactions-template.xml"

If Netbeans is your preferred IDE you can use the file nbactions-template.xml to add to the Netbeans GUI the two actions "Remote run" and "Remote debug". Follow these simple steps:

1. Right click the project in the NBs Projects window and select Properties
2. Select Actions --> Build project
3. Click on Add button and select Skip Tests
4. Click OK - (this forces Netbeans to generate the file nbactions.xml in the project folder)
5. Open the file nbactions.xml and nbactions-template.xml
6. Select the two Action XML elements with name CUSTOM-Remote run and CUSTOM-Remote debug and copy them to the nbactions.xml. - Pay attention to preserve the correct XML syntax of file nbactions.xml, and save it.

Now right-click the project in the NBs Projects window and select Run Maven: you should see the two new goals Remote run and Remote debug

When done, you can safely delete nbactions-template.xml