How to Install the Optigo Traffic Capture Driver for Niagara Stations

Note: The Optigo Traffic Capture Driver requires an active OptigoVN account to operate. 

This guide is designed for users of Niagara 4.7 and above. Click here to jump to instructions for Niagara 4.10 and older.

Not an OptigoVN user yet? OptigoVN unlocks unrivalled, sharable diagnostic insights for troubleshooting and monitoring OT networks. From easy to understand network health scores to pinpointing issues and performance optimizations down to the individual devices on your network, it’s time to leave break/fix behind for a better network in hours, not months. Request a free trial of OptigoVN today.
 

Overview: Upload Modes

The Optigo Traffic Capture Driver for Niagara Stations supports two upload modes for sending captured BACnet data to your OptigoVN account:

• Direct mode: The Station captures and uploads data directly to OptigoVN. This requires the Station to have a direct internet connection.
• Supervisor mode: For Niagara stations that do not have a direct internet connection, a Web Supervisor can act as an intermediary. When the OptigoPacketCaptureService on a Status is set to Supervisor upload mode, the Station will capture data locally but will not upload it directly. Instead, the Supervisor — running the OptigoSupervisorService — will reach into the Station, collect the captured files, and upload them to OptigoVN on the station's behalf.

1. Download the Driver

1. Download the capture driver JAR file. Latest version here.
2. Important! Rename the JAR file to remove the version number before proceeding!

2. Install the Module (JAR file) into your Niagara directory

1. Copy the JAR file into your local Niagara module directory. File path is typically Windows>Niagara>Niagara Version XXX>modules
2. Restart the Niagara Service and the Niagara Workbench application and proceed to add the capture driver to your environment.

3. Verify the driver module in your Niagara environment

1. Click the Open Palette icon (the folder icon in the Palette dropdown).
2. Begin typing  "optigoCapture" in the text field to bring up the driver. Highlight it and select OK.

3. You should now see the Optigo Capture Pallet in the palette window.

   

4. Add the module to the target Station

1. Select the target device dropdown from the NAV menu on the left side.
2. Double-click to open the Platform details. You may need login credentials.
3. Double-click again to open the Software Manager. The software will scan for installable files.
4. Once the list is done compiling, select File to sort by file name, scroll to the entry "optigoCapture-rt", and select the Install button below to install the module onto the JACE.

5. Add the capture port to the target

1. From the expanded NAV menu, double-click the Station. You may need login credentials.
2. From the NAV menu, click the following drop down menus: Station>Drivers> double-click the Bacnet Comm port you wish to install the capture port to (see image) 
3. Drag the "OptigoCapturePort" file from the Palette window into your port submenu to add it. 
4. On the Property Sheet (main window) you should now see the CapturePort, where the Enabled option should now show a green circle and read "true". The "Packets Per Second" field will show signal if BACnet packets are flowing.

6. Add the Capture Service to the target

1. From the Nav menu, navigate to Station>Config>Services.
2. Drag the OptigoPacketCaptureService module from the Palette window to the Services list to install the service.
3. Double-click on the installed module to open it's Property Sheet.
4. Your default Server URL should remain as https://app.optigovn.com unless otherwise noted by Optigo
5. If Station has internet connection, Add your add API Key from target OptigoVN monitoring node and keep the Upload Mode to "Direct"
   If Station does not have internet connection, but the Supervisor does, please see "Configure Supervisor Upload Mode" section below.
6.  Set Enabled to "true". Note: this does not start the capture process.
   
   

---

Creating a Capture with Manual Start/Stop

1. To start a manual capture from your configured target, toggle the Capture menu option in the property sheet to "start". You can see the Packet Count increase reflect an active capture session in progress.
2. Toggle Capture to "stop" to end the manual capture session.
3. Once capture has stopped, file will automatically be uploaded to your OptigoVN account (active connection required).

To manually download the capture for later use in OptigoVN, you can find the file through the nav tree under Station>Files>optigo.

---

Creating a Scheduled Capture Session

Creating a scheduled capture is as easy as adding a Niagara schedule.

1. Select schedule from the Palette window. 
2. We recommend using the BooleanSchedule module. Drag this module to the "OptigoPacketCaptureService" module in the NAV window above, or directly to the Property Sheet in the main window if still open. 
3. Right-click the schedule module and select Link Mark.
4. Right-click the module name at the top of the Property Sheet, and select Link To "BooleanSchedule". This will open the Link submenu.
5.  Select Out from the BooleanSchedule source list and connect it to the Capture option under the OptigoPacketCaptureService target.
6. Click OK.
7. You can now double-click the BooleanSchedule module in the Property Sheet, build the schedule to your needs, and hit save when done. 
8. Once capture has stopped, file will automatically be uploaded to your OptigoVN account (active connection required).
9. To manually download the capture for later use in OptigoVN, you can find the file through the nav tree under Station>Files>Optigo. The files will have a .zip.enc extension and a DataFile type.

No internet connection? Set your server URL to an invalid destination and remove your API key if present. To manually download the capture for later use in OptigoVN, you can find the file through the nav tree under Station>Files>Optigo. The files will have a .zip.enc extension and a DataFile type.
 

---

Configure Supervisor Upload Mode

Supervisor Upload Mode is for Niagara Stations that do not have a direct internet connection and cannot upload BACnet capture data to OptigoVN on their own. In this mode, a Web Supervisor acts as an intermediary — the Station captures traffic locally and holds the files, while the Supervisor periodically connects, collects the captured files, and uploads them to OptigoVN on the Station's behalf.

 

1. Configure the Station

The Station only needs one configuration change to work in Supervisor Upload Mode. The same OptigoPacketCaptureService that was added in the previous steps is used here. On the Station, locate the Upload Mode slot in the OptigoPacketCaptureService property sheet and set it to Supervisor. This tells the Station not to attempt a direct upload to OptigoVN — instead, it will capture BACnet traffic locally and hold the files until the Supervisor collects them. If the Station has a direct internet connection and you want it to upload on its own, leave this set to Direct.

2. Configure the Supervisor Station

The Supervisor station requires a new service. In the OptigoCapture palette, add the OptigoSupervisorService to the Service location in the station.

1. Open the optigoCapture palette and drag the OptigoSupervisorService into the Config > Services node of your Supervisor station.
2. Right-click on the OptigoSupervisorService and select Actions > Import From Niagara Network. This will automatically add all NiagaraNetwork stations as targets within the OptigoSupervisorService.
   Or, manually add JaceTarget from the palette to the OptigoSupervisorService to manually add one Station at a time.
3. Once added, open each imported JACE target entry and update the Username, Password, and Api Key fields with the appropriate credentials for that JACE.
   
   

Now when a Station completes a packet capture it will not upload directly, but will instead wait for the Supervisor to connect, collect the captured files, and upload them to OptigoVN on its behalf.

---

Additional Configuration Options

When setting up the OptigoPacketCaptureService module: the following options appear:

• Min Free Space to Start Mb - The packet capture service will check for this minimum disc space before starting any new capture. If there is not enough space, it will not start a new capture.
• Max Segment Size Mb - This refers to the maximum temporary file size the capture service can use before starting a new one. We strongly recommend increasing this parameter to 500 MB or 1 GB on hosts with at least 2 GB of free disc space. This will prevent small files - resulting in very short analysis in OptigoVN. We intentionally kept the default to a small value because we understand that the capture service may be used in some very small JACEs. Note that the temporary file size is significantly more than the final file size because the final file is compressed
• Max Packets Per Segment - This refers to the maximum number of packets per file. Once this max number is reached, the capture service will create a new file

• Max Segment Duration in Minutes - This refers to the maximum duration each file can be. Once this maximum is reached, the capture service create a new file

  Note: There's a hidden constraint that will only allow 10 files to be stored at any given time. On the 11th file the oldest file will be deleted before starting a new file, always keeping the 10 latest. This should only matter if the station does not have internet access to automatically upload the file or uploading via the supervisor.
   

---

Installation and Configuration for Niagara v4.10 and Older

Niagara users with version 4.10 or older need to install the public certificate and self-signed version of the driver module to Niagara. If you have added another version of the driver on an older version of Niagara, remove it, and use the files provided in the Self Sign Module instructions below.
 

Adding a Self-Signed Module to Niagara

There are two ways to add a self-signed module to Niagara. You can set the module validation level in your system.properties file to low, but it is set to medium by default. To keep the default medium level, use the self-signed certificate.

1. Download the Required Files

You will need to download and extract the following two files from the .zip linked below:

• optigoCapture-rt.jar - the self-signed version, used where Niagara versions require RSA signing and do not support EC (elliptic curve).
• optigo-code-signing-public.pem - the Optigo public certificate.

optigo-code-signing-public.zip

2.  Install the Certificate in Workbench

Step 1. Before adding the module, start Workbench and go to Certificate Management.

Step 2. Import the public certificate from the .zip file.

Step 3. Enter Alias "Optigo Code Signing", and click OK in the dialog.

Step 4. Confirm that the certificate is installed.

Step 5. Shut down Workbench, add the driver module JAR to your modules directory, and restart Workbench. After restarting, you should be able to select the optigoCapture module from the palette. 

You can follow to the instructions on how to install the driver on the target workstation.

Installing the Module on the JACE

To add the module to a target JACE, connect to your platform and open Certificate Management there, then follow the same process to import the certificate. 

Once the certificate is on the JACE, use the instructions above to install the capture services on the target device.