SolarNode Development Guide

This guide explains how to setup a development environment for contributing or modifying the SolarNode application code.

⚠️ Note the Developer VM guide provides a more streamlined way to get a SolarNetwork development environment set up, using a pre-configured virtual machine. This guide is useful if you would like to use Eclipse on your native development machine, instead of relying on a virtual machine.

The SolarNode project consists of a set of OSGi bundle projects that, when combined and run in an OSGi container, form a complete SolarNode application. Each OSGi bundle comes configured as an Eclipse IDE plug-in project (Eclipse refers to OSGi bundles as "plug-ins" and its OSGi development tools are collectively known as PDE). Although Eclipse is not actually required, the remainder of this guide will describe setting up Eclipse for viewing and running the code for development purposes.

Eclipse Setup

If you haven't already set up your SolarNetwork development environment, go through the Eclipse Setup Guide first, and then return here.

Clone Git repositories

The SolarNode project is contained in the solarnetwork-node repository. You can clone a Git repository by going to Window > Open Perspective > Git Repository Exploring (you may need to choose Other... under Open Perspective if Git does not appear there).

1. [email protected]:SolarNetwork/solarnetwork-node.git

Note this is in addition to the common repositories mentioned in the Eclipse Setup Guide, which also describes in more detail how to clone repositories in Eclipse.

Plug-in project naming conventions

The SolarNode code is divided into many small plug-in projects which follow a Java package-like naming convention using periods between domain names, like net.solarnetwork.node.datum. All SolarNode-specific projects start with net.solarnetwork.node followed by a feature name and then optionally followed by other implementation specific names. Examples of features are:

• control - plug-ins for controlling devices
• datum - plug-ins for collecting data from devices
• hw - plug-ins for hardware-specific support
• io - plug-ins for communication protocol implementations
• setup - plug-ins for managing SolarNode itself

If you are not interested in a particular feature, you can streamline your Eclipse workspace by closing the projects you don't need (right-click and choose Close Project).

Running or debugging the SolarNode application

Launch SolarNode by going to Run > Run Configurations.... Under the OSGi Framework section on the left, two example launch configurations named SolarNode (Java 11 Example) and SolarNode (Java 8 Example) will be present. Duplicate one of those by right-clicking on it and choosing Duplicate. Then make changes to that configuration (like rename it) as you see fit. For example you can disable all *.test bundles or disable bundles you are not interested in.

You do not need to run the SolarNet application if you include the net.solarnetwork.node.setup.developer and net.solarnetwork.node.upload.mock bundles in your launch configuration and omit the other net.solarnetwork.node.setup.upload.* bundles. Once you launch the platform, SolarNode will be available at http://localhost:8080:

When using the net.solarnetwork.node.setup.developer bundle, the login credentials are

Username	Password
-11	solar

After logging in, you should see all available configurable bundles show up on the Settings tab:

Disabling test bundles

Most SolarNetwork bundles have an associated unit test fragment bundle whose name ends with .test. For example the net.solarnetwork.common.web bundle has an associated net.solarnetwork.common.web.test unit test bundle. These unit test bundles can really slow down the launching of the SolarNetwork platform in Eclipse, so it is a good idea to disable them so they are not included at runtime.

You can disable test bundles on the Bundles tab of the launch configuration. Type test in the filter field to easily show only the test bundles, and then you can disable each of them, like this:

Unit test logging

For unit tests, a different log configuration from the platform runtime is used. In the net.solarnetwork.node.test project, copy the environment/example/*.properties files into environment/local. You can then edit the ones in local as needed, as they are ignored by Git.

Closing unused projects

The SolarNode platform is made up of a large number of plugin projects, but you probably do not need many of those plugins while working on the SolarNode codebase. To streamline your Eclipse workspace and make running SolarNode faster, you can close the unnecessary projects, and then even hide them from the Project Explorer.

Identify unnecessary projects

First you must identify which projects are "unnecessary" for the development you intend to do. Some good places to start looking are:

• the net.solarnetwork.node.control.* plugins, which are generally NodeControlProvider plugins for specific devices or protocols
• the net.solarnetwork.node.datum.* plugins, which are generally DatumDataSource plugins for specific devices or protocols
• the net.solarnetwork.node.hw.* plugins, which are generally low-level support plugins for specific devices
• the net.solarnetwork.node.io.* plugins, which are generally low-level protocol support plugins

Close unnecessary projects

Select the projects you would like to close, and then either use the Project > Close Project menu or right-click and choose Close Projects. The closed projects change so you can no longer see their contents. When you then launch the SolarNode platform, those plugins will no longer be part of the SolarNode runtime, so SolarNode will be able to start up faster.

Here is a screen shot showing many closed projects and one open project:

Hide closed projects

You can streamline the Eclipse Project Explorer by hiding closed projects. This can help so you do not have to scroll around so much when there are many closed projects. In the Project Explorer there is a small funnel icon. Click on that and you can then select the Closed projects filter to hide all closed projects:

To un-hide the closed projects, un-select the Closed projects filter.

Helpful projects for development

Here are some projects worth noting in terms of being beneficial to developers:

Project	Description
n.s.n.datum.energymeter.mock	A mock energy meter datum source, good for generating simulated datum streams of power and energy.
n.s.n.control.mock	Exposes a few mock toggle switch (boolean) controls, good for testing instruction logic.
n.s.n.hw.rfid.mock	Generate mock RFID events, good for simulating RFID access logic.
n.s.n.io.gpsd.mock	Generage mock GPS coordinate events, good for simulating motion.