Quickstart

  1. Download the tar file1, unpack it, and copy the four files to somewhere on the PATH.
  2. If you want to:

The Software

There are five Perl programs which can be downloaded in a tar file. To install the software, unpack the tar file and copy the files to somewhere on your PATH. For example:

% tar xzvf http://www.mjoldfield.com/mpfs2-util/mpfs2-util-0.1.1.tar.gz
% sudo mv mpfs2-* /usr/local/bin

In the fullness of time I'll package these a bit better. None of the programs need any MPFS2 specific modules, but mpfs2-make-image expects to find the other programs on the PATH.

Tarballs

MPFS2 and HTTP2

There's quite a close connection between Microchip's HTTP2 web server and MPFS2 file system, or more accurately the MPFS2.exe program. Explicitly the web server expands tags like ~foo~ in files when it transmits them, but for this to work the files have to be pre-indexed. MPFS2.exe does this, and so does the mpfs2-indexer program (which will usually be run by mpfs2-make-image).

Tags are defined in the HTTPPrint.idx file, which is just an ordered list of terms separated by |. The indexing process notes the offset of each tag and its index, and saves this information in a separate file. For example, the indexer might look at foo.htm, note that tag 3 is found at byte 3241 in the file and tag 1 at byte 4523, then save that in foo.ht#. When the MPFS2 file is built, files which have been indexed are tagged thus, so the webserver doesn't have to search the directory.

When HTTP2 serves the foo.htm file, it looks at foo.ht# too. So, it knows that when it gets to byte 3241 it should stop sending the file to the socket and call subroutine number 3. This subroutine sends some other data to the socket e.g. the value of the AN0 input, then returns control back to HTTP2. HTTP2 skips over the rest of the tag, then sends data as normal again. When it gets to byte 4523 the process repeats again, this time to subroutine 1.

When we talk about subroutine 1, the index refers to the position in a dispatch table. Obviously the dispatch table and the index files must be consistent, and so both are derived from the same HTTPPrint.idx file. This means that whilst you don't need the whole firmware source to generate new content for the server, you will need the .idx file if you're using any ~foo~ style tags.

There's one other connection between MPFS2 and HTTP2: a file can be marked as compressed. When HTTP2 serves such files it adds the appropriate HTTP header so the client will decompress it. Making compressed files is easy: just use gzip. In general this is a good thing to do, but obviously it's not compatible with the ~foo~ style tags.

The programs

mpfs2-make-image

This is the simplest way to make a MPFS2 image file. If you just have some files you want to upload to the HTTP2 based webserver, just put them in a directory, e.g. called imagedir, then just run

% mpfs2-make-image imagedir

which will create an imagedir.bin file which can be uploaded. Any .gz files will be tagged as compressed, though the .gz suffix will be removed.

If the files include ~foo~ tags, then you'll need the --idx option: see the documentation.

Finally, if you just want to test that all the ~foo~ tags work, then use the --test tag. This uses mpfs2-make-code7 to make a HTML file containing all the tags: it's by no means a perfect test, but it's an easy way to start.

Here are some examples of how the command is used:

# Normal operation: turn the image directory into image.bin
mpfs2-make-image image

  1. Fancier operation: index files
    mpfs2-make-image --idx=HTTPPrint.idx image
  1. Fancier still: include an HTML test file
    mpfs2-make-image --idx=HTTPPrint.idx --test=image/test.htm image
  1. Get documentation
    mpfs2-make-image --help

mpfs2-make-code

This turns the .idx file into code. Normally it produces a C source file containing the dispatch table and a suitable header file: this is slightly different than MPFS2.exe, so you'll need to read the documentation and modify your project.

It can also produce a scaffold file: a C file containing toy definitions for each function in the dispatch table. Some of these may conflict with existing functions, but it's useful when starting a new project.

Finally it can produce an HTML file which contains all of the ~foo~ style tags which can be helpful to see if things are working properly.

Here are some examples of how the command is used:

# Normal operation
mpfs2-make-code foo.idx

  1. Generate scaffolding C file
    mpfs2-make-code foo.idx --scaffold=stubs.c
  1. Generate HTML file which exercises all the tags
    mpfs2-make-code foo.idx --html=test.htm
  1. Get documentation
    mpfs2-make-code --help

mpfs2-fsutil

This actually manipulates the MPFS2 image. If you use mpfs2-make-image you won't use it directly to make images, but it's handy to examine existing images, or extract files from them.

Here are some examples of how the command is used:

# Create a filesystem
mpfs2-fsutil --create foo.mpfs2 a.htm b.css a.ht#

  1. Unpack a filesystem
    mpfs2-fsutil --extract foo.mpfs2
  1. See what's in a filesystem
    mpfs2-fsutil --list foo.mpfs2
  1. Get documentation
    mpfs2-fsutil --help

mpfs2-indexer

This indexes files. It's highly likely that you won't run it yourself, but instead will let mpfs2-make-image run it on your behalf.

Here are some examples of how the command is used:

# Normal operation
mpfs2-indexer HTTPPrint.idx foo.htm bar.htm ...

  1. Dump the things we're indexing to stdout
    mpfs2-indexer --dump HTTPPrint.idx foo.htm bar.htm ...
  1. Check that we agre with the exising index file
    mpfs2-indexer --check HTTPPrint.idx foo.htm bar.htm ...
  1. Get documentation
    mpfs2-indexer --help

mpfs2-img-to-c

Give a file system image, or indeed any other file, generate a C file which expresses the data as an array declaration, with an extra zero byte at the end.

Here are some examples of how the command is used:

# Normal operation: turn the image file into C file
mpfs2-img-to-c foo.bin

  1. Change output filename and variable name
    mpfs2-img-to-c --output=bar.c --c_variable=bar foo.bin
  1. Get documentation
    mpfs2-img-to-c --help

and here's an example of the resulting C file:

/***************************************************************
* foo.c
*
* DO NOT EDIT BY HAND : ALL MODIFICATIONS WILL BE LOST
*
* Generated from foo.bin at Sat Feb 23 14:14:01 2008.
*
***************************************************************/
#define __MPFSIMG2_C
#include "TCPIP Stack/TCPIP.h"
#if defined(STACK_USE_MPFS2) && !defined(MPFS_USE_EEPROM)

ROM BYTE MPFS_Start[] =
  {
     'a', 'b', 'c', '1', '2', '3',0x0a, /* 0000 */
    0x00
    };


#endif // #if defined(STACK_USE_MPFS2) && !defined(MPFS_USE_EEPROM)

Feedback

I'd be delighted to know if anyone finds these things useful.