SolarNode Development Guide
This guide explains how to setup a development environment for contributing or modifying the SolarNode application code.
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.
If you haven't already set up your SolarNetwork development environment, go through the Eclipse Setup Guide first, and then return here.
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).
- [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.
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 new.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 -
weather- plug-ins for collecting weather data
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).
Some plug-ins expose properties that can be configured to suit different operating environments. These plug-ins will always provide default values for the configurable properties, so you only need to create custom properties files if the default values do not match your local environment.
The plug-in properties are configured via Java Properties files located in the
/solarnetwork-osgi-target/configurations/services directory. If a plug-in project
exposes configurable properties, it will have an example properties file in the
example/configuration directory within that project. These files will have particular
names which must not be changed because the plug-in will look for its properties file
based on the pre-defined name. To customize the properties for a plug-in, copy the
desired example/configuration/*.properties file into
/solarnetwork-osgi-target/configurations/services, rename it to have a .cfg
extensions, and then modify the copied file as necessary. The example files will contain
all available configurable properties, along with documentation on each property.
For example, the net.solarnetwork.node.dao.jdbc project exposes some configurable
properties as detailed in
example/configuration/net.solarnetwork.node.dao.jdbc.properties. This plug-in configures
the JDBC connection used by the SolarNode for persisting data. If you want to customize
the JDBC connection in any way, copy this file to
/solarnetwork-osgi-target/configurations/services/net.solarnetwork.node.dao.jdbc.cfg and
modify it as desired.
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.
See the Debugging SolarNetwork with Eclipse page for information on running
SolarNetwork applications within Eclipse. You don't need to run the SolarNet application
if you run the .mock versions of plug-ins like net.solarnetwork.node.upload.mock.