PDA

View Full Version : Settings Object



darco
05-08-2008, 01:45 AM
I just uploaded my first object to the obex, and I wanted to mention it here because I think a lot of people would find it to be extraordinarily useful.

"settings" - obex.parallax.com/objects/314/ (http://obex.parallax.com/objects/314/) (Object is attached to bottom of this post if that URL doesn't work)


the description said...
This object handles the storage and retreval of variables (indexed by arbitrary word-sized integers) and data which need to persist across power cycles. Very easy to use, and thread safe. Since it is effectively a "singleton" type of object, it allows for some rudamentry cross-object communication.


Data can be stored and retrieved with a "key", which is a word-sized integer. Settings can be easily written to EEPROM for persistent storage. Has some convenient methods for storing longs, words, and bytes, as well as strings.

Here is the documentation:

Settings Object v1.0
Robert Quattlebaum <darco@deepdarc.com>
PUBLIC DOMAIN

This object handles the storage and retreval of variables
and data which need to persist across power cycles.

By default requires a 64KB EEPROM to save things persistantly.
You can make it work with a 32KB EEPROM by changing the
EEPROMOffset constant to zero.

Also, since it is effectively a "singleton" type of object,
it allows for some rudamentry cross-object communication.
It is not terribly fast though, so it should be read-from
and written-to sparingly.

The data is stored at the end of hub ram, starting at $8000
and expanding downward.

The format is as follows (in reverse!):

1 Word Key Value
1 Byte Data Length
1 Byte Check Byte (Ones complement of key length)
x Bytes Data
1 Byte (Optional) Padding, if size is odd

The data is filled in from back to front, so that the
size of settings area can be adjusted later without
causing problems. This means that the actual order
of things in memory is reverse of what you see above.

Even though it is written stored from the top-down, the
data is stored in its original order. In other words,
the actual data contained in a variable isn't stored
backward. Doing so would have made things more complicated
without any obvious benefit.

Object "settings" Interface:

PUB start
PUB revert
PUB purge
PUB stop
PUB commit
PUB size
PUB findKey(key) : retVal
PUB firstKey
PUB nextKey(key)
PUB getData(key, ptr, size_)
PUB removeKey(key) : iter
PUB setData(key, ptr, size_) : iter
PUB getString(key, ptr, size_) : strlen
PUB setString(key, ptr)
PUB getLong(key) : retVal
PUB setLong(key, value)
PUB getWord(key) : retVal
PUB setWord(key, value)
PUB getByte(key) : retVal
PUB setByte(key, value)

Program: 286 Longs
Variable: 0 Longs

__________
PUB start

Initializes the object. Call only once.
___________
PUB revert

Retrieves the settings from EEPROM, overwriting any changes that were made.
__________
PUB purge

Removes all settings.
_________
PUB stop


___________
PUB commit

Commits current settings to EEPROM
_________
PUB size

Returns the current size of all settings
__________________________
PUB findKey(key) : retVal

Returns non-zero if the given key exists in the store
_____________
PUB firstKey

Returns the key of the first setting
_________________
PUB nextKey(key)

Finds and returns the key of the setting after the given key
_____________________________
PUB getData(key, ptr, size_)


__________________________
PUB removeKey(key) : iter


____________________________________
PUB setData(key, ptr, size_) : iter


________________________________________
PUB getString(key, ptr, size_) : strlen


________________________
PUB setString(key, ptr)


__________________________
PUB getLong(key) : retVal


________________________
PUB setLong(key, value)


__________________________
PUB getWord(key) : retVal


________________________
PUB setWord(key, value)


__________________________
PUB getByte(key) : retVal


________________________
PUB setByte(key, value)




I wrote this object primarily for my ybox2 (http://www.deepdarc.com/ybox2/) project, but I thought it was useful enough to spin off into the world on its own.

Feedback is welcome!

▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔

darco
www.deepdarc.com/ (http://www.deepdarc.com/)
xmpp:darco@deepdarc.com (mailto:xmpp:darco@deepdarc.com)

Post Edited (darco) : 5/7/2008 6:11:36 PM GMT

Searider
05-08-2008, 02:57 AM
Wow, this is great. I can already think of how it could help me in a project I am working on. Thanks for sharing!

▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔
--------------------

Searider
--------------------