Command API

Introduction

Files can be handled just like using a command line shell on a regular computer. There's a DIR command that can be used to list all files in a directory. Simple open, read and write operations are possible by hand or may be invoked by any device that is connected to the I/O interface.

The following is a short tutorial that shows how to read and write files on SD card. If you want to work through it, please create a file on a FAT16/32 formatted card (by using a PC or something like that), name it "hello.txt" and insert it into the SD slot of your Avisaro-Module. The file should contain a single line: "the_quick_brown_fox_jumps_over_the_lazy_dog". You need also a terminal connected to the I/O interface of the Avisaro Module. In case of RS232, you may find this tool useful.

Reading existing files

Suppose there's a SD-card inserted that has a file named "hello.txt" in its main directory. To open it for reading and get all its content, can simply be done with two commands:

open 1 hello.txt
stream 1

After that, the module transmits the entire file content to your terminal:

the_quick_brown_fox_jumps_over_the_lazy_dog

Please note the 1 before the file name. This is something called a "File Handle". File handles are used to identify and access files after they were opened. You will see that the 1 from here is used in all subsequent file commands.

Often, it is more practical to read files chunk by chunk than getting all that stuff as a whole. This can be done with the READ command. Note that we first must close the file, before we can open it again.

close 1
open 1 hello.txt
read 1 9

After that, you get only the first nine charcters, which are:

the_quick

To read the next two words, invoke READ again:

read 1 10

And this is what you get:

_brown_fox

So to say, calling READ again and again moves the internal "File Pointer" towards the end, until there's nothing more to read. Try it yourself and see what happens. Tip: if ERR33 appears, type ERR?

By the way, the file pointer not only moves automatically on READs. There's a command called POS that you can use to set the file pointer to any position in the file. Try this:

pos 1 20
read 1 10

And you will see:

jumps_over

POS has moved the file pointer to the 20th position, so reading 10 characters from there gives you the output above.

Finally, when we're ready, a file should be closed using the CLOSE command (we already done that before). Closing files frees all ressources associated with them and, in case of writing, ensures that cached data is flushed to disk. So, do it now:

close 1

Creating and writing files

Now that you know how to open and read files, this part of the tutorial shows you how to create new files and put data into them. First we must create a new file on disk. Let's do this, we create a new file named "myfile.txt":

new 1 myfile.txt

This creates a new file and also opens it for writing. If you get an ERR27, you possibly forgot to close the file used by the previous section, which also uses file handle #1, type CLOSE 1 and then try again.

Invoke DIR to see what's on your SD card:

dir

The output should be:

myfile.txt 0
hello.txt 43

Don't worry if output on your module appears in reverse order, the DIR command reads the file system structures directly and doesn't sort what it finds. It's more essential that you see the new file "myfile.txt" with zero length. That's the file you created just now.

As mentioned before, the file is already open. To write data data into it, simply enter streaming mode:

stream 1

Everything you type, after this command, is written to the file. Now type the this (only the six characters without return):

123456

After that type three plus signs:

+++

As you may notice, immediately after the third + the Module prompt (usually a >) appears to indicate that the module has left streaming mode and entered command mode again. The sequence of three pluses is the module's so-called "stop sequence". It is also used in other situations, where it must be possible to leave data mode.

As a contrast to reading, it is inherently important to close a file after you're done with write operations. If you miss that, it's most likely that not all data is written to disk. So let's do it:

close 1

Now assume that six bytes, the characters 123456 are written into the file, you may satisfy yourself. Type:

dir

...and verify that the output looks like:

myfile.txt 6
hello.txt 43

Myfile.txt contains six bytes, is it true? Ok, then let's append some more data. For this to work, we must open "myfile.txt" again but in this case, we need a special command that opens an existing file for writing and moves the file pointer to the end. The command is named APPD, let's do it:

appd 1 myfile.txt

The file is opened again. Now we introduce another command that can be used to write data into a file. Differently from streaming mode, this command writes all of its second argument into the filel. Just see how simple it is:

write 1 abcdef

That's all we need to put the characters "abcdef" at the end of the file. Let's close the file and see the directory:

close 1
dir

The output now should look like this, "myfile.txt" must be six bytes bigger:

myfile.txt 12
hello.txt 43

Finally, make sure the file content is really that what you assume. You can easily verify that by showing the entire file (as you learned from the first section):

open 1 myfile.txt
stream 1

Do you see "123456abcdef", right?

 

That's all!