| \chapter{Advanced Topics} |
| |
| \section{\label{ref:CustomisingUI}Customising the userinterface} |
| \subsection{\label{ref:GettingExtras}Getting Extras} |
| \opt{HAVE_LCD_BITMAP}{ |
| Rockbox supports custom fonts. A collection of fonts is available for download |
| in the font package at \url{http://www.rockbox.org/daily.shtml}}. Support for a |
| number of languages is included with Rockbox, and the latest \fname{.lng} files |
| are always included in the different Rockbox builds. |
| |
| \opt{HAVE_LCD_BITMAP}{ |
| \subsection{\label{ref:Loadingfonts}Loading Fonts} |
| Rockbox can load fonts dynamically. Simply copy the \fname{.fnt} file to the |
| \dap\ and ``play'' them in the directory browser or select |
| \setting{General Settings $\rightarrow$ Fonts} from the Main Menu. |
| If you want a font to be loaded automatically every time you start up, |
| it must be located in the \fname{/.rockbox } folder and the filename |
| must be at most 24 characters long. |
| \warn{Advanced Users Only: Any BDF font file up to 16 pixels high should |
| be usable with Rockbox. To convert from \fname{.bdf} to \fname{.fnt}, use |
| the \fname{convbdf} tool. This tool can be found in the \fname{tools} |
| directory of the Rockbox source code.} |
| } |
| |
| \subsection{\label{ref:Loadinglanguages}Loading Languages} |
| Rockbox can load language files at runtime. Simply copy the \fname{.lng} file |
| \emph{(do not use the .lang file)} to the \dap\ and ``play'' it in the |
| Rockbox directory browser or select \setting{General Settings $\rightarrow$ |
| Languages }from the Main Menu. |
| |
| \note{If you want a language to be loaded automatically every time you start |
| up, it must be located in the \fname{/.rockbox }folder and the filename must |
| be a maximum of 24 characters long.} |
| |
| If your language is not yet supported and you want to write your own language |
| file find the instructions on the Rockbox website: |
| \wikilink{HowtoUpdateLangfile} |
| |
| \section{\label{ref:ConfiguringtheWPS}Configuring the WPS} |
| |
| \subsection{WPS -- General Info} |
| |
| \begin{description} |
| \item[Description: ] The WPS or While Playing Screen is the name used to |
| describe the information displayed on the \daps\ screen whilst an audio track |
| is being played. The default WPS is a relatively simple screen displaying |
| Track name, Artist, Album etc. in the default font as a purely text based |
| layout. There are a number of WPS files included in Rockbox, and you can |
| load one of these at anytime by selecting it in |
| \setting{General Settings $\rightarrow$ Display $\rightarrow$ Browse .wps files}. |
| \opt{HAVE_REMOTE_LCD}{There is a related option to browse \fname{.rwps} |
| files for \daps{} with LCD remote controls installed. This will load a |
| similar WPS screen for the remote but with usually a simpler and more |
| concise layout.} |
| |
| \note{``Playing'' a \fname{.wps} from the file browser has the same effect.} |
| |
| \item [File Location: ]Custom WPS files may be located anywhere on the drive. |
| The only restriction is that they must end in \fname{.wps}. When you ``play'' |
| a \fname{.wps} file, it will be used for future WPS screens, and if the |
| ``played'' \fname{.wps} file is located in the \fname{/.rockbox} folder, it |
| will be remembered and used after reboot. The \fname{.wps} filename must be |
| no more than 24 characters long for it to be remembered. |
| \end{description} |
| |
| \subsection{\label{ref:CreateYourOwnWPS}WPS -- Build Your Own} |
| Quite simply, enter the WPS code in your favourite text editor, Notepad on |
| Windows works fine. When you save it, instead of saving it as a \fname{.txt} |
| file, save it as a \fname{.wps} file. Example: Instead of \fname{Rockbox.txt}, |
| save the file as \fname{Rockbox.wps}. To make sure non english characters |
| display correctly in your WPS you must save the .wps file with UTF-8 character |
| encoding. This can be done in most editors, for example Notepad in Windows 2000 |
| or XP (but not in 9x/ME) can do this. See appendix \reference{ref:wps_tags} for |
| all the tags that are available. |
| |
| \begin{itemize} |
| \item All characters not preceded by \% are displayed as typed. |
| \item Lines beginning with \# are comments and will be ignored. |
| \item Maximum file size used is |
| \opt{HAVE_LCD_BITMAP}{1600} |
| \opt{player}{400} bytes. |
| If you have a bigger WPS file, only the first part of it will be |
| loaded and used. |
| \end{itemize} |
| |
| \note{Keep in mind that your \dap{} resolution is \genericimg{} (with |
| the last number giving the colour depth in bits) when |
| designing your own WPS, or if you use a WPS designed for another target. |
| \opt{HAVE_REMOTE_LCD}{The resolution of the remote is |
| \opt{h1xx,h300}{128x64x1}\opt{x5}{128x96x2} pixels.}} |
| |
| \subsubsection{Conditional Tags} |
| |
| \begin{description} |
| \item[If/else: ] |
| Syntax: \config{\%?xx{\textless}true{\textbar}false{\textgreater}} |
| |
| If the tag specified by ``\config{xx}'' has a value, the text between the |
| ``\config{{\textless}}'' and the ``\config{{\textbar}}'' is displayed (the true |
| part), else the text between the ``\config{{\textbar}}'' and the |
| ``\config{{\textgreater}}'' is displayed (the false part). |
| The else part is optional, so the ``\config{{\textbar}}'' does not have to be |
| specified if no else part is desired. The conditionals nest, so the text in the |
| if and else part can contain all \config{\%} commands, including conditionals. |
| |
| \item[Enumerations: ] |
| Syntax: \config{\%?xx{\textless}alt1{\textbar}alt2{\textbar}alt3{\textbar}\dots{\textbar}else{\textgreater}} |
| |
| For tags with multiple values, like Play status, the conditional can hold a |
| list of alternatives, one for each value the tag can have. |
| Example enumeration: |
| \begin{example} |
| \%?mp{\textless}Stop{\textbar}Play{\textbar}Pause{\textbar}Ffwd{\textbar}Rew{\textgreater} |
| \end{example} |
| |
| The last else part is optional, and will be displayed if the tag has no value. |
| The WPS parser will always display the last part if the tag has no value, or if |
| the list of alternatives is too short. |
| \end{description} |
| |
| \subsubsection{Next Song info} |
| You can display information about the next song -- the song that is |
| about to play after the one currently playing (unless you change the |
| plan). |
| |
| If you use the upper-case versions of the |
| three tags: \config{F}, \config{I} and \config{D}, they will instead refer to |
| the next song instead of the current one. Example: \config{\%Ig} is the genre |
| name used in the next song and \config{\%Ff} is the mp3 frequency. |
| |
| \note{The next song information \emph{will not} be available at all |
| times, but will most likely be available at the end of a song. We |
| suggest you use the conditional display tag a lot when displaying |
| information about the next song!} |
| |
| \subsubsection{Alternating sublines} |
| |
| It is possible to group items on each line into 2 or more groups or |
| ``sublines''. Each subline will be displayed in succession on the line for a |
| specified time, alternating continuously through each defined subline. |
| |
| Items on a line are broken into sublines with the semicolon |
| '\config{;}' character. The display time for |
| each subline defaults to 2 seconds unless modified by using the |
| '\config{\%t}' tag to specify an alternate |
| time (in seconds and optional tenths of a second) for the subline to be |
| displayed. |
| |
| Subline related special characters and tags: |
| \begin{description} |
| \item[;] Split items on a line into separate sublines |
| \item[\%t] Set the subline display time. The |
| '\config{\%t}' is followed by either integer |
| seconds (\config{\%t5}), or seconds and tenths of a second (\config{\%t3.5}). |
| \end{description} |
| |
| Each alternating subline can still be optionally scrolled while it is |
| being displayed, and scrollable formats can be displayed on the same |
| line with non{}-scrollable formats (such as track elapsed time) as long |
| as they are separated into different sublines. |
| Example subline definition: |
| \begin{example} |
| %s%t4%ia;%s%it;%t3%pc %pr : Display id3 artist for 4 seconds, |
| Display id3 title for 2 seconds, |
| Display current and remaining track time |
| for 3 seconds, |
| repeat... |
| \end{example} |
| |
| Conditionals can be used with sublines to display a different set and/or number |
| of sublines on the line depending on the evaluation of the conditional. |
| Example subline with conditionals: |
| \begin{example} |
| %?it{\textless}%t8%s%it{\textbar}%s%fn{\textgreater};%?ia{\textless}%t3%s%ia{\textbar}%t0{\textgreater}\\ |
| \end{example} |
| |
| The format above will do two different things depending if ID3 tags are |
| present. If the ID3 artist and title are present: |
| \begin{itemize} |
| \item Display id3 title for 8 seconds, |
| \item Display id3 artist for 3 seconds, |
| \item repeat\dots |
| \end{itemize} |
| If the ID3 artist and title are not present: |
| \begin{itemize} |
| \item Display the filename continuously. |
| \end{itemize} |
| Note that by using a subline display time of 0 in one branch of a conditional, |
| a subline can be skipped (not displayed) when that condition is met. |
| |
| \subsubsection{Using Images} |
| You can have as many as 52 images in your WPS. There are various ways of |
| displaying images: |
| \begin{enumerate} |
| \item Load and always show the image, using the \config{\%x} tag |
| \item Preload the image with \config{\%xl} and show it with \config{\%xd}. |
| This way you can have your images displayed conditionally. |
| \opt{HAVE_LCD_COLOR}{ |
| \item Load an image and show as backdrop using the \config{\%X} tag. The |
| image must be of the same exact dimensions as your display. |
| } |
| \end{enumerate} |
| |
| \optv{HAVE_LCD_COLOR}{ |
| Example on background image use: |
| \begin{example} |
| %X|background.bmp| |
| \end{example} |
| The image with filename \fname{background.bmp} is loaded and used in the WPS. |
| } |
| |
| Example on bitmap preloading and use: |
| \begin{example} |
| %x|a|static_icon.bmp|50|50| |
| %xl|b|rep\_off.bmp|16|64| |
| %xl|c|rep\_all.bmp|16|64| |
| %xl|d|rep\_one.bmp|16|64| |
| %xl|e|rep\_shuffle.bmp|16|64| |
| %?mm<%xdb|%xdc|%xdd|%xde> |
| \end{example} |
| Four images at the same x and y position are preloaded in the example. Which |
| image to display is determined by the \config{\%mm} tag (the repeat mode). |
| |
| \subsubsection{Example File} |
| \begin{example} |
| %s%?in<%in - >%?it<%it|%fn> %?ia<[%ia%?id<, %id>]> |
| %pb%pc/%pt |
| \end{example} |
| That is, ``tracknum -- title [artist, album]'', where most fields are only |
| displayed if available. Could also be rendered as ``filename'' or ``tracknum -- |
| title [artist]''. |
| |
| %\opt{HAVE_LCD_BITMAP}{ |
| % \begin{verbatim} |
| % %s%?it<%?in<%in. |>%it|%fn> |
| % %s%?ia<%ia|%?d2<%d2|(root)>> |
| % %s%?id<%id|%?d1<%d1|(root)>> %?iy<(%iy)|> |
| % |
| % %al%pc/%pt%ar[%pp:%pe] |
| % %fbkBit %?fv<avg|> %?iv<(id3v%iv)|(no id3)> |
| % %pb |
| % %pm |
| % % \end{verbatim} |
| %} |
| |
| \section{\label{ref:manage_settings}Managing Rockbox settings} |
| |
| \subsection{Introduction to \fname{.cfg} files.} |
| Rockbox allows users to store and load multiple settings through the use of |
| configuration files. A configuration file is simply a text file with the |
| extension \fname{.cfg}. |
| |
| A configuration file may reside anywhere on the hard disk. Multiple |
| configuration files are permitted. So, for example, you could have |
| a \fname{car.cfg} file for the settings that you use while playing your |
| jukebox in your car, and a \fname{headphones.cfg} file to store the |
| settings that you use while listening to your \dap\ through headphones. |
| |
| See \reference{ref:cfg_specs} below for an explanation of the format |
| for configuration files. See \reference{ref:manage_settings_menu} for an |
| explanation of how to create, edit and load configuration files. |
| |
| \subsection{\label{ref:cfg_specs}Specifications for \fname{.cfg} |
| files.} |
| |
| The Rockbox configuration file is a plain text file, so once you use the |
| \setting{Write .cfg file} option to create the file, you can edit the file on |
| your computer using any text editor program. See |
| Appendix \reference{ref:config_file_options} for available settings. Configuration |
| files use the following formatting rules: % |
| |
| \begin{enumerate} |
| \item Each setting must be on a separate line. |
| \item Each line has the format ``setting: value''. |
| \item Values must be within the ranges specified in this manual for each |
| setting. |
| \item Lines starting with \# are ignored. This lets you write comments into |
| your configuration files. |
| \end{enumerate} |
| |
| Example of a configuration file: |
| \begin{example} |
| # Example configuration file |
| # volume: 70 |
| # bass: 11 |
| # treble: 12 |
| # balance: 0 |
| # time format: 12hour |
| # volume display: numeric |
| # show files: supported |
| # wps: /.rockbox/car.wps |
| # lang: /.rockbox/afrikaans.lng |
| \end{example} |
| |
| \note{As you can see from the example, configuration files do not need to |
| contain all of the Rockbox options. You can create configuration files |
| that change only certain settings. So, for example, supppose you |
| typically use the \dap{} at one volume in the car, and another when using |
| headphones. Further, suppose you like to use an inverse LCD when you are |
| in the car, and a regular LCD setting when you are using headphones. You |
| could create configuration files that control only the volume and LCD |
| settings. Create a few different files with different settings, give |
| each file a different name (such as \fname{car.cfg}, |
| \fname{headphones.cfg}, etc.), and you can then use the \setting{Browse .cfg |
| files} option to quickly change settings.} |
| |
| \subsection{\label{ref:manage_settings_menu}The \setting{Manage Settings} |
| menu} The \setting{Manage Settings} menu can be found in the \setting{Main |
| Menu}. The \setting{Manage Settings} menu allows you to save and load |
| \fname{.cfg} files. \opt{MASCODEC}{The \setting{Manage Settings} menu also |
| allows you to load or save different firmware versions.} |
| |
| \begin{description} |
| |
| \item [Browse .cfg Files.]Opens the file browser in the \fname{/.rockbox} |
| directory and displays all \fname{.cfg} (configuration) files. Selecting a |
| \fname{.cfg} file will cause Rockbox to load the settings contained in that |
| file. Pressing \ButtonLeft\ will exit back to the \setting{Manage Settings} |
| menu. See the \setting{Write .cfg files} option on the |
| \setting{Manage Settings} menu for details of how to save and edit a |
| configuration file. |
| |
| \item [Browse Firmwares.] |
| % |
| \opt{SWCODEC}{\fixme{This is a legacy item, and is deprecated.}} |
| % |
| \opt{MASCODEC}{ |
| This displays a list of firmware files in the \fname{/.rockbox} |
| system directory. |
| % |
| \opt{recorder,recorderv2fm,ondio}{Firmware files have an extension of |
| \fname{.ajz}. } |
| % |
| \opt{player}{Firmware files have an extension of \fname{.mod}. } |
| % |
| Playing a firmware file loads it into memory. Thus, it is possible |
| to run the original Archos firmware or a different version of Rockbox |
| from here (assuming that you have the right files installed on your |
| disk. There is no need for any other file or directory to be |
| installed to use this option; the firmware is resident in that one |
| file. |
| } |
| |
| \item [Reset Settings.]This wipes the saved settings in the \dap\ and |
| resets all settings to their default values. |
| |
| \opt{h100,h300}{\note{You can also reset all settings to their default |
| values by turning off the \dap, turning it back on, and pressing the |
| \ButtonRec button immediately after the \dap\ turns on.} |
| } |
| \opt{ipod}{\note{You can also reset all settings to their default values |
| by turning off the \dap, and turning it back on with the hold button |
| on.} |
| } |
| |
| \item [Write .cfg file.]This option writes a \fname{.cfg} file to |
| your \daps\ hard disk. The configuration file has the \fname{.cfg} |
| extension and is used to store all of the user settings that are described |
| throughout this manual. |
| |
| Hint: Use the \setting{Write .cfg file} feature (\setting{Main Menu |
| $\rightarrow$ General Settings}) to save the current settings, then |
| use a text editor to customize the settings file. See Appendix |
| \reference{ref:config_file_options} for the full reference of available |
| options. |
| |
| \end{description} |
| |
| \section{\label{ref:FirmwareLoading}Firmware Loading} |
| \opt{player,recorder,recorderv2fm,ondio}{ |
| When your \dap{} powers on, it loads the Archos firmware in ROM, which |
| automatically checks your \daps{} root folder for a file named |
| \firmwarefilename. Note that Archos firmware can only read the first |
| ten characters of each filename in this process, so don't rename your old |
| firmware files with names like \firmwarefilename.\fname{old} and so on, |
| because it's possible that the \dap{} will load a file other than the one |
| you intended. |
| } |
| |
| \subsection{\label{ref:using_rolo}Using ROLO (Rockbox loader)} |
| Rockbox is able to load and start another firmware file without rebooting. |
| You just ``play'' a file with the extension % |
| \opt{recorder,recorderv2fm,ondio}{\fname{.ajz}.} % |
| \opt{player}{\fname{.mod}.} % |
| \opt{iriver}{\fname{.iriver}.} % |
| \opt{ipod}{\fname{.ipod}.} % |
| \opt{iaudio}{\fname{.iaudio}.} % |
| This can be used to test new firmware versions without deleting your |
| current version. |
| |
| \opt{archos}{\input{advanced_topics/archos-flashing.tex}} |