Reef nutrition

Update to Apex Comprehensive Reference Manual Please

JVU

BOD
Staff member
Neptune folks,

Please consider coming out with an update to your Apex Comprehensive Reference Manual. The last update was apparently in 2014, and a lot has changed since then, including the modern Apex controller and all of its superior features, new modules, significant advances in Fusion, fixes to most of the previous hardware and software problems, setup wizards, and lots of 3rd party equipment.

I still look at the manual when I need to understand the programming language better, but honestly that’s the only part that is still useful. Even then, about half of the programming section is out of date because it gives complex work-arounds to shortcomings you‘ve already directly fixed, or discussion about how to tortuously manually program things you now have better wizards for.

The current Apex/Fusion system is much better, but not straightforward enough that it doesn’t need a comprehensive manual. As of now it doesn’t have one. But it seems like you guys could come up with one pretty easily using parts of the old manual and other scattered resources you and the community have already made out there. I would also suggest that you flesh out the advanced programming part a bit (especially with examples) since there are some common uses not addressed in the old version.

I don’t know what affect the pandemic is having on work for you guys, but if some of you are finding yourself with extra time on your hands, maybe this project would be a great and appreciated way to stay productive!

@Vhuang168 @jonmos75 @Terence
 

JVU

BOD
Staff member
Thanks for the response and for the link Vincent. I’m aware of the getting started walkthroughs. I’ve used them, and they are very useful for initially setting up the system and modules. Big improvement for folks new to the various systems/components, and much appreciated!

From my point of view they don’t take the place of a solid reference manual though. You can’t really find answers to more advanced questions, most notably for any kind of manual programming. The only Neptune resource for that (that I’m aware of) is the Apex Comprehensive Reference Manual, which is out of date in many respects. One can google search and spend a lot of time on dead ends in hopes of coming upon someone who answers a question or gives a useful example on a forum, but this also doesn’t take the place of a reference manual.

Maybe a better way for me to ask what I was really getting at is, can we have a revised version of the truly reference parts of the Reference manual? Doesn’t need to include the startup details since you already have great resources for that.
 

Vhuang168

Guest
Thanks for the response and for the link Vincent. I’m aware of the getting started walkthroughs. I’ve used them, and they are very useful for initially setting up the system and modules. Big improvement for folks new to the various systems/components, and much appreciated!

From my point of view they don’t take the place of a solid reference manual though. You can’t really find answers to more advanced questions, most notably for any kind of manual programming. The only Neptune resource for that (that I’m aware of) is the Apex Comprehensive Reference Manual, which is out of date in many respects. One can google search and spend a lot of time on dead ends in hopes of coming upon someone who answers a question or gives a useful example on a forum, but this also doesn’t take the place of a reference manual.

Maybe a better way for me to ask what I was really getting at is, can we have a revised version of the truly reference parts of the Reference manual? Doesn’t need to include the startup details since you already have great resources for that.
Programming hasn't changed that much. There are some small additions but the Reference Manual is still valid as far as programming is concerned. Can you give me an example of what you are not seeing in the Reference Manual?
 

JVU

BOD
Staff member
Well I have gotten some the answers to my most recent specific questions there, but it is a little cumbersome with all the out of date material mixed in with the relevant stuff.

Maybe this is just a John problem but until recently I never really even looked at the Manual for my questions about my newer system because the cover, rev date, and list of systems/modules covered is so out of date and not relevant to what I own (even though the programming info is still valuable). Just updating it to remove out of date parts and expand on things that are more relevant now would help a lot and make it more approachable for many users in my opinion. Not a total re-write, just a tune-up.

For example I didn’t really understand until recently (these are in the Manual to some extent but not really elsewhere):
- How the programming commands are processed in order once per second or so starting from the top and going in order, except for a few commands that are order-independent.
- How the state of the output is resulted only once per cycle, after going through all the commands.
- How the Defer and Min time commands work by affecting all commands that have the same On/Off output, not order dependent.
- How the 000 and other default time measurements work with various commands.
- How the OSC command works (still doesn’t really make sense though).
- Fallback vs Set and how important this is.

Details I still don’t understand or at least would like to have more info on:
- Which commands can and can’t use the integrated time delay. I’ve seen examples of it used, but I don’t understand the logic for statements I haven’t happened across by chance. For example, my Return pump has a 1 min or so delay between when it gets power and when it starts, So I want there to be a delay in the command to have the skimmer off when return is off. Could do this with Defer, but then it would be deferring all the similar commands in my Skimmer programming, which is shut off for a variety of other reasons. It seems like Defer also works on the initial Set On command, but also not so clear. Would be nice if I could put 002 or something in the right place in the command that turns off Skimmer when Return is off, perhaps needs a negative command or a virtual outlet?
- Which commands need “=“ vs just stating. For example, outlets need “=“ but Feed, Power, others just go by state. I’d like to understand this better because I feel like I’m just copying other people’s code and not sure if it will work the way I want.
- Some more examples of how to use commands I never see people use, like Min time.
- Some more examples of how to use virtual outlets.
- Some more examples of how to use negative logic to achieve and/or type statements.
- Profiles. Don’t understand those at all.

By no means am I saying it has to include all the somewhat random questions I listed. Of course I defer to your team’s judgement about what should be in an updated manual. For the most part, I‘ve got my programming working by seeing what the wizard comes up with, trial/error, and copy/pasting other people’s code. This works ok most of the time. But a nice updated reference manual would be great, and just the act of updating it even if you didn’t add much but just deleted the out of date parts would make it much more approachable and relevant for people I think.
 

Vhuang168

Guest
The 1st series of questions are all in the manual as you said.

The 2nd looks to be more about syntax and not fully understanding the uses of some of the statements.

I've attached the Quick Reference Guide, which is found on pg 161 of the manual. It will show you what has the = and what doesn't as well as the syntax required by other commands.

Screen Shot 2020-03-26 at 7.49.52 AM.png


Examples follow the guide but it is only a few. There are examples in each of the sections discussing specific commands.

Below are the examples of the OSC statement.




Example 1 - Consider the following example (remember the times are OFF/ON/OFF in minutes and seconds):

OSC 0:00/15:00/45:00 Then ON

The above will be ON for 15 minutes beginning at midnight, then OFF for 45 minutes. So at 3pm it would be ON from 3pm – 3:15pm then OFF until 4pm and repeats through the day.

Example 2 - However, if we change it just a little

OSC 45:00/15:00/0:00 Then ON

It will be OFF for 45 minutes at midnight, then ON for 15 minutes. So at 3pm it’s OFF until 3:45, then it is ON from 3:45 – 4:00pm and continues to repeat that way through the day.

Example 3 - Or, reverse the OFF/ON/OFF to be ON/OFF/ON but keep the same 15 minutes out of the hour, however now you have two ON times per cycle instead of one:

OSC 7:30/45:00/7:30 Then OFF

All of the above examples run for 15 minutes out of the hour for a total of 6 hours per day – the only difference is when the 15 minutes happens – 1) at the top of the hour, 2) at the end of the hour or 3) a little up front and a little at the end! So keep this in mind when you’re testing the command at 8pm and wondering why it doesn’t work.



That is found in the OSC page.

If the examples do not illustrate the use, the best resource is the forum. Users post their programming there all the time and you can scan through and see what works, what doesn't.

I would also suggest using virtual outlets to test programming. For example for your return pump, use a VO to simulate the pump so that any tests you conduct, do not affect the way your pump works now.

I would also suggest that instead of copying and pasting code, understand what each line does so you can implement it in other outlets.

You can always reach out if you have questions regarding code. It's not hard once you get a few under your belt.
 
  • Like
Reactions: JVU

JVU

BOD
Staff member
I appreciate you taking the time to help me Vincent. My original request was not really for personal help, I know that Neptune Support is the best and has always been very helpful when I’ve engaged it.

Rather, I was trying to suggest an update of the Reference Manual for the good of Neptune and it’s customers. You will need to do something along those lines eventually as it gets longer in the tooth every year. I can only assume that a lot of people are like me and use their Apex for months/years without even looking at a manual for hardware they don’t own for guidance on the underlying code for the hardware they do own. I gave all those examples because you asked what kinds of questions I was having, not because I’m trying to hog your gracious support here. Thank you!
 

Chromis

Supporting Member
I can give an example - because the manual is outdated, just this week I had to go to the boards to find out how to turn off the Apex WiFi. There was no direct/clear Q&A thread for that and I ended up wasting 30 mins on the boards.

An updated manual should ultimately reduce workload since it might prevent some of the repeated questions on the boards, as people would be more inclined to actually read the manual before posting questions.

I second @JVU’s suggestion.
 

rygh

Webmaster
Staff member
Hmm, I actually disagree in a way.
In this day and age, I think it is better to strive to NOT NEED a manual.

Because everything is browser based, there is no need anymore for cryptic menu systems and abbreviated settings.
Tweak the user interface to make it more intuitive.
This takes more time at first, but means no fancy manuals, and a lot less support calls.

Plus, context sensitive help is easy.
Each settings page should have a little "?" button to click, that takes you to the appropriate section of what was originally in the dense manual.

--- Example --

The "OSC" command should not exist!
OSC 45:00/15:00/0:00 Then ON
Should NEVER be seen by the user other than some summary log or something.
You should click on an add-timer button or something.
That should give you some pull downs on start, stop, and loop times.
And next to it should be a little graph that appears visualizing what it will do.
 

JVU

BOD
Staff member
Hmm, I actually disagree in a way.
In this day and age, I think it is better to strive to NOT NEED a manual.

Because everything is browser based, there is no need anymore for cryptic menu systems and abbreviated settings.
Tweak the user interface to make it more intuitive.
This takes more time at first, but means no fancy manuals, and a lot less support calls.

Plus, context sensitive help is easy.
Each settings page should have a little "?" button to click, that takes you to the appropriate section of what was originally in the dense manual.

--- Example --

The "OSC" command should not exist!
OSC 45:00/15:00/0:00 Then ON
Should NEVER be seen by the user other than some summary log or something.
You should click on an add-timer button or something.
That should give you some pull downs on start, stop, and loop times.
And next to it should be a little graph that appears visualizing what it will do.
I don’t see that as disagreeing, but rather a much larger enhancement request for the future, which they obviously already acknowledge the importance of given that all of their recent changes are moving that direction. All great improvements.

Apple surely does take that approach, and although I love the results of their many $millions and many thousands of engineer hours invested in making their products intuitive, I don’t think a hobby product like Apex is even remotely in the same ballpark of customer base and resources to invest. Also it’s worth noting that when you do need some reference manual type resource from Apple, you basically just don’t get it, something many thousands of people have complained about bitterly for many years.
 

rygh

Webmaster
Staff member
I don’t see that as disagreeing, but rather a much larger enhancement request for the future, which they obviously already acknowledge the importance of given that all of their recent changes are moving that direction. All great improvements.

Apple surely does take that approach, and although I love the results of their many $millions and many thousands of engineer hours invested in making their products intuitive, I don’t think a hobby product like Apex is even remotely in the same ballpark of customer base and resources to invest. Also it’s worth noting that when you do need some reference manual type resource from Apple, you basically just don’t get it, something many thousands of people have complained about bitterly for many years.
There are iPhone manuals.
Easy one: https://support.apple.com/guide/iphone/welcome/ios
Every gory details you might want: https://developer.apple.com/documentation


Quite often, spending a lot of time and money on an intuitive UI is totally worth it.
  1. A UI is a one-time investment.
  2. Better product = more customers (obvious)
  3. Confusion over the user interface are a VERY common cause for returns
  4. Phone support due to user interface confusion really adds up, and is ongoing


KEY : Intuitive != fancy
 
Top