1 [!

[Arduino library]
(https://www.ardu-badge.com/badge/OSFS.svg)](https://www.ardu-badge.com/OSFS)
2 [![Build Status]
(https://travis-ci.org/charlesbaynham/OSFS.svg?branch=master)](https://travis-ci.org/c
harlesbaynham/OSFS)
3
4 Overly Simplified File System (OSFS)
5 ====================================
6
7 Provides an extremely basic, low footprint file system for EEPROM access in
8 an Arduino or other AVR microprocessor. Could be ported to other architectures very
easily.
9
10 Note
11 ----
12
13 The example provided will work on devices with AVR architectures and
14 demonstrate how to use the build-in EEPROM for storage. However the library
15 can work on almost any microprocessor as long as you write the `readNBytes`
16 and `writeNBytes` functions to interface the library with your storage medium.
17
18
19 Usage
20 -----
21
22 The user must define interface functions to read / write from the memory in use.
23 This means that OSFS can be used for arbitrary storage media, including external
24 hardware interfaced by e.g. SPI.
25
26 To use OSFS with the Arduino EEPROM, copy the function definitions from the examples
27 into your program header.
28
29 Datatypes can be stored using the command `newFile`, e.g.
30
31 int testInt = 999;
32 OSFS::newFile("testInt", testInt);
33
34 Appending `true` to this command will overwrite pre-existing files of that name:
35
36 OSFS::newFile("testInt", testInt, true);
37
38 "Files" can be retrieved by calling `getFile`:
39
40 int testInt;
41 OSFS::getFile("testInt", testInt); // Now testInt == 999
42
43 OSFS will refuse to deal with your ROM unless it has first been `format()`ed:
44
45 OSFS::format();
46
47 All OSFS functions return an `enum class result` which will give you more information
48 if they fail. E.g.
49
50 using namespace OSFS;
51
52 r = getFile("testInt", testInt);
53
54 if (r == result::FILE_NOT_FOUND)
55 // File was not found
56 else if (r == result::NO_ERROR)
57 // File found
58 else {
59 // Another error occurred.
60 // See OSFS.h for a full list of error codes
61 int errCode = (int) r;
62 }
63
64 The OSFS functions `newFile` and `getFile` use templates to accept any data type,
including
65 custom classes or structs. See the example `writeTest.ino` for details.
66
67 Alternatively, `newFile` can write a given number of bytes into storage, starting at a
 given
68 location. This is particularly useful for storing strings, e.g.:
69
70 char testStr[15] = "this is a test";
71 OSFS::newFile("testStr", testStr, 15);
72
73 To retrieve items stored like this, you must manually get the file size and then read
the correct
74 number of bytes back out, like so:
75
76 using namespace OSFS;
77
78 char testStr[15];
79 unsigned int filePtr, fileSize;
80
81 r = getFileInfo("testStr", filePtr, fileSize);
82
83 if (r == result::NO_ERROR)
84 readNBytes(filePtr, fileSize, testStr);
85
86 Internals
87 ---------
88
89 This library has no support for fragmented files or directories. File names
90 are in 8.3 format: 8 chars followed by 3 for an extension. Filenames will be
91 padded to 11 chars by spaces.
92
93 Each file has a header of n bytes:
94
95 -----------------------
96 HEADER
97 File ID and extension (8+3 bytes)
98 Size of file (uint16_t = 2 bytes)
99 Pointer to start of next file's header (uint16_t = 2 bytes)
100 Flags (uint8_t = 1 bytes. MSB = 1 for deleted file, 0 for valid. Other bits
reserved)
101 -----------------------
102 FILE CONTENTS
103 Binary data with no restrictions (<Size of file> bytes)
104 -----------------------
105
106 `Size of file` and `pointer to next` are both present because a file may not
107 necessarily fill all the available space, e.g. if it has been overwritten
108 with a smaller file. As of v1.2, overwriting with a larger file is supported if
109 there is a sufficiently large continuous space available to place it in.
110
111 The first 4 bytes of EEPROM are reserved for information about this library:
112 Bytes 1 to 4 = "OSFS" Bytes 5 to 6 = uint16_t containing version info.
113
114 Unless these 6 bytes match their expected values, this library will consider
115 the EEPROM to be unformatted and will refuse to work with it until format() is called.
116
117 Interface functions
118 -------------------
119
120 For the library to work, you must teach it how to access your storage device;
121 you do this by defining the functions `readNBytes` and `writeNBytes` and the
122 `uint16_t`s `startOfEEPROM` and `endOfEEPROM`. Despite the names (kept for
123 backwards compatibility), these can be used to access any type of storage
124 medium, not just EEPROM. The example files show how this can be done for
125 accessing the built-in EEPROM on an AVR device. The tests show how to point
126 them at a chunk of RAM instead (slightly pointless in real life, since the
127 contents would be lost on power-off).
128
129 To define your own interface, copy the following definitions into your code:
130
131 ```
132 // Here we define the four pieces of information that OSFS needs to make a filesystem:
133 //
134 // 1) and 2) How large is the storage medium?
135 uint16_t OSFS::startOfEEPROM = 1;
136 uint16_t OSFS::endOfEEPROM = 1024;
137
138 // 3) How do I read from the medium?
139 void OSFS::readNBytes(uint16_t address, unsigned int num, byte* output) {
140 ... code that copies `num` bytes from your storage medium
141 at `address` into the waiting array `output` ...
142 }
143
144 // 4) How to I write to the medium?
145 void OSFS::writeNBytes(uint16_t address, unsigned int num, const byte* input) {
146 ... code that copies `num` bytes from the array `input`
147 into `address` on your storage medium ...
148 }
149 ```
150
151 You don't need to include checks for overflowing your memory bounds in `readNBytes`
and `writeNBytes` since OSFS will check `address` and `num` against the
`startOfEEPROM` and `endOfEEPROM` constants you provide.
152
153 Once these four components are defined, OSFS will now manage that chunk of
154 your storage medium. Call `OSFS::format()` to get going and follow the
155 examples for tips. Note that you don't have to provide OSFS with the whole
156 thing: it's just as happy managing a small piece of your memory as it is
157 managing all of it.
158
159
160
161 _Copyright Charles Baynham 2020_
162