4.9 KiB
FRAM_MULTILANGUAGE
Library for FRAM_MULTILANGUAGE (FRAM_ML) to be used with the FRAM_I2C library.
Description
The FRAM_MULTILANGUAGE (FRAM_ML) is an experimental library that uses an FRAM object to persistent store text tables. Typical use is to implement multi languages translations. The storage of text in FRAM reduces RAM usage of an Arduino quit a lot.
The FRAM_ML supports up to 5 languages, this is hard coded in the first version (0.5.1). An FRAM of 32KB can easily store many hundreds or even thousands (shorter) strings. This allows to store e.g. 600 strings in one language or 300 in two languages or 120 in five languages.
The FRAM_ML can use only part of an FRAM and multiple FRAM_ML objects can use the same FRAM.
The current implementation is very straightforward, which is not memory efficient. The advantage is it performs pretty well as every string can be found with little math.
As this library is experimental, implementation and API might change in the future.
Version
The FRAM_MULTILANGUAGE library follows FRAM_I2C version number.
Interface
#include "FRAM_MULTILANGUAGE.h"
Constructor
- FRAM_ML() Constructor.
- uint32_t begin(FRAM *fram, uint32_t memAddr, uint8_t languages, uint8_t strings, uint8_t maxLength)
initializes the FRAM and writes the parameters to FRAM for persistency.
- fram = pointer to FRAM object.
- memAddr = start memory address in FRAM.
- languages = number of language tables ( max 5 hardcoded).
- strings = number of strings in lookup table.
- maxLength = length of largest string. (first design is not memory efficient).
- returns uint32_t == first free (next) FRAM location.
- uint32_t begin(FRAM *fram, uint32_t memAddr)
initializes the FRAM and reads the parameters (see above) from the FRAM.
- fram = pointer to FRAM object.
- memAddr = start memory address.
- returns uint32_t == first free (next) FRAM location.
- int getMaxLanguage() idem.
- int getMaxStrings() idem.
- int getMaxLength() idem.
Read write language abbreviation.
The FRAM_ML allows to store the country codes of the languages used in FRAM. This is not mandatory. See https://www.nationsonline.org/oneworld/country_code_list.htm
- int setLanguageName(uint8_t index, const char * str)
- index = 0..n, typical smaller than MaxLanguage.
- str = country code == max 3 chars e.g. "IRL", "EN", "FR", "P".
- returns error status.
- int getLanguageName(uint8_t index, char * str) to fetch names.
- returns error status.
read write text strings
- int setLanguage(uint8_t index) set the current language to use.
This makes access easier as one often stays within one language.
If only one language is used this function is not used.
- returns error status.
- int getLanguage() returns the current set language.
- int setText(uint8_t index, const char * text) writes text to FRAM
under the index of the current language.
- returns error status.
- int getText(uint8_t index, char * text) reads text to FRAM
under the index of the current language.
- returns error status.
Error codes
| value | description | Notes |
|---|---|---|
| 0 | FRAM_ML_OK | |
| -10 | FRAM_ML_INDEX_OUT_OF_RANGE | |
| -20 | FRAM_ML_TEXT_TOO_LONG |
Memory layout
Address is relative to base address.
| ADDRESS | DESCRIPTION | Notes |
|---|---|---|
| 00 | version = 1 | |
| 10 | languages | |
| 11 | strings | |
| 12 | maxLength | |
| 20 | country codes | |
| 40 | tables |
Future
Must
- test
- documentation
Should
- add setName(const char * str) + getName(char * str)
- length 8, position 2..9
Could
- performance sketch.
- memory check in begin(fram, addr, languages, strings, length)
- version check in begin().
- add getVersion()
- add CRC32 over tables to test integrity?
- per table or total?
Wont (unless)
- checking if translation exist / FRAM filled properly.
- user responsibility
- set read-only flag in begin(fram, addr)?
- user responsibility.