 Notice. New forum software under development. It's going to miss a few functions and look a bit ugly for a while, but I'm working on it full time now as the old forum was too unstable. Couple days, all good. If you notice any issues, please contact me. |
Forum Index : Microcontroller and PC projects : Armmite F4 - SD Card File Utilities Library
| Author | Message | ||||
| erbp Senior Member  Joined: 03/05/2016 Location: AustraliaPosts: 186 |
The following may be of interest to some. I have created a library of functions that can be used to manage and manipulate files on an SD Card on an Armmite F4 system. My use scenario is: an Armmite F4 with ILI9341 3.2" LCD (320x240) with a PS/2 keyboard attached. I want to be able to use it un-tethered from a PC as much as possible and to that end have enabled the LCD Panel as Console, using Font 1. While the panel is small, Font 1 allows 18 lines x 40 characters per line, so working from the Command Prompt without an external Console attached is possible even if a bit less than ideal. I have found that doing stuff with files on the SD Card is very limited in this environment where the firmware provides only limited built-in support. To enhance the things you can do with files without needing to take the SD Card to a PC, I have created the 'FileUtils' library containing 8 functions as stand-alone sub-routines. The "program" file needs only to be LOADed to the F4 but not RUN. The functions will then be available directly from the Command Prompt along with all the standard MMBasic Commands and Functions. Output from these functions is sent to the console and input, being entered at the Command Prompt, is from the console input device. The console output can be directed to the LCD Panel (using the OPTION LCDPANEL CONSOLE 1 command), or can use an external console (Teraterm, Putty, etc.) if connected to a PC. Since console output to the ILI9341 panel is limited to 18*40 lines*characters and my specific use is in this environment, output is generally formatted for this size console window. If you are using an external console and do not have the LCD Panel configured as a console, the console window size will default to 24*80 (and can be changed by the user) HOWEVER the output from the FileUtils functions will continue to use 18*40 format since the console window size setting is NOT programatically visible so the code cannot know what size the console window is. Note that input to these functions is actually arguments to sub-routines. You can enclosed the argument list in brackets (...) or not depending on your preference. String arguments must be enclosed in double quotes as per normal. The following shows the general Help information available via the FileUtilsHelp() function. These list the remaining 7 functions (apart from Help) that the library provides.   As indicated 4 functions are for use with record based files - i.e. files structured into records with CR/LF (or variant) acting as record terminators. These files are frequently referred to as Text Files. MMBasic source files are an example of this type of file. The 4 functions supported are:- FileCopy - allows a record based file to be copied to a different directory on the SD Card as the same or different name, or to the same directory as a different name. See FileUtilsHelp("FileCopy") for syntax and a brief explanation of this function. Following is an example of using the FileCopy function.  FileExtract - similiar to FileCopy except that it can extract part of the source file, from a specified starting record number to a specified ending record number. Identification of the record numbers matching the portion of the file that you want to extract can be done via the FileList function (see below). See FileUtilsHelp("FileExtract") for syntax and a brief explanation of this function. Following is an example of using the FileExtract function to extract a copy of the code for a particular sub-routine from a MMBasic program file.  FileList - lists the content of a specified record based file. The listing output will only show printable characters. CR/LF are recognized as record (line) terminators but are not shown in the listing. If the file contains other non-printable characters they will be shown as a blank character. See FileUtilsHelp("FileList") for syntax and a brief explanation of this function. Following is an example of using the FileList function to list a MMBasic program file.    Below is the output from FileList showing the content of the file that was created by FileExtract in the example above.   FileMerge - allows the contents of one file (the Insert file) to be inserted into another file (the Merge file) at a specified location within the Merge file. The Insert location is specified as a record number in the Merge file. See FileUtilsHelp("FileMerge") for syntax and a brief explanation of this function. Following is an example of using the FileMerge function.  Record Based function limitations: - Only support a maximum record size of 255 characters. - FileList only shows the printable characters (ASCII values 32 thru 126) in each record, non-printable are shown as spaces. - There is no hard filesize limit for these functions, however FileList will be very cumbersome to use with larger files. - These functions are designed only for use with the Armmite F4 running f/w v5.07.00. They are un-tested on and NOT expected to work on the other mite platforms. The remaining 3 functions are for use with stream (non-record based) files - i.e. files that are a stream of bytes and do not use any record structure. These files are sometimes referred to as Binary files or Non-Text files and typically contain some/many byte values which are not printable characters. Bitmap images are an example of this type of file. However record based files can also be treated as stream files, so these functions CAN be used with record based files, including files containing records longer than 255 characters. I am using the 'Bin' (binary) abbreviation to identify these functions. The 3 functions supported are:- FileBinCopy - provides equivalent functionality to the FileCopy function, except that it can handle both stream files AND record based files. Using FileBinCopy will allow a record based file with record size greater than 255 characters to be successfully copied. See FileUtilsHelp("FileBinCopy") for syntax and a brief explanation of this function. Following is an example of using the FileBinCopy function.  FileBinList - lists the content of a specified file (stream or record based). The listing output is formatted as two lines displaying 10 bytes of file content. The first line displays the printable character for any bytes with values between 32 and 126, other values will display as a blank on this line. The second line displays the Hexadecimal value for each byte regardless of whether it is a printable character or not. Unfortunately this only allows 80 bytes of file data to be displayed per console "screen", so is very limited when listing larger files. See FileUtilsHelp("FileBinList") for syntax and a brief explanation of this function. Following is an example of using the FileBinList function.   FileBinXfer - allows a file (stream or record based) to be copied from one SD Card to a different SD Card. This is achieved via a 2 step process. Firstly, the content of the file is copied into a data array resident in RAM. The function then displays instructions to the user to swap the SD Card to the one that the file is to be copied onto. Once this has been done and confirmed by entering OK, the required directory structure will be built on the second SD Card (if it doesn't already exist), and then the file data copied from the array in RAM to the second SD Card. Due to size constraints on the amount of RAM available for the array, this function is limited to a maximum filesize of 100200 bytes (approx 100KB). See FileUtilsHelp("FileBinXfer") for syntax and a brief explanation of this function. Following is an example of using the FileBinXfer function.   FileBinxxxx function limitations: - There is no hard filesize limit for the FileBinCopy and FileBinList functions, however FileBinList will be very cumbersome to use with larger files. - There is no record size limit for record based files when used with the FileBinxxxx functions. - FileBinXfer only supports filesizes up to 100200 bytes for either stream or record based files. - These functions are designed only for use with the Armmite F4 running f/w v5.07.00. They are un-tested on and NOT expected to work on the other mite platforms. SD Card Directories All the above functions support specification of the path to the required file. With one exception (see below) the path specification may be either absolute - i.e. starts at the root directory (A:/) or relative. Relative paths take into account the Current Working Directory (CWD). So if I had used the CHDIR command to change the working directory to "A:/Phil/Test" and the file I wish to access is located in or will be copied to this directory, then I only need to specify the file name - e.g. "MyTestFile.txt" which would refer to the file "A:/Phil/Test/MyTestFile.txt". This applies to both source files (files that will be used for input) and destination files (files that will be used for output). For files that are used for input, the functions expects the specified path and file to already exist and will report an error if it cannot be found. For destination files, neither the path specified nor the file needs to exist as the functions that create output files will verify, and build if necessary, the requested directory structure before attempting to create the file. If the a file with the same path and name as a destination file already exists, it will be replaced by the file created by the function. The one exception to using a relative path for a file is the destination file for the FileBinXfer function. In this case the Current Working Directory, even if active before the function is initiated, will be reset to the root directory when the SD Card is swapped. So the destination file for FileBinXfer MUST be specified with an absolute path (starting with A:/). The source file may specify either an absolute or relatve path. FileUtils.zip To use, unzip FileUtils.bas to the desired directory, then use the LOAD "<path>/FileUtils.bas" command, where <path> is the path to the directory the program file was placed in. Do not RUN this file, although doing so will not cause any damage or break anything. I hope these utility functions will be of assistance to some Armmite F4 users. Note: If one of the FileUtils functions crashes, you will need to use the standard MMBasic CLEAR command to clear all variables, otherwise when you try to use any FileUtils function you will only get another error complaining about some variable being already declared. |
||||
Mixtel90 Guru  Joined: 05/10/2019 Location: United KingdomPosts: 5726 |
Oh, so close! I can see this being very useful. Going back over 40 years, the old Nascom computers used 16 lines of 48 characters, with the top line not scrolled (for hardware reasons). In reality the lines were 64 characters long but were truncated to fit the screen area. I would humbly suggest that you rearrange the BIN display to be similar to the Nascom T ssss ffff one (ssss=start address, ffff=end address): Drop the &H from the address (not needed) and 2 values per line. aaaaa hh hh hh hh hh hh hh hh x..x..x. a=hex address (I've shown a 5-char address, but you may be able to get 7 chars) hh=hex value x is valid ASCII character . is invalid ASCII character That's 38 characters to the line so you can get 18 lines of hex values, 144 per page. Also the addresses line up nicely in hex. This is shown using 16-line pages, 128 values per page. This would leave a line for "Start=aaaaa End=aaaaa" and another for "More?": 00000 00 01 02 03 04 05 06 07 ........ 00008 41 42 43 44 45 46 47 48 ABCDEFGH 00010 30 31 10 33 34 20 36 37 01.34 67 . . 00070 00078 next page 00080 00088 00090 . . 000F0 000F8 Edited 2021-11-12 20:36 by Mixtel90 Mick Zilog Inside! nascom.info for Nascom & Gemini Preliminary MMBasic docs & my PCB designs |
||||
| lizby Guru Joined: 17/05/2016 Location: United StatesPosts: 3015 |
Nice. Thanks. I've added to Armmite F4 on Fruit of the Shed I've found the 800x480 3.97" TFT LCD touch display IPS/OTM8009A (with adapter) best for F4 console work. ~ Edited 2021-11-13 00:34 by lizby PicoMite, Armmite F4, SensorKits, MMBasic Hardware, Games, etc. on fruitoftheshed |
||||
| erbp Senior Member Joined: 03/05/2016 Location: AustraliaPosts: 186 |
Hi Mick, Thanks for the suggestion re the output format for the FileBinList function. It will allow approx 60% increase in the file data that can be displayed per page. I will investigate implementing that format as soon as I get time. @lizby, Thanks for adding this to Fruit of the Shed, I had thought of doing it myself but I'm not sure of the process so it ended up in the too hard basket. Thanks also for the info re the IPS/OTM8009A LCD. I might try out one of those on a future project. Phil. |
||||
| erbp Senior Member Joined: 03/05/2016 Location: AustraliaPosts: 186 |
Hi, Here is an update to the FileUtils library that I posted back on 12 Nov 2021. This is Version 1.0.3 (the version is shown on line 3 of the source listing) and includes an updated FileBinList function implementing the suggestions made by @Mixtel90 (Thanks Mick). There are 2 changes compared to the original version of this function:- 1. The output is formatted differently which allows 128 bytes from the file per console screen to be displayed in Hex and printable characters in Alpha with non-printable chars shown as a period (.) in the Alpha section. This compares to only 70 bytes per screen in the original. Also the format is more readable and I suspect many will already be familiar it - see example screen images below. 2. The FileBinList syntax has been changed to add an optional Starting Byte Offset, so that you can select the starting position within the file that you wish to start listing from. Note that this is an Offset value so is zero based and may be specified as a decimal value or in hexadecimal using the &H prefix. The default if this argument is not specified is zero, so the listing will start from the first byte in the file. There is an updated Help page for the FileBinList function to show the changed syntax - example screen image also shown below. FileBinList Output examples - Stream File   FileBinList Output examples - Record Based File   Updated Help Information for FileBinList  Updated source file: FileUtils.zip |
||||
| Mixtel90 Guru Joined: 05/10/2019 Location: United KingdomPosts: 5726 |
I like this. :) Mick Zilog Inside! nascom.info for Nascom & Gemini Preliminary MMBasic docs & my PCB designs |
||||
 Print this page |
