All data is sent in the form of simple messages. All numeric data is a byte in length and is sent as an unsigned two digit hexadecimal value in ASCII with digits A through F in uppercase.
The data consists of a varible number of bytes based on the command and have meaning in the context of the command. Messages do not have to contain a data part.
The termination character value is 0xFF at present. This simplifies finding the character for the microcontroller and prevents collisions with common 7-bit characters. It may be changed to a 7-bit character before the initial version of the code is running.
The checksum is calculated by adding the bytes of the message, save for the terminator, in an unsigned byte (overflows are ignored) and finding the two's complement. The checksum value is sent as a two digit hexadecimal number following the terminator.
|
Command
|
Description
|
|
ER
|
Eeprom Read
|
The system's configuration data, including thresholds, time delays, and the config byte, are all stored in EEPROM. This command allows the computer to inspect the data. Refer to the configuration data reference for a list. The address space not used by configuration data may be used by the computer for whatever it wants. The total amount of EEPROM depends on which PIC microcontroller the system is running on.
Input:
The EEPROM address to read.
Output:
The value stored at the EEPROM address.
|
|
ES
|
External System power state
|
Reads the optional power state input. The input could be the antenna / external amplifier power control on a car stereo.
Input:
This is a request for data. Only the ID is sent.
Output:
"P" for powered, "U" for unpowered. The message may be sent immediately after a power state change (???). Computer shutdown should be controled by other factors.
Example: ESU
|
|
EW
|
Eeprom Write
|
The system's configuration data, including thresholds, time delays, and the config byte, are all stored in EEPROM. This command allows the computer to configure the system. Refer to the configuration data reference for a list. The address space not used by configuration data may be used by the computer for whatever it wants. Each EEPROM address can be written to approximately 100,000 to 1,000,000 times before the address fails. The total amount of EEPROM depends on which PIC microcontroller the system is running on.
Input:
The data is the EEPROM address followed by the value to write. If the value is already stored at the address, no write operation will occur to help extend the life of the EEPROM. After the write operation, the system will read back the value to see if it was written properly. If it reads back a different value than the one written, an error will be issued.
Example: To configure the system to shutdown the computer if the temperature drops below 2°C, issue this: EW0202
Output:
The value stored at the EEPROM address.
|
|
LP
|
clear Last Power status
|
Input:
The flag used to indicate if the computer was running when running power was last lost is also used to tell if the computer should be powered up the next time running power is applied. If this command is issued after loss of running power, it will clear the flag and prevent the computer from powering up without user input the next time running power is applied.
|
|
LV
|
Line Voltage
|
This is intended to help prevent draining a battery. The measured voltage is on the line suppling energy to the computer's power supply. DC is assumed.
Input:
This is a request for a voltage measurement. Only the ID is sent.
Output:
A byte representing the voltage is sent. The value is not the voltage itself, but instead is the raw value given by an analog to digital converter. It will likely require a liner transformation to change to a voltage, but the transformation may vary with the hardware and power supply used.
Example: The power supply is delivering 12v. That voltage is divided by 3 so that it is never more than 5v in this case. The ADC measures a 5v range and returns a value of 0 when the measured voltage is ground. The message is: LVCC
|
|
PS
|
Power State
|
Input:
This is a request for data. Only the ID is sent.
Output:
"P" for powered, "U" for unpowered. The message may be sent immediately after a power state change, however, if the new power state is "U", the computer is not required to start shuting down. Such a requirement should be made by user configuration.
Example: PSP
|
|
RR
|
eRRor code
|
Input:
Only the ID is sent. The error is treated as a checksum error because the system doesn't know how to deal with any other computer end errors. The microcontroller will resend the last message.
Output:
A code indicating the problem sent as a two digit hexadecimal number. The error defines in the code is the definative list, but a list is included here for your viewing pleasure.
|
Define
|
Value
|
Meaning
|
|
ERROR_GENERAL
|
0x01
|
Some error. Try to avoid using this error code.
|
|
ERROR_CHECKSUM
|
0x02
|
The last received message failed the checksum test.
|
|
ERROR_WRITE
|
0x04
|
The last EEPROM write operation failed.
|
|
ERROR_POSTPONE
|
0x08
|
The last shutdown request command is ignored because it would postpone the computer's shutdown too long. The condition can occur during a forced shutdown.
|
|
ERROR_ABORT
|
0x10
|
The last shutdown abort command is ignored because it was given at an inapropriate time, like during a forced shutdown.
|
|
ERROR_MSG_TOO_LONG
|
0x20
|
The received message was too big to fit into the system's message buffer. The entire message can be no longer than BUFFER_SIZE bytes long.
|
|
|
SA
|
Shutdown Abort
|
Input:
Only the ID is sent. If the system is counting down to cut power to the computer in response to a shutdown request command issued by the computer, the shutdown countdown will be discontinued and the shutdown will not occur. This command will not prevent a forced shutdown -- attempting to do so will generate an error.
Output:
Could be used, but probably won't be.
|
|
SF
|
Shutdown Forced
|
Used to force a shutdown after the environment (temperature or voltage) has exceeded a threshold. It is not issued for power state changes (default) unless the system is configured to do so.
Output:
The data sent is the number of seconds to loss of power expressed as a two digit hexadecimal number. The system will discontinue power to the computer after the indicated number of seconds. The computer can request more time by using the shutdown request message once. Adjust the POWER_OFF_FORCE value to change the time granted.
Example: SF2D for loss of power in 45 seconds.
|
|
SR
|
Shutdown Request
|
Used for shutdowns requested by the user or the computer.
Input:
The number of seconds to wait before discontinuing power to the computer. After receiving this message, the system will wait about the indicated time and then kill the computer's power. It can be used after a shutdown forced or request message to kill power sooner or later. This message can only be used once after a shutdown forced message and can extend the time up to POWER_OFF_FORCE, the amount of time given in the shutdown forced command.
Example: SR00 for immediate loss of power.
Output:
Only the message ID is sent. It indicates that a request has been made for the computer to shutdown by the user. The computer may chose to ignore the request. This is the only action the system will take in response to the user's shutdown request.
|
|
TE
|
TEmperature
|
Input:
This is a request for data. Only the ID is sent.
Output:
The raw 8-bit temperature value as a two digit hexadecimal unsigned number. The raw value is in twos complement format so that the temperature can be a negative value. The value is in celiceus (I can't spell). This value comes from a DS1621, DS1721, or similar device. It is intended that the device will read the ambient air temperature near the computer.
Example: TE1E for 30°C, TEF6 for -10°C
|
|
VC
|
Version Compatible
|
Input:
This is a request for data. Only the ID is sent.
Output:
The earlist version of the firmware with a compatible, not identical, message set. If the result from this message indicates an incompatible version, the software should try to limit itself to using the shutdown commands to limit the possibility of sending a command with an undesirable effect while hopefully maintaining the most basic functionality. The source code defines the string with the define VERSION_COMPATIBLE_STRING.
Example: VC20011029
|
|
VF
|
Version Firmware
|
Input:
This is a request for data. Only the ID is sent.
Output:
The version of the firmware as a date in the format yyyymmdd. The source code defines the string with the define VERSION_FIRMWARE_STRING.
Example: VF20020314
|