Amulet Internal RAM

Amulet has over 1 KiB of onboard RAM which we have turned into virtual dual port RAM. There are 256 different byte variables, 256 different word (16-bit) variables, 256 different Color (32-bit) variables, and 256 different 25-character null terminated string variables (25+1=26 bytes allocated per string variable). Amulet Widgets can read or write to these Internal RAM variables. The Internal RAM variables can also be saved in flash, thus giving the variables permanence. In addition, an external processor can read and write to these Internal RAM variables as well. The external processor can send an unsolicited serial message to the Amulet to read or write to the Internal RAM variables. This means that the external processor is not required to be the Amulet's slave. Follow this link to learn more about the communication protocol. You can setup your pages to a) have the Amulet always be the master, b) have your processor always be the master or c) have a dual master system.

Some of the main features of InternalRAM:

1) Internal RAM variables can survive from page to page of your GUI project.
2) Internal RAM can be saved back to the flash, so the variable can persist even after powering down.
3) Internal RAM variables can be used as arguments within Amulet methods. i.e. (Amulet:UART.byte(0).setValue(InternalRAM.byte(2)))
4) Internal RAM variables can be used as variable indices. i.e. (Amulet:UART.byte(InternalRAM.byte(0)).setValue(2))

Internal RAM nomenclature:

The href nomenclature for Internal RAM's is Amulet:InternalRAM.variableType(variableNumber).method()

As a point of reference, the nomenclature to specify the Internal RAM variables in the code is the same as specifying external variables. External variables expect the UART object to be used whereas the Internal RAM variables use the InternalRAM object. For example, to have an Amulet Bargraph Widget tied to an external byte variable # 2, the href attribute would look like this:

"Amulet:UART.byte(2).value()"

To be tied to an Internal RAM byte variable # 2, then the href attribute would look like this:

"Amulet:InternalRAM.byte(2).value()"

The UART object specifies the Amulet will send out a serial message to an external processor requesting the value of the external byte variable number 2. The InternalRAM object specifies that the Amulet will read the value of the Internal RAM byte variable number 2. The InternalRAM object will not send out any serial requests since the Amulet is capable of reading the Internal RAM directly.

Using InternalRAM variables as method arguments:

A powerful feature of Internal RAM variables is that they can be used as arguments within Amulet href methods. This means that instead of using a Control Widget's intrinsic value as a function parameter, you can use Internal RAM variables, which can be changed at run-time by your external processor. Internal RAM byte, word and string variables can all be used as method arguments. For example, to have a button send out an RPC that is defined by Internal RAM byte variable #1, you would use the following nomenclature:

"Amulet:UART.invokeRPC(InternalRAM.byte(1))"

The value which is contained within Internal RAM byte variable #1 would be sent out as the RPC number over the UART.

Another example which sends out an Internal RAM string variable:

"Amulet:UART.string(0).setValue(InternalRAM.string(2))"

This sends the string contained within Internal RAM string variable #2 out the UART as a "set external string variable #0" command to an external processor.

When using Internal RAM variables as method arguments, use the following naming conventions:

InternalRAM.byte(x)
InternalRAM.string(x)
InternalRAM.word(x)

Do not precede with Amulet: or end with .value().

Using InternalRAM byte variables as variable indices:

Another powerful feature of Internal RAM variables is that they can be used as variable indices for the base variable type. Since variable indeces only range from 0x00-0xFF, only Internal RAM byte variables can be used as variable indices. For example, to have a button set an external byte variable that is defined by InternalRAM byte #1 to a value of 0x20, you would use the following:

"Amulet:UART.byte(InternalRAM.byte(1)).setValue(0x20)"

The value contained within Internal RAM byte variable #1 would be used as the external byte variable number to set to 0x20.

Another example which reads the Internal RAM word variable defined by InternalRAM byte variable #0 would use the following:

"Amulet:InternalRAM.word(InternalRAM.byte(0)).value()"

The value contained within Internal RAM byte variable #0 would be used as the Internal RAM word variable number to read from.

When using Internal RAM variables as variable indices, use the following naming convention:

InternalRAM.byte(x)

Do not precede with Amulet: or end with .value().

Note: Internal RAM byte variables can only be used as a variable index of the base variable type of an href function. It cannot be used as an index to an Internal RAM variable being used as a method argument. That means the following CANNOT be used:

"Amulet:UART.invokeRPC(InternalRAM.byte(InternalRAM.byte(5)))"

It is acceptable to have an href which uses Internal RAM variables as both a variable index as well as an argument. It can be a little confusing to look at, though. The following is a valid href:

"Amulet:InternalRAM.word(InternalRAM.byte(5)).setValue(InternalRAM.word(6))"

Which would result in the Internal RAM word variable number defined by the value of InternalRAM byte variable #5 set to the value of Internal RAM word variable #6.

Note regarding using InternalRAM string variable for a button label:

When using an InternalRAM string as the label for a button which is using FromInitHref as its label, the initHref parameter of the button should look like: Amulet:InternalRAM.label(x).value(), where x is the index of the Internal RAM string variable. There is not a separate bank of Internal RAM label variables, this function will return the string associated with Internal RAM string variable # x. Due to the requirement of the button to have a label returned to it, it was necessary to create an InternalRAM label variable, but it shares the exact same memory space as the Internal RAM string variables. The Internal RAM label should only be used in this application.

Initializing Internal RAM variables at compile time:

By default, all Internal RAM variables are initialized to zero. You can initialize Internal RAM variables at compile time by including an initialization file in your project. The initialization file must have an "ini" extension and must reside in the same directory as your GUI project. You must include the initialization file in a META tag in the start or home page of your project. The syntax to include the file is:

<META NAME="initInternalRAM" SRC="filename.ini">

The initialization file, filename, must have a .ini extension and it must be located in the same directory as your main html page. Inside the initialization file, any line preceded with // is treated as a comment. All initializations must be located in the far left column, so do not tab over. The HTMLCompiler recognizes both decimal and hexadecimal numbers.

Initializing single Internal RAM variables:

The syntax within the include file to initialize a single Internal RAM variable is as follows:

InternalRAM.variableType(variableNumber) = value

Examples:

InternalRAM.byte(0xFE) = 0x7F
InternalRAM.word(32) = 4000
InternalRAM.color(0) = 0x000000FF
InternalRAM.string(0) = "First String"

There is an important thing to note regarding the 256 25-character (plus a null) strings. It is acceptable to have strings and initialize strings that are longer than 25 characters (up to 248 characters). You just need to be aware that the string will run on into the next string variable's RAM space. So, if you know your Internal RAM strings are going to be more than 25 characters, you might want to only use every other string variable index. i.e. InternalRAM.string(0), InternalRAM.string(2), InternalRAM.string(4)...etc. Keep in mind that this will effectively give you only 128 string variables instead of the standard 256.

When initializing Internal RAM strings, user-defined wraps can be specified by entering "\n" within the string. Since we use double quotes to define a string, to have a literal double quote appear in the string, enter two double quotes in a row.

User-defined wrap example:   InternalRAM.string(0) = "top line\nbottom line"

Double quote example: InternalRAM.string(0) = """this phrase"" is quoted"

Initializing multiple Internal RAM variables:

It is also possible to initialize a block of contiguous Internal RAM variables. The syntax to initialize a block of Internal RAM variables is as follows:

InternalRAM.variableType(variableNumberStart-variableNumberEnd) = value

Example:

InternalRAM.byte(0xFC-0xFF) = 0x7F
InternalRAM.word(0x00-0xFF) = 0xFFFF
InternalRAM.color(0x00-0xFF) = 0xFFFFFFFF
InternalRAM.string(0-10) = "undecided"

Note: When initializing a block of contiguous Internal RAM strings, the initialization string must be 25 characters or less. By default, each Internal RAM string variable holds a maximum of 25 characters and null character.

Initializing special attributes in Internal RAM string variables:

When initializing string variables, it is possible to specify special attributes, such as font style, line feeds and upper ASCII characters.

The font styles available are plain, bold, italic, underline and strikethrough. If it is desired to set the font style within the initInternalRAM file, that can be done by using the font style escape sequence "%s(xxx)", where xxx is bit representation of the desired font style. See the table below for the list of font styles and their corresponding bit location. Each font style is represented by a single bit within the font style byte. Multiple font styles can be specified at one time, except in the case of plain, which must stand alone.

For example, to initialize InternalRAM string #0 with a string that is formatted to look like this:  "this is bold" you would use the following:

InternalRAM.string(0) = "this is %s(0x20)bold"

Line feeds are entered in the initInternalRAM file as "\n". For example, to initialize InternalRAM string #1 with a string that is formatted to look like this:
"this is
the break"
You would use the following:

InternalRAM.string(0) = "this is\nthe break"

Upper ASCII characters can be entered similar to font styles. Use the raw byte escape sequence "%r(xxx)", where xxx is the value of the raw byte to include in the string. For example, to initialize InternalRAM string #2 with a string that is formatted to look like this: "this is a ©" you would use the following:
InternalRAM.string(0) = "this is a %r(0xA9)"

Reloading the initialized InternalRAM variables on a per page basis:

By default, the InternalRAM variables are loaded from the serial data flash into the internal SRAM of the Amulet GEM-compliant Chip only once upon power up. If it is desired to reload the internal SRAM with the InternalRAM variables that are stored in the serial data flash on a per page basis, you can use an Amulet META tag with the ReloadInternalRAM attribute to specify this. There are three dot modifiers that will specify the scope of the reloading from serial data flash: .page, .project, and .notThisPage. The dot modifier .page will reload the InternalRAM only on the page that the meta is included. By using the dot modifier .project, every page in the project will reload the InternalRAM from the serial data flash unless a page has the meta using ReloadInternalRAM.notThisPage.

If the InternalRAM is to be reloaded, it happens immediately upon the loading of the page. Any time that page is navigated to, the InternalRAM will be reloaded.

Example usage:

 <META name="Amulet" content="ReloadInternalRAM.page">

Internal RAM specific methods:

There are a number of methods that are specific to the Internal RAM variables. All three variable types have their own specific methods. See the tables below for a description of all available methods.

Table 1. InternalRAM byte method descriptions.

Table 2. InternalRAM word method descriptions.

Table 3. InternalRAM color method descriptions.

Table 4. InternalRAM string method descriptions.

Table 5. Miscellaneous InternalRAM method descriptions.