Doc update

README.md

@@ -2,21 +2,40 @@
 
 ## General Description
 
-Enguino (a portmanteau of engine and Arduino) is an inexpensive _(about $100)_, lightweight _(2 ounces w/o case or cables)_, small _(about the size of a bar of bath soap)_, [open source] engine monitor for experimental aircraft. The engine monitor is displayed on a tablet as a web page. Here is an [example] of a typical Enguino display. The tablet can be an iPad, an Android or any other tablet that includes a modern web browser and has wifi.
+Enguino (a portmanteau of engine and Arduino) is an inexpensive _(as cheap as $100)_, lightweight _(2 ounces w/o case or cables)_, small _(about the size of a bar of bath soap)_, [open source] engine monitor for experimental aircraft. The engine monitor is displayed on a tablet as a web page. Here is an [example] of a typical Enguino display. The tablet can be an iPad, an Android or any other tablet that includes a modern web browser and has wifi.
 
 Enguino is intended to work with the [Stratux] ADS-B receiver which is also open source. The Stratux acts as a Wifi router for Enguino. For airplanes not equipped with a Stratux it is still possible to create an Enguino system with slightly different hardware and a small change to the configuration.
 
 The hardware consists of a tiny single board computer called an [Arduino]. This board is similar to the Raspberry Pi used in the Stratux, although the Arduino has a much simpler computer on it. Despite being a simple computer, the Arduino is much better at connecting to the real world.
 
-Because Enguino is experimental, it is recommended that you don't replace your legally required gauges with Enguino until you've confirmed to yourself that its readings are accurate and reliable. Also tablets and and wifi communication alone shouldn't be counted upon for critical flight information. Furthermore you may not have a dedicated tablet for Enguino. For these reasons an auxiliary display is an optional part of Enguino. It consists of a simple LED display that normally displays tachometer and fuel gauges but can also display engine alerts and warnings.
+Enguino connects to 8 thermocouples for CHT and EGT, a tachometer, a fuel flow transducer and seven generic inputs.
+
+Because Enguino is experimental, it is recommended that you don't replace your legally required gauges with Enguino until you've confirmed to yourself that its readings are accurate and reliable. Also tablets and and wifi communication alone shouldn't be counted upon for critical flight information. Furthermore you may not have a dedicated tablet for Enguino. For these reasons an auxiliary display is an optional part of Enguino. It consists of a simple LED display that normally displays tachometer and fuel gauges but can also display engine alarms and readings.
+
+## Aux Display
+
+The auxiliary display will fit in a 3 1/8" cutout. It consists primarily of two lines of 4 digit 7 segment LED displays. Limited text is also shown on the display.
+
+A master caution/warning annunciator, a multi-colored LED is on top. If any gauge, even those not currently being shown, is in the red range it will show red, if any in is in the yellow range it will show yellow, otherwise it will show green.
+
+A pushbutton is below the display. Tapping the button acknowledges an alert if one is displayed, otherwise it switches to the next page of information. Holding it for at least a second redisplays all alerts that have been suppressed. Holding it for 3 seconds or more toggles dimming the display for night flight.
+
+In normal operation (for a fixed pitch prop) the tachometer and fuel for left and right tank in gallons is shown as `2300` / `15:10` (2300 rpm, 15 gallons left tank, 10 gallons right). Excessive RPM's cause the tachometer to blink. On power up the following sequence would be shown:
+* `Hobb` / `123.4` only last 4 digits of hobbs shown
+* `bAt` / `12.2` alternator-battery voltage
+* ` 0` / `15:10`
+
+Whenever out of range indicators happen the display switch to showing the condition and the value, for example `OP L` / `10`. A 'warning' (red) out of range will be indicated by the first line blinking and the annunciator LED also blinking red. Pressing the pushbutton stops the blinking. Pressing it again cycles the display to the next information page. The annunciator LED continues to be red as long as the condition persists. In the case of a caution condition (yellow range) the annunciator LED turns yellow. When the engine isn't turning some alerts are suppressed.
+
+**TBD** Reenable alerts (or maybe just warnings) after x minute?
 
 ## Hardware
 
 The main board is a particular type of Arduino called the [Leonardo ETH]. This Arduino contains an ethernet adapter which is then attached to the Stratux via an RJ-45 cable.
 
 Arduino expansion boards are referred as _shields_. Attached to the Leonardo is an 8 input [thermocouple shield]. This assumes you want CHT/EGT temperatures. If not a simple [proto shield] can be used instead.
 
-The prototyping area of either of the shields will have a number of resistors and other components added to it to complete the Enguino. Some basic soldering will be required to complete this project. A parts list can be found further down. **TBD** - Instructions for assembly.
+The prototyping area of either of the shields will have a number of resistors and other components added to it to complete the Enguino. Some basic soldering will be required to complete this project. A parts list can be found further down. **TBD** - Instructions for assembly or create circuit boards.
 
 ## Software
 
@@ -72,7 +91,7 @@ The horizontal gauges (gs_horiz) are typically for handling 3 or more CHT gauges
 
 The aux display can display a number of pages during startup. After that it displays a default page. Following that are a number of information pages.
 
-A page can display text on the first line, 4 characters, however not all letters are supported.
+A page can display text on the first line, 4 characters, however not all letters are supported. Some letters are displayed in the wrong case, for example 't' instead of 'T'. The letters 'M', 'W' and 'X' can not be displayed in any form. Others like 'V' end up looking the same as 'U'.
 
 Each line can be associated with a sensor. If the first line has text and is associated with a sensor it will show caution (the letter L or H will replace the last character) or alarm information (the line will blink).
 
@@ -165,7 +184,7 @@ The main webpage has a timer running in Javascript on the tablet that invokes a
 
 The sensor system is fairly generic but currently only Van's Aircraft engine sensors have predefined configurations. The resistive sensors will have a 240 ohm(1%) pull up to +5V. This will require up to 18 ma per sensor, or for the typical 5 sensors (fuel x 2, oil-p, oil-t, fuel-p) 90 ma total. This provides a good compromise between power usage, heat and loss of resolution. This provides 9 bits of resolution. To limit resistor heating to reasonable levels, .5 watt resistors should be used. Resistor temp. rise should be no more than 100 deg. C in free air. A resistance significantly out of range will mark the sensor inoperative. To convert from ADC units to ohms use this formula `ohms = 240 * (adc / (1024-adc))`, this will require long divided by long division unfortunately or a lookup/interpolation table.
 
-Many of the sensors are 240-33.5 ohm sensors similar to Stewart Warner. These usually scale linearly by resistance. For those that don't, a custom interpolation table may be required. The oil temperature sensor is also resistive (its a *thermistor*) but it has a larger range. Using a Steinhar-Hart calculator the conversion formula becomes `degrees Kelvin = 1 / (0.0016207535760566691 + 0.0002609330007304247 * log(R) + -1.0278556187396396e-7 * log(R)^3)`. An interpolation table is used to convert this.
+Many of the sensors are 240-33.5 ohm sensors similar to Stewart Warner. These usually scale linearly by resistance. For those that don't, a custom interpolation table may be required. The oil temperature sensor is also resistive (its a *thermistor*) but it has a larger range. Using a Steinhar-Hart calculator the conversion formula becomes `degrees Kelvin = 1 / (0.0016207535760566691 + 0.0002609330007304247 * log(R) + -1.0278556187396396e-7 * log(R)^3)`. This is far too complicated to solve on the Arduino so an interpolation table is used for the conversion.
 
 For resistive sensors still attached to the gauge, the gauge itself provides the pull up resistance and voltage. For Vans Aircraft engine instruments the pull up is 5 volts and the resistor is about 227 ohms(measured externally, internally the resistor appears to be 240 ohms, 5%). The pin can be directly connected if the voltage can't exceed Vcc by more than .5v. Otherwise a 15K series resistor could be attached to help isolate the pin.
 
@@ -183,20 +202,11 @@ The tachometer measures RPM by recording the uS time whenever the pin has a risi
 
 ### Auxiliary Display
 
-The auxiliary display consists of two lines of a 4 digit [7 segment LED displays]. Limited text is shown on the display. Some letters are displayed in the wrong case, for example 't' instead of 'T'. The letters 'M', 'W' and 'X' can not be displayed in any form. Others like 'V' end up looking the same as 'U'.
-
-A master caution/warning [bicolor LED] annunciator is reworked by soldering onto two unused display row of the top display. Red - warning(fix it now or land), yellow - caution(look into it before it becomes a problem), green - ok.
-
-A pushbutton is also part of the display. Tapping the button acknowledges an alert if one is displayed, otherwise it switches to the next page of information. Holding it for at least a second either acknowledges all alerts or redisplays all alerts. Holding it for 3 seconds or more toggles dimming the display for night flight.
-
-In normal operation the tachometer and fuel for left and right tank in gallons is shown as `2300` / `15:10`. Excessive RPM's cause the tachometer to blink. On power up the following sequence would be shown:
-* `Hobb` / `123.4` only last 4 digits of hobbs shown
-* `bAt` / `12.2` alternator-battery voltage
-* ` 0` / `15:10`
+The auxiliary display consists of two lines of a 4 digit [7 segment LED displays]. Both are strung together on the same i2c communication bus, but the bottom display has the A0 jumper soldered so they can be individually addressed. The displays have power (from the shield board), ground, a data line and a clock line going to them.
 
-Whenever out of range indicators happen the display switch to showing the condition and the value, for example `OP L` / `2.4`. A 'warning' (red) out of range will be indicated by the first line blinking quickly and the annunciator LED also blinking red. Pressing the pushbutton returns the display to showing tachometer and fuel. The annunciator LED continues to be red as long as the condition persists. In the case of a caution condition (yellow range) the annunciator LED turns yellow. When the engine isn't turning some alerts are suppressed.
+A master caution/warning [bicolor LED] annunciator is reworked by soldering onto two unused display row of the top display.
 
-Once an alert has been acknowledged the display will no longer switch to it automatically. To reenable this hold the button for at least a second. The master LED annunciator will show if an caution or warning condition persists or reoccurs, but it will not blink. **TBD** Reenable alerts (or maybe just warnings) after x minute?
+The pushbutton is connected to ground on one side. The other side of the switch goes back to the shield.
 
 ### Parts list
 * Arduino Leonardo ETH - Digikey 1050-1007-ND
@@ -221,8 +231,8 @@ Once an alert has been acknowledged the display will no longer switch to it auto
 ### Future stuff
 * Record engine data by having the Engiuno pipe text to a port on the Stratux. The startup script on the stratux starts netcat (nc) in the background to record the text to a file. The script would also truncate the file at on powerup to limit its growth.
 * It may be possible to support 2 (or maybe more) thermocouples without the thermocouple multiplexer shield by using the differential mode ADC, 40x gain and a CJC sensor(Analog TMP36). Only 8 bits are usable with 40x, the noisy lower bits help with oversampling though. 488 uV per count works out to 21.5 deg. F resolution with a K type thermocouple. The 2.56 volt internal reference would double the resolution and oversampling could probably quadruple it (16x oversample). ADC0 and ADC1 are the negative side, any other ADC pin may be positive. With a filtering cap (10nF) several thermocouples could share a pin. The internal ATMEGA temperature sensor needs both offset and gain calibration, a 10 deg-C rise is typical as well, 2 point calibration may be much to expect for users. **TBD** - move the voltage divider sensor to ADC5 to allow future use of thermocouples.
-* A custom shield might be helpful for the typical user who isn't proficient with a soldering iron, particularly if it were populated. Jumpers would select resistors and maybe filter caps. A thermocouple board that didn't interfere with the ADC would add 4 more analog inputs (perhaps a latch for the mux or an I2C thermocouple/mux like Linear's LTC2495CUHF#PBF). An ammeter feature will be desired by some, TI's INA170 High Side Current Shunt Monitor is probably a good part to implement this. Support 12 thermocouples for 6 cylinder? Support for 24 volt electrical system?
-* A custom aux display board would also help. A single HT16K33 LED drive chip could be used for both displays as one chip can support 8 LED digits. A smaller 7 segment LED modules could be used to allow fitting the display in a 2.25" hole. A long posted tactile pushbutton switch mounted to the board that would go through a small hole on the display (similar to a digikey EG4356TR-ND) could replace the current switch. The switch wire could be eliminated from the harness if 2 or 3 separate switches are attached to the chip. More switches would be required as the chip can only detect presses, not holds.
+* A custom shield would be helpful for the typical user who isn't proficient with a soldering iron, particularly if it were populated. Jumpers would select resistors and maybe filter caps. A thermocouple board that didn't interfere with the ADC would add 4 more analog inputs (perhaps a latch for the mux or an I2C thermocouple/mux like Linear's LTC2495CUHF#PBF). An ammeter feature will be desired by some, TI's INA170 High Side Current Shunt Monitor is probably a good part to implement this. Support 12 thermocouples for 6 cylinder? Support for 24 volt electrical system?
+* A custom aux display board would make Enguino easier to use. A single HT16K33 LED drive chip could be used for both displays as one chip can support 8 LED digits. A smaller 7 segment LED modules could be used to allow fitting the display in a 2.25" hole. A long posted tactile pushbutton switch mounted to the board that would go through a small hole on the display (similar to a digikey EG4356TR-ND) could replace the current switch. The switch wire could be eliminated from the harness if 2 or 3 separate switches are attached to the chip. More switches would be required as the chip can only detect presses, not holds.
 * The Arduino Yun would support airplanes lacking a Stratux. The code would need to use the 'bridge' objects instead of the ethernet objects. Use #ifdef AVR_YUN to flex the code.
 * Themes - a dark theme could be created easily enough by adjusting the styles. A larger text theme for the gauges would involve more defines and stringizing them for the SVG.
 * Create another TCP or UDP port that can be read from the Stratux (perhaps with netcat). This would be a comma separated text stream of engine data to be logged.
@@ -231,7 +241,13 @@ Once an alert has been acknowledged the display will no longer switch to it auto
 table - www.kilohotel.com/rv8/rvlinks/o360apwr.xls www.kilohotel.com/rv8/rvlinks/io360apwr.xls
 GRT - tables for mp_at_55%(rpm), mp_at_75%(rpm), delta_hp(pres.alt), also uses OAT. The delta-hp is a constant rpm, mp in the cruise range.
 MGL - formula (3 constant) http:https://www.mglavionics.co.za/Docs/MGL%20EFIS%20G2%20HP%20calculation.pdf
-O-320 power chart http:https://preflight.dynonavionics.com/2014/02/did-you-know-percent-power-dynon-way.html
+* STP power = (((((MAPmax - ((MAPmax - MAPnow) * K1)) / MAPmax) * RPMnow / RPMmax) ^ K2)
+* Altitude adjust = ((1 + K3) * (ATMO_PRESSstp / ATMO_PRESSnow) - K3)
+* Temperature adjust = SQRT((519 – (3.58 * PRESS_ALT_FT/1000)) / (460 + OAT_F))
+* K1 and K2 are very roughly .1. Default value for K3 is -.695
+* Power % = 100 * STP_Power * Altitude_Adjust * Temperature_Adjust
+O-320 power chart
+ http:https://preflight.dynonavionics.com/2014/02/did-you-know-percent-power-dynon-way.html
 
 
 [open source]:https://en.wikipedia.org/wiki/Open-source_model