Some Precise controllers manufactured after June 2013 include a small area of Non-Volatile Memory (NVRAM) that is user accessible. The NVRAM contents are preserved when the controller power is turned off. This area was added to permit applications to store a limited amount of key dynamic state information such as performance statistics or System Error Log entries.
The NVRAM is different from the non-volatile flash memory (device /flash) in that the NVRAM is not affected by unexpected power-off conditions. After writing to the /flash device, you must wait for at least 15 seconds before powering off the controller. If you do not wait, the /flash contents may become corrupted and you may lose all of the files stored on the /flash device. The NVRAM can be written without danger of corrupting existing data, even if the power is turned off during a write operation. Of course, the data actively being written may be lost.
Another difference is that the flash memory can only be written a finite (but relatively large) number of times, whereas the NVRAM can be written an unlimited number of times.
The major downside of the NVRAM is that its storage area is small compared to the flash memory. Depending on your controller model and options, the NVRAM size may be 8Kbytes or 32Kbytes. On these devices, about 320 bytes are reserved and cannot be written.
Data may be stored in files on the NVRAM by specifying the device /NVRAM. This device may be used with all types of I/O methods, including StreamWriter, StreamReader, and FTP.
To maximize the space available for data, a maximum of 16 NVRAM files may be created, and the names must be "file1" through "file16".
When an NVRAM file is created, it's maximum size should be defined by appending the following switch to the file path specification:
-size n
where n is the maximum size of the file, in bytes. This value may range from 4 to the maximum number of unused bytes on the device (less than 7873). Once a file is created, its size cannot be changed unless the file is deleted and created again.
If “-size n” is omitted when creating a new file, a default size of 1024 bytes is assumed.
To assist in logging data to the NVRAM, a file may be specified to act as a circular buffer that wraps around to the beginning once it reaches its maximum size. This mode of operation is enabled by appending the following switch to the file path specification:
-wrap
In a circular file, new data overwrites the oldest data once the maximum file size is reached. In a normal non-circular file, an error is signaled if an attempt is made to write when the file is full.
By searching for the final record in a file, you can always find the latest entry, even after a power failure.
When a NVRAM file is written, the data is stored as a record. Each record can have a maximum length of 255 bytes. Each record is written atomically, that is, either the entire record is written or none of the record is written, even if the power fails during the write operation. In a circular file, entire records from the start of the file are removed atomically before new records are added. In this way, records in the file are never left in a partially updated state.
Delaying an output request to the NVRAM by buffering defeats some of the NVRAM benefits, since buffered data may be lost during a power fail. To avoid this problem, StreamWriter objects for device /NVRAM have AutoFlush enabled by default. If you disable AutoFlush, you need to be aware of the implications and use the Flush method appropriately.
There is one byte of overhead for the entire file, and one byte for each record. You should account for this overhead when computing the maximum number of records that a file can contain.
There are no special considerations for reading an NVRAM file except that attempting to read a circular file while it is being written may return inconsistent data.
The files in the /NVRAM device may be accessed by a remote FTP client. If your host computer supports this service, the /NVRAM folder shows up in the top-level FTP directory. FTP always displays the maximum allocated file size and the date and time the file was last modified.
In this example, a non-circular file with a maximum length of 64 bytes is created,
Dim tfile As New StreamWriter("/NVRAM/file2 -size 64", True)
Dim ii As Integer
For ii = 1 To 100
tfile.WriteLine("Record " & CStr(ii))
Next ii
tfile.Close
This program fails with ii = 6 with error -323 (Device full). At this point, /NVRAM/file2 contains the following records:
Record 1
Record 2
Record 3
Record 4
Record 5
In the next example, a circular file is created of the same size.
Dim tfile As New StreamWriter("/NVRAM/file3 -size 64 -wrap", True)
Dim ii As Integer
For ii = 1 To 100
tfile.WriteLine("Record " & CStr(ii))
Next ii
tfile.Clos
This program does not fail. After execution completes, /NVRAM/file3 contains the final records written:
Record 96
Record 97
Record 98
Record 99
Record 100
In GPL 4.0 and later, a new feature was added that automatically writes system error messages into a specified file as the errors occur. This feature is enabled by writing the file name into the Parameter Database entry "Error log file" (DataID 323). This feature was designed with the NVRAM in mind but can be used with other file structured devices as well.
To automatically enable error message logging into the NVRAM, a file name and file size must be specified. For example, DataID 323 could be set to:
"/NVRAM/file1 -size 7500 -wrap"
This would write all new error messages into file1 using most of the available NVRAM space. The maximum size could be set to 7872. The "-wrap" will create a circular buffer so that older messages will be over-written by new messages when the file becomes full.
Prior to enabling error logging, the console command "Del" should be used to make space for the error log file.
Please see the documentation on "Error log file" (DataID 323) for a full list of the options available with this feature.
For some applications, only a small amount of data needs to be saved and the flexibility offered by the file system is not required.
GPL provides eight 32-bit signed integers that are stored in the NVRAM and accessed by DataID 1892 "GPL program NVRAM variable array". These DataID values may be freely read or written by GPL programs or the web interface. The most recent value written is always saved in the NVRAM. The four bytes that make up each 32-bit value are always written atomically, so each 32-bit value is always valid.