[PROJECT] Driver for Neptune Systems Apex

Drivers for Neptune Systems Apex aquarium controllers. Allows the Hubitat to check a variety of information from the status file provided by the controller, so users can incorporate into their home automation.


  • Queries the IP/Hostname of the Apex controller for the status.json then parses that data into a variety of attributes and variables. Officially, Neptune Systems denies the existence of the status.json and states people should use the status.xml. However, I have found that the json is much more complete than the xml is.
  • Provides attributes for the most common (and known) variables from a variety of modules.
  • Can "recognize" modules attached to the Apex including Apex itself, EB4, EB8, EB832, PM1 (if pH in use), PM2 (if Cond in use), AFS, FMM, VDM, AI, Vortech, Trident, & DOS. Other modules may be recognized but I would prefer more data (if anyone wants to provide me copies of their status.json).
  • Can have a set of "custom" variables identified for additional data as the sensors all report as the name a user sets them for, not with a specific standard otherwise.
  • If the child driver is also loaded and children are enabled in the parent it will create child devices for each module recognized and put their respective attributes and events there as well. If you disable the children later, it will automatically delete all the child devices. Enabling it again will automatically recreate them the next time there is a data refresh. If you add new modules to your Apex, those will automatically get added as children during the next data refresh as well.
  • Driver checks each day for a new version of the driver and will post an event if a new driver version is available. It does not automatically update.
  • Available within the Hubitat Package Manager (HPM).

Install Instruction(s):

  1. Load the parent driver (NeptuneSystemsApex.groovy) and the OPTIONAL desired child driver(s) onto the Hubitat.
    a) Go into the drivers section on your Hubitat
    b) Select the New Driver button
    c) Select the Import button
    d) Copy/paste the NeptuneSystemsApex.groovy link from the very first post into the field and select Import.
    e) Select the Save button.
    f) Repeat a-e for the child drivers if you will want to enable child devices.
    NOTE: Load the Hubitat NeptuneSystemsApexChild.groovy if you want the read-only generic child driver. Load the NSChild-[others].groovy drivers if you want active control capabilities.
    WARNING: Actively controlling your Neptune System modules from Hubitat CAN interfere with their control by the Apex itself as it is replicating the manual override methods a user can select in their browser interface.
  2. Go to the Devices section on your Hubitat.
  3. Select the Add Device button.
  4. Select the </>Virtual button.
  5. Enter the device name you want, select NeptuneSystemsApex from the Type dropdown, then select the Save Device button.
  6. In the parent device preferences, enter the Apex controller's URL. If you have authentication required and/or going to perform active control, you MUST also enter your username/password as part of the URL. It would be formatted like: http://[username]:[password]@[IP/Hostname] Just replace [username] with your Apex's admin username, [password] with the appropriate password and [IP/Hostname] with the IP or Hostname used to get to the Apex (as normal now).


  • New/updated versions could appear at any time. The links listed above will remain valid (they do not change for versions) and I will make a note in a new post whenever a new version is published.
  • When using an Apex Classic or Jr. that requires authentication to poll the JSON file, you can still use these drivers. These versions of the controller do not use any particularly secure method of authentication, so in order to query the JSON enter the URL in the form of: http://[username]:[password]@[IP/Hostname]
    Just replace [username] with your Apex's admin username, [password] with the appropriate password and [IP/Hostname] with the IP or Hostname used to get to the Apex (as normal now).

Keep going with this... I too have an Neptune Apex system. Are you developing this for the 2016 model or will this work with the classic models as well? besides outputting info on the dashboard, what else are you planning on doing with this?

1 Like

NICE! I'm using ReefPi to query my Apex controllers at the moment, but I've been working (very, VERY slowly) on getting that integrated to HE.

You might want to take a stab at getting it to to work using something like WATO (or maybe even ping @bangali and see if you could incorporate some of his WATO code into this project).

Ideally what I'd like to see is if we could rely less on Apex and utilize more of the Hubitat platform to perform the same tasks and data logging that Apex does and put less reliance on Apex expensive equipment. Don't get me wrong, I love my Apex, but I believe their equipment is very over priced.

1 Like

RIGHT?! For my two tanks, I think I've given Neptune over $5K already. Granted, I've spent hundreds on my fish as well (my juvenile Tessalata Eel cost me $250 and I'm looking at getting two young female/male Cat Sharks soon), but for what Neptune offers in the Apex line, it boggles my mind every time I think about how much I've spent on their equipment. Hence why I've been slowly migrating things over to ReefPi.

I bough a classic package minus the ORP probes... and I was lucky enough to win an Apex JR when they were still making them from a local swap. I did however recently buy a new 2016 brain when they went on sale about 6 months ago... and I'm sure I'll buy new probes and stuff I need for my new build... but I'm about a year out from that... I just put a down payment on having a new 185g tank made by Reef Savvy. I'm willing to spend the money, I just want to do it right the first time and not have to spend twice or even 3 times.

1 Like

Ohhhh you'll LOVE that tank. I have a 300g from Custom Aquariums that's still waiting to be setup in the next couple of months. I have to finish the sump in the basement first. My eels and panther grouper are quickly starting to outgrow my 90g that I have them in now. sigh

Pro tip: When buying eels (and groupers), always look at their max growth size... lol :wink: I have a brother/sister pair of Snowflake eels. My female is smaller (~17" right now), but her brother is a whopping 27" long now and chubby (yes, I totally fat shame him lol). The one I worry about the most though is the Tessalata Eel as he is a true Moray and is probably going to hit his full 4'-5' size.

I’d never have a grouper because I know how large they get. As a diver, I’ve seen them bigger then I in the ocean. Lol. On the flip side I’m more into growing the coral so I need / want fish that are reef safe and won’t eat each other. =D

1 Like

Yeah, I have my community reef tank as well (which houses my fox face, tangs, damsels, mandarin goby and such), but I've ALWAYS wanted a true predator tank since I first started getting into aquariums. My dream is to one day have an octopus tank. But, given their short lifespan in captivity and the amount of work keeping the tank sealed, I've never attempted it.

To be fair, I love my grouper because of how big he's getting (he's at about 11" right now). I saw one at my LFS a few years ago that was easily 35" and I just stood there gaping in awe of it.

if the driver is publishing those attributes in HE it will work out of the box with WATO. no code changes should be necessarily :slight_smile:

While I am making it with my 2016 Apex in mind (my Classic controller fried just after the Apex came out) if I remember correctly it should work just fine with the Classic. The status.xml file is located in the same place (cgi-bin/status.xml) and I think has the generally same formatting. I could make that more flexible if it does not work as is. If you want, and are willing, you could always send me a sample xml if it does not work. Being able to enter the names of the probes really helped mine because I have two aquariums (one fresh, one marine) being monitored. The fresh only has temp and pH.
My primary goal was showing the information then having a basic reaction to the temperature, since the Apex should handle the rest. If you have ideas for more, let me know as I am always open to ideas.
Neptune Systems stuff is pretty pricey but most of the alternatives have died off whether companies or people's projects. I built my own simple controller a few years back. But partway in I realized it was going to cost almost as much and was going to eat so much more time to get it right, that I went back to their controller (this was after my Classic died). I have personally had good luck although I am not interested in their "Fusion" offering.

Posted version 0.3. Basically I corrected an error I made with the temperature value (it must be lowercase to show in the dashboard and rules properly), added more comments, corrected the logging, and did some general cleanup. I have now proven (on my system at least) that rules checking it's temperature work properly.

Next thing I want to look into is a dashboard tile to show all the probe values... plus I may look at adding in power readings or such. If anyone has requests, let me know.

What I'd be interested in seeing is the ability to capture the logs within the Apex and export them using NodeRed and InfluxDB. So I can get more historical data graphing instead of just once a day, once and hour or only once a week.

Well, the values can be read from the status.xml as quickly as you feel like punishing the Apex. I made the driver use just the minutes methods, but there are millisecond versions (if you wanted to query faster than every minute). You would have to send that data to your preferred method...

Maybe they could be sent to a global variable that could then be read?

Version 0.4 is now posted at the above link. This new one adds the ability to check the values and provide an Alert or Warning depending on how far they are from the target. It is VERY simple at this time:
If the probe is > Target + Variability or < Target - Variability it will result in a Warning
If the probe is > Target + ( Variability * 2 ) or < Target - ( Variability * 2 ) it will result in an Alert

There is not really anything being DONE with those yet besides a message... but it is a start.

I have also altered the logging a bit so not all logging messages are equal (some things I think people would only care about for debugging, so they will ONLY show when debugging, etc...).

Version 0.6 is now the latest. The main change was making the driver check my website to see what the latest version is (original concept from @Cobra). It just checks a simple xml on my site once a week to see if the version listed in there is newer than what it has in the driver, then sends an event if it is, or if it already has the latest.

Working on version 0.7... Right now the only confirmed change is reporting the software version of the Apex. I am looking at reporting the current state of the outlets, but that might be further out if my tests do not go well. Wanted to get power reported but due to the way the 832 reports power it does not look like that will be as easy.

Any feedback from anyone on it so far?
Requests for features?
Is the warning/alert useful or not? I am not sure it is all that useful versus building more customized ones in Rules, but interested in opinions.

I would like to figure out how to make a custom tile for the dashboard... Unfortunately most of my searches have not helped with the basics of that and the Hubitat documentation is still pretty lacking for development. In the meantime I would assume people can use @Cobra's SuperTile. I have not used it myself (besides looking at the description in the posting) because I want to learn how to do it myself.

In any case, hoping for some feedback because right now it is doing the basics I need and more, but not sure where else to go with it.

One last item, of the folks that have Apex units, do any of you have sensors beyond the basic 4 (temperature, pH, ORP, and Salt)? If so, would you be willing to post the bit from the xml showing how they are reported, or send me a copy of the XML? I want to see how they are reported so I can include them in the future.

I don't have this setup yet as I don't have my new system up online and won't for awhile, but how about reporting the status of the switches connected to a BoB? Perhaps send an alarm to pushover or speech if a switch changes to a certain state?

Alarms for temp too high? PH too high? I get those out of the apex so I'm not sure what benefit they would be from Hubitat other then it's just another "option". One thing I'm looking at doing in the future is running my lights off hubitat. I don't care about ramping up and down, and neither do my coral... on / off... I can use an enterwave outlet with a power bar connected to one switch and connect all my channels between two or three enterwave outlets and just let hubitat power them on and off and free up those outlets on the EB832.


  1. I would love to have done the switches but status.xml does not appear to contain the switches from BoBs... I have 2 sets of them and not a single switch (despite my actively using some in my top-off system and shown on my dashboard) shows up in the status.xml. So unless Neptune Systems makes a change there... I do not think I can make that happen.
  2. Setting an alarm or message/speech would be something in the rules watching the driver, not so much the driver itself. But you can write a Rule that will monitor any part reported, so that is a plus.
  3. For the sensors low/high notice... I agree I am not sure if there is any value to having them in the driver either. Not only is the Apex the initial stage, but I think it would make more sense to write any "too high" or such values into a Rule monitoring the values. I may actually deprecate this portion of the driver if nobody really uses it (I have not found much use for it myself yet).
  4. Hubitat could easily set an outlet (or multiple) on a timer schedule and could be completely unrelated to the Apex, so that is easy to do in Rules. I had a classic Apex and 2 sets of outlets for it (used ones can be found fairly cheap) and when that Apex died I bought the new model. The old outlets work just fine with it, so you could always go that route. If you find a deal, it could be cheaper than a bunch of WiFi or ZigBee outlets.

Version 0.7 has been posted. I did a bunch of general things to this one:

  1. First and foremost I cleaned up my thank you and attributions.
  2. The Apex's software version will now be reported.
  3. The driver can now log every outlet reported when it is set to Debug logging. If you check your logs after that point it will show the total number of outlets then run through EVERY single one, listing their name and the current state. The outlets are NOT reported as events or displayed in the driver yet... as I need to figure out how to do that in a reasonable manner. My system has 42 outlets (Apex reports variable speeds, sound, and email alarms as outputs also, I only have 24 ACTUAL outlets + two 24V outlets). In any case, even with the most basic system that would be a bunch of things to display. So I need to figure out a cleaner method.