Configuring HydraFerret on ESP32

Introduction

Once the firmware has been flashed to the esp32 module and it boots for the first time, it will need some configuration to define its environment. As a general rule: "All configuration is optional, but some configuration will be required". The suggested sequence is:

Define a unique name for the module.

In order to distinguish each module it needs a unique name. In a small environment this might be as simple as naming the unit after its location, eg "kitchen". In bigger environments a matrix or block naming scheme might be more appropriate, eg "aisle_1a", "aisle_1b" or "aisle_3c". It may help for consistency to keep names all lowercase, ie not capitalised. But that is purely a preference option! eg:

devicename riverRd_20

Set processor speed

This is an optional step to set the processor speed. HydraFerret should perform well at the lowest speed, but sometimes a demanding application may require more CPU cycles. Acceptable speeds are 80, 160 and 240 MHz. Faster speeds will cause the CPU to run a little warmer and consume a bit more power.

cpuspeed 160

Define network connections.

Up to 4 networks may be defined. While normally only one network is required, it is sometimes useful to define networks in multiple locations in a module moves physical location or may be covered by more than one network.

wifi [<0-3> <ssid> [<password>]]
This defines a network connection to connect to. If there is network security, the password will also need to be specified. Running "wifi" without parameters will list the networks which have been defined. eg:
```
wifi 0 SushiOne MisoSoup20200120
wifi 1 SushiToo BentoBox20191209
```
wifimode [alwayson|ondemand]
This determines if the network is always connected or not. Some power savings are gained by turning the network off when it is not required. This is important for units powered by batteries with limited capacity. If a telnet service is required, then alwayson is required. The default is alwayson. eg:
```
wifimode ondemand
```
wifiscan [enable|disable]
When wifiscan is enabled, the module will choose the WiFi with the strongest signal. However, no SSIDs should be hidden for this to work correctly. Hidden SSIDs will be ignored if wifiscan is enabled. If wifscan is disabled, the SSIDs are probed in their number sequence and the first one to respond will be chosen. This will work with hidden SSIDs. the default is wifiscan enabled. eg:
```
wifiscan disable
```
ntp [<ntp-server|none>]
Optionally define a network time protocol (NTP) server. This allows the HydraFerret module to aquire the correct time. The default time server is pool.ntp.org - and will probably work for most installations. eg:
```
ntp 192.168.0.1
```
timezone [definition]
If you are not in the West African (default) timezone, you probably want to adjust the timezone to your own. There are a number of timezones defined, which can be listed using the "list tz" command. These can then be used to define the timezone, eg:
```
timezone QUEENSLAND
```

Define pins used to connect to sensors

Use as few or as many of these as you require.

i2c [<0-1> <sda> <scl> [speed]]
Up to 2 i2c busses may be defined. If the SDA and SCL pins are the same, the bus will be disabled. HydraFerret should autodetect new devices added to the the i2c bus, but you may opt to do further configuration as as rename them or change the frequency they are polled at. eg:
```
i2c 0 21 22 100000
```
onewire <bus-number> [disable|<pin>]
Up to 4 OneWire busses may be defined. These connect temperature sensors. eg:
```
onewire 0 27
```
adc [<pin> <unit-of-measure> <attenuation> <offset> <multiplier>]
Only pins 32-39 can be used for analogue to digital conversion (ADC), additional parameters define offset and multiplier values to use. eg:
```
adc 34 light 3 100 -0.02442
```
counter <0-7> disable counter <0-7> <0-39> <unique-name> <unit_of_measure> <offset> <multiplier>
These define the pins used to connect pulse sources for counters. eg:
```
counter 0 12 bath litres 0 0.015
```
serial [0|1] <rx-pin> <tx-pin> <speed> <bits> serial [0|1] [disable|pms5003|zh03b|mh-z19c|winsen|ascii|nmea] These configure the pins and speed to use for serial connections and the type of device connected to them. eg:
```
serial 0 12 14 9600 8n1
serial 0 pms5003
```
identify <pin> [invert] identify [on|off|flash|fflash|sflash] [persist]
Define a pin to use as an identify function, this usually connects to a LED on the esp32 module. eg:
```
identify 5 invert
```

Define any outputs

HydraFerret will work without any outputs, but it can support up to 8 outputs. These permit a limited amount of control of external devices. When evaluating outputs these are processed sequentially from the lowest numbered output (0) to the highest (7). Thus these may be considered as a small and simple program.

output [<0-7> disable]
output [<0-7> default <value>]
output [<0-7> <pin> <relay|pwm|servo|var> <name> <rpn expression>]

Define the xymon server to report to.

xyserver [<DNS-name>|<IP-Address>|<URL>|none [port-number]]
This setermines the xymon server to act as a destination, and optionally the port number to use. The default port number is 1984, and this is only used when using the native xymon protocol. Where a URL is specified the default http/s port will be used. eg:
```
xyserver 192.168.0.10
```
xysecret [<string>|none]
This is only used when the xyserver is a URL. It gives an additional secret which is sent to the webserver fronting xymon to authenticate the HydraFerret module using it as a shared secret. eg:
```
xysecret de7191b7-9681-41ab-b9cc-0d164c766ce3
```

Enable/disable options

Running the command "enable" will list various options and their on/off status. HydraFerret should work fine without setting any of these, but they do allow greater customisation of each unit. The opposite effect is made with the disable command. Where enable is shown as an option disable will work too.

enable ansi - ANSI colorized terminal, escape codes are not supported by all terminals. Can verify support by running "ansi" command.
enable consolelog - console logging to file. This allows console history to persist over a reboot.
enable memory - memory stats displayed in xymon, by default these are not displayed, shows as a "memory" column in xymon.
enable output - Output status displayed in xymon, by default these are not displayed.
enable otaonboot - OTA update check on boot and new code downloaded if available.
enable startupdelay - 60 second boot startup delay, by default this is disabled. It allows some console access pror to device discovery taking place.
enable showlogic - Display alert logic on xymon console as an additional line if a warning / critical / extreme alert is detected. By default it is disabled.
enable telnet - telnet service, to permit remote access. Note this is not a traditional telnet session, but remote access to the HydraFerret system console using a standard telnet client.

Other options

Set a hibernation time: On some systems it may be desirable for them not to run at certain times of the day. For example on a solar powered system which would not return interesting data over night. The hibernate command puts the processor in a deep sleep for the hibernation period. The processor will still require power during this time, but it is minimal.
```
hibernate 18:00 06:00
```
Set a monitoring interval: While "acceptable" monitoring may be achieved by making one sample per monitoring period, that is not usually a good practice. It is better to sample many times per monitoring interval. For xymon the monitoring interval is 5 minutes. During that time HydraFerret could take 300 samples (one per second). the "interval" command cand be used to adjust the sample interval between 1 and 300 seconds. There are various reasons to do this, including:
- the sensor may have some variability, and multiple samples in a period will smooth the effect of variability in individual samples
- the environment might change through the sample period. eg: a freezer door is opened for 35 seconds during the 5 minute monitoring interval. If the sample is taken when the door is open the temperature will be too high. But if taken just prior to the door being opened it will be too low. The multiple samples return an average temperature value.
Combine trend graphs Graphs from several modules may be combined using the "combine" option which sends graph data to be graphed by both the module and the combine name in xymon. To get this to work the unit used as the combine name should either be collecting its own metrics or have some nominal test in xymon, eg a connectivity test with the local network router. Then under the trends heading, all HydraFerret modules with the same combine name will collect their graphs together. This allows physically separate modules' data to be easily compared. eg using the config command on each unit to be combined it is possible to group measurements for different locations such as the trends graph below:
```
combine mombasa
```

Thank you for visiting camelthorn.cloud

Home