Neptune Apex Debugging Tutorial
When developing for Apex, being able to debug and troubleshoot your code is essential. There are currently three methods that can be used collectively to debug Apex:
- AquaBus/ModBus traffic capture
- Arduino debug output with ‘print’ to console
- Apex built-in no-longer-undocumented telnet commands
AquaBus/ModBus traffic capture
Capturing AquaBus traffic is trivial, yet it provides a wealth of information when trying to understand the protocol or to see what’s wrong with the protocol implementation. We already know that AquaBus is a serial RTU ModBus traffic over CAN transport. Assuming the CAN transciever is working properly and reliably, the easiest point of traffic capture is on the UART side of the transciever, between arduino and the CAN. In the example of AquaBus Arduino Adapter, you’d want to attach your logic analyzer to “TX (CAN<-AVR)” and “RX (CAN->AVR)” pins. It is up to the reader to pick an appropriate logic analyzer for this. Since AquaBus operates at a relatively low speed, many basic analyzers will work. I prefer to use a Saleae Logic Analyzer for this due to its simplicity and robust, user friendly software. There are several inexpensive alternatives, compatible with Saleae software out there.
You would want to connect “channel” probes to RTU RX and TX pins as described above. Also, make sure to connect the analyzer’s common ground to the ground pin on the adapter. Once all probes are coonected and the traffic is captured, it needs be decoded so that it is presented in a readable form. Correct settings for each channel are as follows:
Once everything is configured properly, a good capture would look like this (redacted):
Arduino Debug Output
The code in the repository includes detailed logging which can only be enabled by defining DEBUG flag in various source files, or for the entire build. Debug output is currently supported via arduino software serial library. It uses Arduino digital pins #8 and #9 for serial RX and TX respectively. A simple USB-to-Serial cable or an FTDI chip is sufficient to communicate with the software serial to pick up any debug output and display it in a terminal. Use putty or any other termial software to connect to arduino serial port to observe the output. Software serial configuration:
- Baud rate: 57600
- Data bits: 8
- Parity: none
- Stop bits: 1
Apex Built-in telnet commands
Apex supports a large number of commands, many of which can be used for debugging, troubleshooting and monitoring. Most commands are not officially documented. In this section we attempt to discuss many of them based on our research. Use these commands at your own risk.
To use these commands, telnet into Apex first with your Apex device credentials.
| # | Command | Description | Example Usage | Sample Output |
|---|---|---|---|---|
| 01 | abbaud |
Set Aquabus baud rate | abbaud 19200 | AquaController> abbaud 19200 abbaud 19200 Baud = 19200 |
| 02 | abclear | Clear out internal device descriptor table for all devices | abclear | |
| 03 | abdelete |
Delete module connected on AquaBus at address AquaBus_Address | abdelete 2 | AquaController> abdelete 2 abdelete 2 |
| 04 | abdump | Dump list of all modules connected to Apex on AquaBus | abdump | AquaController> abdump abdump hwtype hwrev swrev abaddr serial # pCount gCount eCount reatt inact 002 000 000 000 0000 144817 65 144751 00000000 24 000 000 000 000 0000 0 0 0 00000000 00 000 000 000 000 0000 0 0 0 00000062 00 020 001 00c 000 0000 0 0 0 00000012 00 hwtype hwrev swrev addr name EB8 module 001 012(OK) 003 EB8_3 |
| 05 | abfind | Scan all baud rates and find modules connected to Apex on AquaBus. If found, attempt to attach | abfind | AquaController> abfind abfind Baud = 50000 Baud = 49500 Baud = 49000 Baud = 48500 Baud = 48000 Baud = 47500 Baud = 47000 Baud = 46500 Baud = 46000 |
| 06 | abinit | Initialize AquaBus interface file ‘device.cfg’ and profile ‘profile.cfg’ | abinit | AquaController> abinit abinit |
| 07 | aboff | Disable AquaBus | aboff | AquaController> aboff aboff |
| 08 | abon | Enable AquaBus | abon | AquaController> abon abon |
| 09 | abosc |
Get osc value for module connected on AquaBus_address | abosc 2 | unknown |
| 10 | abprobe | Initiate AquaBus Probe sequence | abprobe | AquaController> abprobe abprobe |
| 11 | absetosc |
Set osc value for module connected on AquaBus_address | absetosc 2 1234 | |
| 12 | abswp | unknown | ||
| 13 | aichan |
Unknown. Likely, set AI channel and trigger attach | ||
| 14 | aiclaim | unknown. Likely related to AI management | ||
| 15 | aiinit | Unknown. Likely initialization/probe routine related to AI | ||
| 16 | amp | Amp Test | ||
| 17 | auto <> | Unknown. Set Outlet related… | ||
| 18 | bt | Back Trace | bt | AquaController> bt bt Sun Moon Moon Date rise/set rise/set Int Temp Feb 01 07:37/19:07 06:57/18:57 07 75.0 Feb 02 07:37/19:07 07:46/19:46 07 75.0 Feb 03 07:37/19:07 08:35/20:35 07 75.0 Feb 04 07:36/19:08 09:23/21:23 00 75.1 Feb 05 07:36/19:08 10:11/22:11 07 75.1 Feb 06 07:36/19:08 11:00/23:00 07 75.1 Feb 07 07:35/19:09 11:49/23:49 14 75.2 Feb 08 07:35/19:09 12:38/00:38 14 75.2 |
| 19 | c | Current Status | c | AquaController> c c Current Status is: Sep 19 2019 00:07:34 Tmp pH ORP Salt 206 12.4 0 1.2 VarSpd1_I1 is PF1 Auto VarSpd2_I2 is PF2 Auto VarSpd3_I3 is PF3 Auto VarSpd4_I4 is PF4 Auto SndAlm_I6 is OFF Auto SndWrn_I7 is OFF Auto EmailAlm_I5 is OFF Auto Email2Alm_I9 is ON Auto Power Failed: Sep 17 2019 23:19:38 Power Restored: Sep 17 2019 23:19:59 |
| 20 | cal <> | Unknown | ||
| 21 | calup <> | Unknown | ||
| 22 | clear | Unknown | ||
| 23 | cons | Enable console output. Usually used for debug output | cons debug 1 | |
| 24 | cortype cortype <> | Unknown | ||
| 25 | d | Print Data Log | d | AquaController> d d Date Tmp pH ORP Salt 00:00 09/19/2019 20.6 12.4 0 1.2 00:10 09/19/2019 20.6 12.4 0 1.2 |
| 26 | debug |
Enables debug output at various levels. Usually used after ‘cons’ is enabled. Level 1 - all debug output. Level 512 - limited debug output | consdebug 1 debug 512 | |
| 27 | defeeprom | Unknown | ||
| 28 | del |
Unknown | ||
| 29 | dir |
List content of directory specified | dir | AquaController> dir dir 25157 09/18/19 23:51 SYSLOG.TXT 1000 09/18/19 23:51 DEVICE.CFG 864 09/18/19 23:51 PROFILE.CFG 0* 01/31/00 10:30 CFG 11 09/18/19 23:20 LATEST.TXT 0* 01/31/00 10:30 LOGS 0* 01/31/00 10:30 PROT 0* 01/31/00 10:30 CLASSIC 649 09/18/19 23:51 OUTPUTC.CFG 947 05/29/19 21:08 FILES.TXT 8295 06/29/19 21:09 114.PNG |
| 30 | dose |
Unknown | ||
| 31 | dsim |
Unknown | ||
| 32 | eb8getee |
Unknown | ||
| 33 | eb8setee |
Unknown | ||
| 34 | eb8zero |
Recalibrate EB8 current sensor. To use, unplug all devices from EB8 to ensure no power consumption, then execute command | eb8zero | |
| 35 | elock | Unknown | ||
| 36 | esync | Unknown. Save eeprom.dat??? | ||
| 37 | eunlock | Unknown | ||
| 38 | eventEval |
Unknown | ||
| 39 | fan |
Unknown | ||
| 40 | fformat | Unknown | ||
| 41 | frsts | Factory Reset | ||
| 42 | heap | List available heap space | heap | AquaController> heap heap Heap Avail = 84880 |
| 43 | i | Reinitialize EEPROM | i | |
| 44 | ill | Unknown | ||
| 45 | l | List programming configuration | ||
| 46 | logclean | clean newest logs from /logs | ||
| 47 | logdel | Delete old logs from /logs | ||
| 48 | m | Unknown | ||
| 49 | mail |
Most likely to configure email alerts. There is a description on Apex support forum somewhere | ||
| 50 | nidump | NI stats. Likely network/wifi related | nidump | AquaController> nidump nidump WiFi NI Data RX packets: 0 TX packets: 0 NI Stats rx_packets: 00155013 tx_packets: 00128660 rx_fr_Errs: 00000000 rx_crc_err: 00000000 rx_missErr: 00000000 rx_intr: 00283636 |
| 51 | off |
Turn off outlet | ||
| 52 | on |
Turn on outlet | ||
| 53 | outadd |
Unknown | ||
| 54 | outdel |
Unknown | ||
| 55 | p | Memory dump | p | |
| 56 | pfinit | Initialize profile.cfg | pfinit | |
| 57 | radaddr |
Unknown (radion???) | ||
| 58 | radclear |
Unknown (radion???) | ||
| 59 | radid |
Unknown (radion???) | ||
| 60 | radreset |
Unknown (radion???) | ||
| 61 | radset |
Unknown (radion???) | ||
| 62 | reboot | Reboot Apex | reboot | |
| 63 | rtest |
Unknown | ||
| 64 | sc | Unknown | ||
| 65 | sockets | List open TCP/UDP sockets | sockets | |
| 66 | t |
Unknown | ||
| 67 | threads | List Apex threads | threads | AquaController> threads threads Hndl Name Pri Status EvQueue StkPtr FreStk MinFree Ticks 20017bd8 0:23 60 RUN 20009c1c 200179a8 1936 1112 619 OK 20017110 tcpsm 32 SLP 20002e10 200170c0 944 640 2611 OK 20016cd0 mdns 64 SLP 20015924 20016c60 1932 1420 246 OK 20015518 dhcpc 64 SLP 20006f90 20015490 1288 1056 0 OK 20014e78 netl 64 SLP 00000000 20014e48 1452 416 137 OK 20014858 monitor 60 SLP 2000157c 20014738 3208 3112 0 OK 20013a70 iota 64 SLP 00000000 20013a28 3924 3112 1 OK 20012620 menu 62 SLP 00000000 200125d0 1940 1504 14 OK 20011c98 push 64 SLP 200171c8 20011b90 3932 1512 22805 OK 2000de10 event 61 SLP 00000000 2000dd20 1384 408 688521 OK 2000d778 emacrx 9 SLP 20009bc0 2000d718 1324 1084 3498 OK 2000a8f0 main 63 SLP 00000000 2000a8a0 1708 420 2919 OK 2000a1b8 idle 254 RDY 20009c1c 2000a188 720 572 91095281 OK |
| 68 | upboot | boot bootloader | ||
| 69 | update | Firmware update and reboot | update | |
| 70 | v | List Apex firmware version | v | |
| 71 | var |
Unknown | ||
| 72 | volts | Show aquabus voltage | volts | AquaController> volts volts AquaBus Voltage = 11.12 Power Conn Voltage = 12.39 |
| 73 | vtaddr |
Vortech related | ||
| 74 | vtclear |
Vortech related | ||
| 75 | vtclearall |
Vortech related | ||
| 76 | vtfreq |
Vortech related | ||
| 77 | vtinit |
Vortech related | ||
| 78 | vtquery |
Vortech related | ||
| 79 | vtreboot |
Vortech related | ||
| 80 | vtreset |
Vortech related | ||
| 81 | vtstat |
Vortech related | ||
| 82 | vttest |
Vortech related | ||
| 83 | vtupeco |
Vortech related | ||
| 84 | vtupman |
Vortech related | ||
| 85 | vtuprfm |
Vortech related | ||
| 86 | vtupvti |
Vortech related | ||
| 87 | vtuppwwd |
Vortech related | ||
| 88 | wpa |
Wav phase offset | ||
| 89 | xtal |
Change xtal source | ||
| 90 | z | Unknown |