- 1 Introduction
- 2 Getting Started
- 3 Hardware Components
- 4 Software Components
- 5 Example Usage
The TS-BAT3 board is a PC/104 daughter card which provides up to 1200mA of regulated 5V DC voltage to the PC/104 bus. Although designed to operate with the TS-7XXX series of products, it should work with any PC/104 main board, provided that the appropriate software is installed. It is powered by three NiMH cells with a rated capacity of 2000mAh.
2 Getting Started
As shipped from the factory, the TS-BAT3 board requires a few steps to become operational:
- With all power disconnected, plug the TS-BAT3 board into the main board.
- Download and install the latest drivers and application software.
- The software is divided into the following parts:
- TS-UART serial driver core (tsuart0.o) This is the same core driver currently shipping with all our products which have a TS-UART: TS-7260, TS-7300, TS-7400, etc...
- TS-BAT3 serial driver loader (tsuart-bat3.o) The TS-UART core is modular and implements all the serial driver functionality. The loader simply registers a particular serial port or ports with the core so they can be used, as well as implementing any auxiliary functionality, if needed.
- TS-BAT3 utility/charging daemon (bat3) This program provides the ability to directly view and change various parameters of the TS-BAT3. The "--help" option shows various options that are available. Many of the options available are useful only for debugging and experimentation purposes. This program also provides an option to run a default charging algorithm to try to keep the battery charged. In this mode the program runs as a daemon (background process).
- Source code (bat3src.tar.gz) A gzipped tar file is provided which contains the source code for the TS-BAT3 utility, as well as sample code for interfacing with this program to perform advanced network battery monitoring and charging functions.
- The above software can be obtained at the following URL - https://files.embeddedTS.com/pc104-peripherals/ts-bat3/
- To install the software it is necessary to perform the following steps:
- Copy the driver files and the bat3 program to the board that the TS-BAT3 will be attached to.
- Add the appropriate lines to your startup script to load the following modules: first "tsuart0.o", then "tsuart-bat3.o". It may not be necessary to load "tsuart0.o" if your startup script is already loading it.
- Add the following line to your startup script to start the charging daemon whenever the board is booted - bat3 --charge 400 &
- The software is divided into the following parts:
- Connect an appropriate power supply to the TS-BAT3 board.
- The TS-BAT3 can either be powered with a 7-28V DC power source via the square connector on the corner of the device, or with a regulated 5V DC power source via the pair of pins labeled "5V GND" which also indicates the correct polarity required.
- When using the TS-BAT3 board, do not attempt to apply power to any point on the main board; only utilize one of the two points on the TS-BAT3 mentioned in the previous paragraph.
- Remove the "BATTERY DISABLE" jumper (JP3).
- This jumper is provided as a means for disabling the battery backup and powering function. This is useful when battery power is not required or desired, such as when shipping the unit or for storage purposes.
- As long as JP3 is removed, the TS-BAT3 board will provide power when insufficient main power is available, so long as sufficient battery charge is left. When JP3 is present, the TS-BAT3 board will shut down and provide no power when main power is not present, regardless of battery state.
- Power up or reboot the main board.
- If everything is installed and running correctly, the LED on the TS-BAT3 board will start blinking immediately after bootup is complete.
3 Hardware Components
3.1 Description of Operation
The TS-BAT3 board has several logical components which provide the means to monitor and charge the battery and provide power to various sub-systems. The block diagram below shows how these components are connected. The charging control circuit is powered either by regulated input voltage or by the batteries themselves. It controls battery charging levels through pulse width modulation of regulated input voltage. It also has several analog to digital circuits which allow it to monitor battery voltage, charge/discharge current, and so forth. The charging control circuit provides an interface via the serial port on the TS-BAT3 board. Please see the software section for more information on this interface.
The charge control circuit also provides a low-power sleep mode. In this mode the TS-BAT3 will power down the main board, itself, and any other connected boards for a specified period of time. When the time has elapsed, power will be restored, rebooting the main board.
3.2 Block Diagram
There are five (5) jumper pins of interest on the TS-BAT3 board. These jumpers control the I/O address and IRQ settings, as well as battery function enabling. It may be necessary to alter these jumpers to avoid a conflict with other daughter cards connected to the main board.
|OFF||battery power enabled|
|ON||battery will not supply power|
|OFF||OFF||none (do not use this setting)|
|OFF||ON||6 (Linux interrupt 33)|
|ON||OFF||5 (Linux interrupt 32)|
|ON||ON||6, with IRQ sharing enabled|
There is also an auxiliary jumper position on the "ISP" header:
|ON||reset board from extended sleep mode|
The ISP5/6 is a reset function. Momentarily apply a jumper across pins 5 and 6 of the ISP header as shown in the diagram above. This provides a means for prematurely terminating the low-power sleep mode.
3.4 LED Function
The green LED on the TS-BAT3 board can be used to display status information. The "bat3" program uses this LED as follows: when power is on and the battery is actively being charged, the LED will flash. When power is on, but the battery is not currently being charged, the LED will remain on solid. When power is off (running on battery or not), the LED will be off.
4 Software Components
The battery charging procedures for the TS-BAT3 have been chosen conservatively to maintain battery life and avoid dangerous situations such as overheating. In exchange for this safety, the batteries charge at a relatively slow pace. You should expect initial charging to take an uninterrupted 24 hours, with recharging time falling to under 16 hours after the battery has been recharged a few times and has finished reforming.
With more aggressive charging, faster charge times are possible. However, proper implementation of such algorithms requires careful attention to operational battery parameters across a range of temperatures and battery conditions. Careless or improper charging may result in reduced battery life, overheating, battery damage, leaking, fire, or explosion.
The charging circuitry tries to provide some guards against dangerous conditions:
- Current limiting (via R1 and R2) Except under low battery conditions, charging current is limited to around 500mA. However, this current may not be maintainable across all battery conditions and temperatures. Therefore, to maintain a constant charging current, it is recommended that the maximum charge current be limited to 400mA.
- Automatic shutdown The charging control circuitry provides the ability to charge the battery with pulse-width modulation. However, this provides only (fairly) constant voltage and therefore requires interaction by the charging daemon to alter the PWM duty cycle to maintain constant current. The charge control circuitry will automatically shut off charging if it receives no commands from the charging daemon for approximately 120 seconds, to guard against over-charging in the event of a software crash.
- Environmental temperature sensor The temperature sensor on the TS-BAT3 board measures the ambient temperature of the board and provides this information to the charging daemon. DO NOT use this to detect temperature swings of the battery to make end of charge determination unless you can establish that it can reliably do so for your application. It is entirely possible that the coupling between the temperature sensor and the battery temperature may not be tight enough to make critical fast charging decisions.
4.2 Charging Strategy
The supplied bat3 charging daemon implements a simple, conservative duty-cycled constant current charging algorithm. The charging current and duty cycle can easily be altered for a given application. For instance, a solar driven unit might require the charging current to be lowered due to limitations of available power. Care must be taken in choosing alternate charging parameters to avoid overheating. As a general rule, limit average current over one period to C/10 unless you will be closely monitoring battery parameters.
By default, charging occurs in 2 minute periods with a 50% duty cycle, and at a charging current of 400mA. This results in an average C/10 charging current which can be maintained indefinitely with no safety issues. Battery life reduction is avoided, in contrast to a constant C/10 charge.
4.3 Interface to Charging Control Circuitry
The charge control circuitry is implemented with an AVR microcontroller. Communication with the AVR is accomplished via the TS-UART (serial port), which is accessible via /dev/ttyT3S0 when the appropriate drivers are loaded. This serial communication is framed using modified HDLC framing with a checksum byte for each frame (packet).
The AVR on the TS-BAT3 board sends frames containing state information approximately 30 times per second. The structure of this packet is documented in "bat3.h" (struct BAT3reply) in the source code package. When the user application on the main board (e.g. the bat3 daemon) wishes to change the state of the charge control circuitry, it sends a request frame (struct BAT3request) to the AVR. Subsequent frames will reflect this state change to acknowledge the change.
The source code package provides abstractions which reduce the amount of work an application must do to communicate with the AVR:
- bat3.c contains functionality specific to the TS-BAT3 board
- avr.c contains functionality specific to any TS board with an AVR
- serial.c contains functionality for sending and receive serial frames
- file.c contains generic file related functionality
- ByteArray.c contains functions for dealing with byte arrays.
4.4 "bat3" Options
The "bat3" program processes options in a slightly non-standard way. First, unknown options are silently ignored. Options which are missing their required parameters get default parameters, which normally means zero (0), which is probably not what you want. For the remainder of the options it is necessary to know how the bat3 program operates.
The bat3 program was designed as a utility to fetch and change the state of the TS-BAT3. When run with no parameters, it merely waits to receive a state frame from the AVR, then prints out the current state in a human readable text format. When options are supplied that modify the AVR state, these options are processed, and when option processing is finished, a packet is constructed and sent to the AVR. If the AVR does not acknowledge the state change, the packet will be resent up to a retry limit. The options which change the AVR state are:
--buck (currently un-implemented)
--The "--help" option describes these options and their parameters in more detail.
To run the charging daemon the "--charge" option must be specified. This causes the program to detach from the controlling terminal immediately; therefore, any options after it will be ignored, as well as any options before it which do not directly pertain to the charging algorithm (e.g. any of the options in the previous paragraph). Any additional options to specify charging parameters (besides current, which is a parameter to --charge itself) must come before the "--charge" option. These additional options (without their required parameters) are:
In general it is not even necessary to specify anything but the charge option with its required parameter, as all charging parameters can be changed on the fly as documented in the next section.
4.5 Advanced Monitoring and Charging
The bat3 program listens on UDP port 4000 for commands. The structure of these commands are documented in bat3.h (struct BAT3UDPcommand). These commands are:
4.5.1 Command 1
This tells bat3 to start sending detailed battery information at 1Hz. These packets are sent to the UDP port of the host that sends the request. That is, the bat3 program looks at the source IP address of the request packet and sends to that address, at the port number specified in the request. Only one host at a time (the last one to send this request) will receive these info packets.
The structure of the packets sent by the bat3 is documented in bat3.h (struct bat3Info). Note that the voltages and currents in this packet should only be considered approximate unless you perform strict calibration on an individual board basis.
4.5.2 Command 2
This tells bat3 to stop sending information packets.
4.5.3 Command 3
This tells bat3 to start charging the battery continuously at the specified current level in milliAmps. Your program must monitor battery information (initiated by sending command 1) to determine when to stop charging.
4.5.4 Command 4
This tells bat3 to start charging the battery at the specified current level in milliAmps. Charging is enabled for time_on seconds and then is shut off for time_off seconds and then the cycle is repeated indefinitely. You must determine whether or not it is necessary to monitor battery information to determine when charging is complete.
5 Example Usage
The following describes a scenario in which the TS-BAT3 is used to gracefully shutdown the TS-7800 that it is paired with.
01.) Download the bat3src.tar.gz tarball and compile the source using the "make" command on the TS-7800. * make 02.) Copy the new bat3 binary to /usr/local/bin, where it can be easily included in your PATH. * cp bat3 /usr/local/bin/ 03.) Create a init.d script that will be called on system startup with the following contents. * vi /etc/init.d/init_bat3 #!/bin/sh PATH=$PATH:/usr/local/bin echo -n "Initializing TS-BAT3..." ( # insert the bat3 module modprobe tsuart_bat3 # the bat3 utility expects to see BAT3 @ ttyT3S0 ln -sf /dev/ttts10 /dev/ttyT3S0 # Charge @ 400mA on for 60 secs, then off for 60 secs # Run 'shutdown -h now' in 1 second after power loss # nohup protects bat3 from being killed on init hangup # sleep 1 protects nohup from being killed prematurely nohup bat3 --on 60 --off 60 --shutdown 1 --charge 400 & sleep 1 ) > /dev/null echo "done" 04.) Give executable rights to the script created above * chmod +x /etc/init.d/init_bat3 05.) Create a symbolic link from the /etc/init.d/init_bat3 script to the /etc/rc3.d/ directory for inclusion inclusion in the Linux startup process. * ln -sf /etc/init.d/init_bat3 /etc/rc3.d/S99init_bat3 06.) Edit the "halt" script to include a sleep command to cut power for defined time just before the system halts. The following lines are in standard 'diff -u' format. * vi /etc/rc0.d/S90halt - PATH=/sbin:/bin:/usr/sbin:/usr/bin + PATH=/sbin:/bin:/usr/sbin:/usr/bin:/usr/local/bin + bat3 --sleep 50 halt -d -f -i $poweroff $hddown 07.) Be sure to sync the changes and then restart the board. * sync; shutdown -r now 08.) When the system starts, you will see "Initializing TS-BAT3...done" in the startup process and the LED on the TS-BAT3 will start to blink indicating that it is charging. At this point, you can simulate a power outage by pulling the power cord. Within a second, you will see the board start it shutdown sequence. When it hits the "bat3 --sleep 30" line of the halt script, the BAT3 will go into a low power sleep mode for 30 seconds. When 30 seconds have passed, power will be restored and the board will begin its boot sequence. See notes below.
If you chose to use the bat3 utility and a power failure occurs followed by a power restore, the sleep function cannot be interrupted unless you physically jump ISP3, so then you'll need to wait for the sleep to end. If the power is not restored by the time the sleep has ended and the system boots up, then the batteries will start depleting. If you expect that the power would be restored in a specified time, e.g. one hour, then you could simply make the bat3 sleep for an hour so that when it comes up again, the power will have been restored. The downside is your system will always have a minimum downtime of an hour whenever power is cut.
The other alternative when using the TS-7800 is to use the 'ts7800ctl -s' command which has the ability to cut off power to the TS-7800 for 524288 seconds (145.63 hours or 6 days) until power is restored. When power is restored, the TS-7800 will start up again regardless of the sleep state.
In order to utilize the 'ts7800 -s' sleep command as described above, you must make a hardware modification due to the TS-7800 AVR implementation.
The +5V pins on the PC/104 bus of the TS-BAT3 are B3 and B29. Row B is the row closest to the batteries and pin one is nearest to the jumpers. These pins will need to be cut and then connected from the top of the PC/104 connector to the +5V header (near COM1) of the TS-7800.
This hardware modification is not necessary on other boards.