Update Battery Benchmark plugin in the manual to correct some out-of-date

information, and rewrite some sections to improve the English.


git-svn-id: svn://svn.rockbox.org/rockbox/trunk@20352 a1c6a512-1295-4272-9138-f99709370657

1 files changed, 45 insertions, 52 deletions

diff --git a/manual/plugins/batterybenchmark.tex b/manual/plugins/batterybenchmark.tex
index ab7774c..fb7c64d 100644
--- a/manual/plugins/batterybenchmark.tex
+++ b/manual/plugins/batterybenchmark.tex
@@ -1,20 +1,19 @@
 \subsection{Battery Benchmark}
-The Battery Benchmark Plugin enables you to test your battery's performance,
-while making normal use of your \dap. Once loaded it will run in the
-background (TSR plugin), reading various info about your battery while you use
-it. Once you finish your session you can find the benchmark output data in a
-file on your \dap\ \fname{/battery\_bench.txt}.
-Please submit your results to the Rockbox wiki.
-\wikilink{BatteryRuntime}
+The \setting{Battery Benchmark} plugin enables you to test your battery's
+performance whilst using your \dap\ normally. Results can be submitted 
+to the \wikilink{BatteryRuntime} wiki page.
 
 \subsubsection{How it works}
-After you load the plug-in the operation of your \dap\ continues as normal.
-You can do whatever you could do before loading the plugin except loading
-another plugin. If you happen to load a plugin while benchmarking, a splash
-screen will inform you about the termination of the benchmark.
-While you operate it will log various battery related information every time
-the disk is activated by external causes, (buffer refill, open directory,
-USB mode) or an hour passes without updating the log file.\\
+Once loaded, \setting{Battery Benchmark} runs in the
+background recording various information about your battery to memory.
+A new point is written to memory every minute.
+Every time the disk is accessed for any reason
+(such as refilling the audio buffer, opening a directory or entering
+USB mode etc.) then the information in memory is written to disk.
+Once the memory becomes full (after many hours), then the data
+are written to disk anyway. This is done so that the data are not biased by
+excessive additional disk accesses. The file is written to the root
+directory of your \dap\ and is called \fname{battery\_bench.txt}.
 The plugin will continue to log info until:
 
 \begin{itemize}
@@ -22,49 +21,43 @@ The plugin will continue to log info until:
 \item The \dap\ is shut down.
 \item The battery is empty.
 \end{itemize}
-Between disk activity (or an hour), it will log info in memory (every
-measurement is captured when the voltage changes). If there are too many
-measurements older entries will be deleted and the log file will inform the
-user about the interval where entries were lost. Benchmarks can be resumed if
-you accidentally load a plugin, or turn off your \dap, as long as the log
-file \fname{/battery\_bench.txt} is not deleted. 
+
+Benchmarks can be resumed if
+you accidentally load a plugin, or turn off your \dap, so long as the log
+file \fname{battery\_bench.txt} is not deleted. 
 
 \subsubsection{Information explained}
-On the top of the file you will see various info on how to use the plugin.
+At the top of the \fname{battery\_bench.txt} file is various
+information on how to use the plugin, followed by the data themselves.
+
 \begin{description}
 \item[Time] This column reports the total time of operation of the \dap. It is 
-not the time that you started the plug-in. If you have your player on for 5 
+not the time that you started the plug-in. If you have your \dap\ on for 5 
 minutes and then start the plugin, it will start measuring from 5 minutes.
-\item[Seconds] As time, it shows time passed in seconds. Nothing special, it is
-there because it is free and maybe someone might want to make graphs with
-seconds.
-\item[Level] The percent level of the battery estimated by Rockbox. This is an
-estimation and not an accurate result. Using the real percentage (current
-battery voltage / top battery voltage) * 100) we can calculate the difference
-between the estimation. Goal of this column is to make the estimation algorithm
-of Rockbox more accurate.
-\item[Time Left] It shows the estimated (by Rockbox) remaining time until
-shutdown. Again, as with Level(above), this column can be used to see 
-differences between real time left and estimated time left. This could help 
-make time left more accurate.
-\item[Voltage] The battery voltage, the moment the measurement was captured. 
-Measurements are captured when this number changes while benchmarking.
-This column can be used to give quite interesting graphs in a spreadsheet
-program. (Excel, Calc, e.t.c)
-\item[M/DA] (Measurements per Disk Activity) The number of measurements stored
-temporarily in memory, before written on the log file. This can give you an
-idea of how many voltage changes there are between disk activity (or one hour).
-\item[C] Stands for Charger. An "A" in that column shows if there was the power
-adapter attached to the unit, at the time of the measurement.
-\item[S] The "S" column shows the state of the device (Charging, or not). The
-"C" indicated that the unit was charging when the measurement was captured.
+\item[Seconds] The same as \config{Time}, except measured in seconds.
+\item[Level] The percent level of the battery estimated by Rockbox, and not the
+actual battery level. The actual battery level can be seen from the
+\config{Voltage} column
+\item[Time Left] This shows the time remaining until the battery is empty,
+again as estimated by Rockbox.
+\item[Voltage] The battery voltage in mV at the moment the measurement
+was taken.
+\item[C] This stands for Charger. An "A" in that column shows if the power
+adapter was attached to the unit at the time of the measurement.
 \item[U] USB powered. Only for targets that support this. A "U" will indicate
-if the unit was using the USB port for powering. 
+if the unit was using the USB port for power at the time of the measurement. 
 \end{description}
 
-\subsubsection{Making graphs}
-While you can tell how long your battery lasted, with a single look at the last
-line of the battery log (\fname{/battery\_bench.txt}), the most useful purpose of
-Battery Benchmark is to make graphs using a spreadsheet program like Excel or
-Calc. The battery log (\fname{/battery\_bench.txt}) is in CSV format (comma separated)
-so you can quite easily import it to a spreadsheet program.
+\subsubsection{Usage}
+The log file can be used to tell you how long the battery lasted (with some
+limitations, see below), but it is most useful for graphing discharge curves
+in order to improve Rockbox's estimation of battery level and time remaining.
+The battery log (\fname{battery\_bench.txt}) is in CSV format
+(comma separated variables) and thus can be easily imported into a spreadsheet
+or similar program.
+
+\subsubsection{Limitations}
+As \setting{Battery Benchmark} needs to write the data held in memory to
+disk in order to save them, it is possible that should Rockbox shut down
+due to low battery then there will not be enough power remaining to write the
+data to disk. Therefore all measurements since the previous save will be lost.