WRITE

Syntax : WRITE Location,Value
Syntax : WRITE Location, {Word}Value {, {Word}Value ...}

Function

Write Value into Location in EEPROM. On the BS2 family, multiple Value may be written to consecutive locations.‡

• Location is a variable/constant/expression* (0 - 255 on BS1, 0 - 2047 on all other BASIC Stamp modules) that specifies the EEPROM address to write to.
• Value is a variable/constant/expression* (0 - 255, or 0 - 65535 if using the optional Word modifier‡) specifying the value to be stored.

* Note: expressions are not allowed as arguments on the BS1.

‡Note: The optional arguments require PBASIC 2.5.

Quick Facts

Explanation

The EEPROM is used for both program storage (which builds downward from address 255 on BS1, 2047 on all other BASIC Stamp models) and data storage (which builds upward from address 0). The WRITE instruction stores a value to any EEPROM address. Any location within the EEPROM can be written to (including your PBASIC program's locations) at run-time. This feature is mainly used to store long-term data to EEPROM; data stored in EEPROM is not lost when the power is removed.

The following WRITE command stores the value 245 at location 100:

  WRITE 100, 245

The EEPROM is organized as a sequential set of byte-sized memory locations. With the BS1, the WRITE instruction only stores byte-sized values into EEPROM. This does not mean that you can't write word-sized values, however. A word consists of two bytes, called a low-byte and a high-byte. If you wanted to write a word-sized value, you'll need to use two WRITE commands and a word-size value or variable (along with some handy modifiers). For example:

SYMBOL  value   = W1                    ' word-sized variable
SYMBOL  valLo   = B2                    ' B2 is the low-byte of W1
SYMBOL  valHi   = B3                    ' B3 is the high-byte of W1

Main:
  value = 1125

  WRITE 0, valLo
  WRITE 1, valHi
  END

value   VAR     Word

Main:
  value = 1125
  WRITE 0, value.LowByte
  WRITE 1, value.HighByte
  END

When this program runs, the two WRITE commands will store the low-byte and high-byte of the number 1125 into EEPROM.

With the BS2 family, the Word modifier can be used to write 16-bit values. The low byte of the value will be written to Location, the high byte will be written to Location + 1 ("Little Endian" ).

' {$PBASIC 2.5}

value   VAR     Word
value2  VAR     Word
addr    VAR     Word                    ' EEPROM address
test    VAR     Byte                    ' test byte read back

Main:
  value = $1125
  value2 = $2003
  WRITE 0, Word value, Word value2      ' write value at locations 0 & 1
                                        '  and value2 at locations 2 & 3

  FOR addr = 0 TO 3                     ' display "25 11 03 20"
    READ addr, test
    DEBUG HEX2 test, " "
  NEXT  

  END

EEPROM differs from RAM, the memory in which variables are stored, in several respects:

1. Writing to EEPROM takes more time than storing a value in a variable. Depending on many factors, it may take several milliseconds for the EEPROM to complete a write. RAM storage is nearly instantaneous.
2. The EEPROM can only accept a finite number of write cycles per location before it wears out. The table above indicates the guaranteed number of writes before failure. If a program frequently writes to the same EEPROM location, it makes sense to estimate how long it might take to exceed the guaranteed maximum. For example, on the BS2, at one write per second (86,400 writes/day) it would take nearly 116 days of continuous operation to exceed 10 million.
3. The primary function of the EEPROM is to store programs (data is stored in leftover space). If data overwrites a portion of your program, the program will most likely crash.

Check the program's memory map to determine what portion of memory your program occupies and make sure that EEPROM writes cannot stray into this area. You may also use the DATA directive on the BS2, BS2e, BS2sx, BS2p, and BS2pe to set aside EEPROM space.

On the BS1, location 255 holds the address of the last instruction in your program. Therefore, your program can use any space below the address given in location 255. For example, if location 255 holds the value 100, then your program can use locations 0-99 for data.

On other BASIC Stamp models, you'll need to view the Memory Map of the program before you download it, to determine the last EEPROM location used.

On the BS2p, BS2pe and BS2px the READ and WRITE commands can affect locations in any program slot as set by the STORE command. See the STORE command for more information.