Updating Instructions
=====================


Included in this archive are:
-----------------------------

 * controller_1_3.txt - Software update for the Soliton
 * uploader_1_3.exe - A DOS program that updates the Soliton
 * uploader_1_3 - A Linux program that updates the Soliton
 * logger_1_3.exe - The current version of the logging program (Windows)
 * logger_1_3 - The current version of the logging program (Linux)
 * logger.c - The current version of the logging program (source)
 * ReadMe.txt - This file
 * LoggerProtocol.txt - About the network logger protocol


Changes in the software version 1.2 to 1.3:
-------------------------------------------

Bug fixes:

 * Fixed a problem with Quiet mode that might be the root cause for
   desat errors in some rare situations.

Features:

 * Only run fans when the controller is warmer than 40C.

 * Increase max motor current to 600 Ampere for Junior.

 * Increased maximum allowed temperature for Junior.

Added safety:

 * Added ADC over- and underflow error.

 * Do a sanity check of the current sensor at start up.

Changes in the software version 1.1 to 1.2:
-------------------------------------------

Bug fixes:

 * Fixed a web bug that made it impossible to select LVC BMS.

Features:

 * Added logging of active limits that makes it possible to see why
   actual motor current isn't the same as throttle demand.

 * Adaptations for Junior.

Changes in the software version 1.0 to 1.1:
-------------------------------------------

Bug fixes:

 * Fixed bug that didn't shut down the controller if 12 Volt dropped
   too low (below 10V). This is a redundant safety mechanism to
   protect the IGBTs from being under-driven. Note that the controller
   first inhibits motor output (~4ms) then shuts down if the under-
   voltage condition persists (~80ms).

 * Fixed bug with temperature derating so it starts at 1000A rather
   than the max motor current setting. If, for example, motor current
   current is set to 500A then derating shouldn't kick in until 75°C
   since the IGBTs can still handle 500A at that temperature.

 * Fixed so the setting for motor overtemp can actually be changed.

 * Fixed a buffer error in the web server that truncated the drop down
   menus, making some of the options impossible to select.

Features:

 * Error codes are now stored in the on-board non-volatile memory and
   will be presented in English in the web interface upon the next
   page refresh. The errors persist until cleared with a click
   button. Both error and the running time since last startup are
   stored to make it easier to hunt down the area in the logfile (if
   collected!).

 * The warning lamp flashes during initial startup if any error codes
   have been stored (rather than briefly light solid which is done to
   simply indicate the lamp is working).

 * Improved RPM-measurement and overspeed protection. A digital filter
   implemented in software better discriminates between valid tach
   pulses and noise.

 * Performance/Quiet mode setting. In Performance mode the controller
   always operates at 8kHz for best efficiency while in Quiet mode it
   uses 14k to reduce the chance of the motor "singing", especially at
   low currents when dithering (randomized pulse skipping) is in
   effect.  Quiet mode also reduces the magnitude of ripple reflected
   back to the battery pack so is beneficial with lower pack voltages
   (<96V). The controller will automatically drop back down to 8kHz at
   high motor currents or if it goes into thermal derating. The higher
   frequency will automatically resume when current or temperature
   drops enough.

 * Motor kW-limit. It's possible to limit not only the maximum current
   and voltage delivered to the motor, but also the maximum power. A
   motor that, e.g., can withstand 1000A or 200V won't necessary
   survive both at the same time! Being able to limit power as well
   will increase the survival odds for the motor (but it is still up
   to the end user to wield the power of the Soliton1 responsibly!)

 * Idle. A proper PID loop has been added to regulate motor RPM
   despite changing loads, mainly for "idling" the motor. This is an
   industry- first feature that makes conversions with automatic
   transmissions (not to mention keeping A/C going in heavy traffic!)
   practical!

 * Start input. Allows pushbutton starting of idle, rather than
   applying throttle. Mandatory safety requirement for EU regulation
   ECE-R100.

 * Run indicator. Blinks when precharge is over the controller is
   ready to accept throttle input and/or start idling. Changes to a
   steady light when the start button is pressed.

 * Factory defaults. Erases all user settings so the controller goes
   back to, you guessed it, Factory defaults.

 * The brake signal input can now handle both normal (high when brakes
   are applied) or inverted (low when brakes are applied) polarity.

 * State of Charge meter output. Gives a rough indication of battery
   capacity remaining by looking at where the pack voltage is at
   between two user-set limits. A battery current above which point
   the SoC percent is held can be set as well. This method is of
   limited effectiveness with Lithium chemistries and is no substitute
   for an Ah-counting SoC gauge.

 * Tachometer output. Can be set to generate pulse trains compatible
   with standard 4, 6 and 8cyl. tachometers, regardless of how many
   pulses per revolution are used for the actual motor tachometer.

 * Single cell low-voltage input. Allows a BMS with an alarm output or
   NC loop to tell the controller to dial down motor current when a
   single cell has dropped below a safe level. This works just like
   the existing pack level minimum voltage protection.


Added safety:

 * Low voltage protection. If pack voltage drops 10 Volts below the
   minimum pack voltage setting then the controller considers this an
   error. Normally pack voltage will never go more than a few Volts
   below the treshold since the controller automatically dials down
   motor current to protect the pack.

 * Motor current is limited to 900A if pack voltage is above 310V.

 * If there's an "Precharge timeout, no voltage" or "Precharge
   timeout, too low voltage" error stored in the controller, there's
   an extra 10 second delay added at startup before the ordinary
   precharge sequence is initialized. This is to limit power
   dissipation in the precharge resistor that can cause it to become
   unsoldered should someone, e.g., program too high a minimum pack
   voltage and keeps cycling power to the controller wondering why it
   won't start. The delay will disappear when the stored errors are
   cleared.


Steps to update the controller software:
----------------------------------------

 1. Connect the laptop to the Soliton with an ethernet cable
 2. Wait the usual 1 minute for APIPA (see below for details) to
    negotiate a connection
 3. Choose either of these two methods to upgrade:
    a. Select the txt-file in the web interface and press the button
       "Update" (general method, extremely slow in Windows)
    b. Double click on the uploader_1_1.exe program to initiate the
       update (workaround for Windows, see below for details)
 4. Once the upload finishes cycle power to the Soliton
 5. Watch for the green LED to blink several times on startup to
    indicate it has read the new code
 6. After 1 minute connect to the web interface (http://169.254.0.1/)
    to verify the version is now 1.1. If it's not, please try to
    update the software again.


Comments about APIPA:
---------------------

APIPA stands for Automatic Private IP Addressing (also known as
Link-Local Addresses, RFC3927) and is a fallback for devices on a
TCP/IP-network to automatically get an address to be able to
communicate if there's no DHCP-server available. The controller does
stretch this standard a bit by always requesting the address
169.254.0.1, but this is to make it easy to find it in your browser.

All modern OS does support APIPA, including all versions of Windows
from Window 98, Macintosh from OS 8.5 and Linux with NetworkManager
(or similar tools) installed. If your computer doesn't support APIPA
(for example if it's turned off in the settings/register) or you can't
get it to work you can manually set an IPv4-address, for example
169.254.0.10 with netmask 255.255.0.0. Leave gateway and DNS-settings
blank.


Comments about uploader_1_1.exe:
--------------------------------

There's a flaw in the Windows TCP/IP stack that's been observed in
both XP and Vista (we haven't tested Windows 7 so we can't tell if the
bug is still present). What seems to happen is that the controller
can't buffer the data fast enough (the CPU in the controller is
probably in pair with whatever you have in your micro wave owen) and
thus it throttles the transfer.

This is normal TCP/IP behaviour and works well when I upgrade the
software in the controller from my Linux computer (takes about half a
minute) but something goes wrong in the networking code for Windows
and the update can easily drag on for over five minutes. Sometimes the
upload also gets corrupted (also seems to mainly happen when using
Windows) and the controller refuses to upgrade.

Thus uploader was written. What it does is simply spoon feeding the
upload so slow that the controller never has to throttle the transfer
and thus the Windows bug is never triggered.

/Martin

[eof]
