The OS functions each have a unique vector which is used to JSR to the appropriate function. These vectors will remain fixed, even if the functions themselves are moved around in the internal ROM. These vectors are defined in an include file which you can use in your programs.
Each OS function will use (and usually alter) the contents of ACC, R0, DPTR and any other registers used for parameters, unless otherwise noted. Byte parameters are usually passed and returned in ACC, and if a second byte parameter is used, in R0. Pointers are always passed and returned in DPTR. 16 Bit values are passed and returned in A (low byte) and R0 (high byte). The following notation is used to describe the parameters:
| ACC | BYTE | (first) 8-bit Parameter in ACC |
| R0 | BYTE2 | (second) 8-bit Parameter in R0 |
| R1 | BYTE3 | (third) 8-bit Parameter in R1 |
| DPTR | POINTER | Pointer parameter in DPTR |
| R0:ACC | WORD | 16-bit Parameter in R0 (high) & ACC (low) |
| DPH:DPL | BYTE3, BYTE4 | 2 8-Bit Parameters in DPH (BYTE3) and DPL (BYTE4) |
If an ampersand character is appended to the type, the value is returned in that register.
This function prints out the null terminated string pointed to by text on the LCD display. It observes and interprets the following control characters:
| ASCII Code (decimal) | Description |
| 0 | End of string |
| 1-7 | User defined characters. Character 0 accessible by ScrChr() only |
| 8 | Backspace |
| 9 | Tab |
| 10 | Linefeed (scroll up display if in second line) |
| 13 | Carriage Return (goto first column in current line) |
| 128 | Clear Screen |
| 129 | Home |
All other characters are output "as is" on the LCD display (see display data sheet for complete character set). The functions returns a pointer to the null character terminating the string. When outputting strings from a table this can be useful for advancing the pointer to the next string.
Prints out the character specified on the LCD display. No interpretation is performed on the character. (see display data sheet for complete character set). This function is useful for printing a single character only, or for accessing control characters otherwise processed by StrOut(). This is especially true for the user defined characters with character codes 0 to 7.
Prints the byte in ACC at the current cursor position in hexadecimal. This function is useful for debugging, but the end user does not normally want to see hex numbers.
Clears the LCD display and returns the cursor to the 0,0 position.
Returns the cursor to the 0,0 position, but leaves the LCD display contents intact.
This function is used to control the appearance of the cursor and the mode of the display.
| Bit set | Bit clear | |
| Bit 0 | Cursor on | Cursor off |
| Bit 1 | Cursor blinking | Cursor not blinking |
| Bit 2 | Display on | Display off |
Sets the cursor to the specified position on the display. Col may be in the range of 0-63 and Row may be in the range of 0-1.
Returns the current cursor coordinates. The values returned can be used directly to call Pos_Cursor(). Again, col may be in the range of 0-63 and Row may be in the range of 0-1.
Loads up to eight characters into the LCD display's character generator. The function always loads the characters starting at character 0. Count can be any value from 1-8. The font data pointed to by font must be consecutive. Each character consists of TBD font data bytes. Only the 5 least significant bits of each byte are used. The characters can be accessed as character codes 0 through 7.
Read a character from the keyboard. Function returns immediately if no character is available. Up to one keypress is buffered by the OS. In no character is available, the functions returns $FF. Otherwise the ASCII code of the key is returned. The #-key acts as the "Enter/Yes" key and is assigned the ASCII code 13, the *-key (sometimes also the "Esc/Abort/No" key) has the ASCII code 42.
Read a character from the keyboard. This function waits until a key has been pressed. Otherwise it behaves exactly as GetCh().
This function returns the current version of the operating system. Currently it returns $01:$00 (Version 1.00)
This function waits a number of 10 ms ticks. This is a simple way to implement delays.
This function returns the first RAM address usable by the Application program.
Sets the ALDL output to 10K (diagnostic mode). This is used to put some ECMs into diagnostic mode.
Sets the ALDL output to open (road mode). Not all ECMs output any information while the A & B terminals are open, but some do.
This function is useful for selecting one of a number of entries from a menu. The function is passed a pointer to a menu structure, and returns the zero based index of the menu entry the user selected. The selection is made using the "2" (up) and "8" (down) keys. The menu entry is selected with the "#" (Enter) key, or the selection is aborted with the "*" key. If the selection is aborted, the function returns $FF. The current item is marked with an arrow, and the display scrolls up and down automatically if necessary.
The menu structure pointed to by menu consists of one byte describing the number of entries in the menu, a zero byte and then a table of null separated strings as menu entries. The menu must consist of at least two entries and each entry should contain 15 null-terminated printable characters or less.
Example:
MOV DPTR,#MyMenu LCALL Sel_Menu ;function returns 0,1 or 2 RET ;if entry was selected or else $FF MyMenu: DB 3 ;3 entries DB 0 ;separator DB 'Choice 1',0 ;first entry DB 'Choice 2',0 ;second entry DB 'Choice 3',0 ;last entry
The message function is very useful for communicating long messages to the user. It formats a multiline message to fit the LCD screen. Msgptr points to a null-terminated string containing the message, lcdlen is the width of the LCD screen, typically 16.
The message is automatically broken down into several lines, and a line break can also be forced through the use of the vertical bar character (ASCII code 124).
The user can scroll down to view the entire message with the "8" or "0" keys. If the Escape ("*") or Enter ("#") key are pressed, the function returns.
The return value is the ASCII code of the key that caused the function to return. This is similar to a message-box under Windows, that can be used to ask the user a question, and the user can respond simply with yes/ok or no/abort.
This is a shortcut function intended to be used with Sel_Menu. jmptable is a jumptable consisting of three byte entries in the form "LJMP address". A is used to branch to an entry of the jumptable, with 0 branching to the first entry in the table, and so on.
The jumptable may have up to 64 entries.
This function is used to control the LED. The following table shows all possible parameter values:
| Value | Description |
| 0 | LED off |
| 1 | LED on |
| 2 | LED flashing slowly |
| 3 | LED flashing quickly |
This function is used to control the buzzer. The following table shows all possible parameter values:
| Value | Description |
| 0 | Buzzer off |
| 1 | Buzzer on |
| 2 | Buzzer beeping slowly |
| 3 | Buzzer beeping quickly |
This function calculates the CRC over a given block of memory. The block of memory may be up to 512 bytes long. The function is passed a pointer to the memory, an init value for the checksum, and the length of the block of memory in words. The function returns the CRC over the block of memory, and DPTR points to the first location after the block of memory.
In order to call the function multiple times for memory blocks larger than 512 bytes, only the num_words parameter needs to be passed, the other parameters will be initialized correctly by the previous call.
This function dumps 4 bytes in hex to the display in the following form:
ORG 0AB42H LABEL: DB 019H,02CH,075H,08FH ... MOV DPTR,#LABEL LCALL HexDump ... ;displays this line on the display: ; AB42:19 2C 75 8F
Upon return DPTR is incremented by four, so the function can be called to dump whole memory blocks with successive calls. The function does not output a CR/LF to prevent scrolling.
This function starts a simple single step function through a normally closed switch from the ALDL input to ground. This is extremely useful for debugging functions in conjunction with a listing of the program code being executed. After this function is called, execution will stop before the first instruction after the function call.
The contents of the following registers are shown on the LCD display (register values are examples only):
a12 b34 dp=ABCD pc8134 srC0 spC1
Register names are in lowercase characters: a=ACC, b=BCC, dp=DPTR, pc=PC, sr=PSW, sp=SP. If the switch is momentarily opened, a single instruction will be executed, the updated contents of the registers displayed, and execution again halted.
Note: This function will not step into operating system functions, but will halt again with the first instruction after the operating system call. Also, since the ALDL input is used, this feature can not be combined with any code relying on data being received through the ALDL input, but data reception must be carried out in realtime anyway, so this is not a real concern.
This function initializes the C3 (CCC = Computer Command Control) handler. It is passed a pointer to a RAM buffer to monitor and the size of the buffer. This is the number of bytes the handler will expect in each frame. Usually the number of bytes in a frame is 20 or 25.
The data in the buffer will continuously be updated while data is being received. If the connection is interrupted, the previous contents will remain in the buffer.
Exits the C3-handler and frees all buffers and internal variables again. Must be called before switching to UART- or Class 2 modes.
This function returns true ($FF) if a complete frame has been received. This function is useful to see if the communication could be established. If communication times out, the function returns false (0). Either way, this function returns immediately.
This function clears the handler's lock flag that is set at the end of each frame. If the application clears the lock flag, it can wait for the lock bit to be set again via a call to C3_CommunicationLocked(). This way the application can know when a new frame has arrived and still be able to use the time waiting for the current frame for something useful.
This function can be used to check if there is still data coming in. If there has been no data for some time, the function returns 0, otherwise it returns $FF.
This function initializes the UART (UART = Universal Async Receive Transmit) handler. It is passed a pointer to a RAM buffer to capture a frame to and the size of the buffer. This is the maximum number of bytes the handler will accept in a frame. Usually the number of bytes in a frame is 68 or less (it's 67 on the Fiero). Only frames starting with the module ID byte are accepted.
The data in the buffer will continuously be updated while data is being received. If the connection is interrupted, the previous contents will remain in the buffer.
Exits the UART-handler and frees all buffers and internal variables again. Must be called before switching to C3- or Class 2 modes. Note: this resets the baudrate back to default 9600 Baud!
This function returns true ($FF) if a complete frame has been received. This function is useful to see if the communication could be established. If communication times out, the function returns false (0). Either way, this function returns immediately.
This function clears the handler's lock flag that is set at the end of each frame. If the application clears the lock flag, it can wait for the lock bit to be set again via a call to C3_CommunicationLocked(). This way the application can know when a new frame has arrived and still be able to use the time waiting for the current frame for something useful.
This function can be used to check if there is still data coming in. If there has been no data for some time, the function returns 0, otherwise it returns $FF.
This function is used to transmit a message on the UART bus. Some ECMs only transmit diagnostic information if commanded to do so by a message frame.
The function is passed a pointer to a message, with the first byte containing the length of the message (in bytes) followed by the message itself. The function does not perform any checks to see if the bus is busy.
Note: This function works regardless of whether or not the UART mode is active. In other words, if you're not using the UART mode, you can use this function to transmit data on the serial output at the default 9600 Baud, with 8N1, or you can also set a different baudrate. This can be useful for debugging purposes for instance. However, you do need to build some interfacing circuitry to electrically connect the UART-Bus to a PC or terminal.
This function is used to set the baudrate for the UART. The following baudrates are currently supported:
| Value | Baudrate |
| 0 | 8192 |
| 1 | 300 |
| 2 | 600 |
| 3 | 1200 |
| 4 | 2400 |
| 5 | 4800 |
| 6 | 7200 |
| 7 | 8192 |
| 8 | 9600 |
| 9 | 19200 |
This function initializes the J1850 (Class 2) handler / Data Link Controller (DLC). It is passed a pointer to a RAM buffer for received messages and the size of the buffer. The buffer size should be at least 22 bytes, which are used internally by the handler to store a message until it is unloaded by the DLC_UnloadMessage function.
An internal flag is set if a message has arrived in the buffer. This flag can be queried with the DLC_Rx_Ready() function.
Returns 0 if the J1850 bus is idle, $FF otherwise.
Returns 0 if the DLC is ready to accept another message, nonzero otherwise. The return value contains the fill status of the DLC transmit FIFO:
| Value | Buffer status |
| 0 | Buffer empty |
| 1 | Buffer not empty |
| 2 | Buffer almost full |
| 3 | Buffer full |
Transmits a J1850 message on the bus. msgptr points to a buffer containing the message to be transmitted, with the first byte in the buffer being the length of the message.
The mode determines how the message should be transmitted. If bit 0 is cleared, the message is sent to the DLC and remains there until the DLC can transmit it on the bus. The function returns immediately after the message has been sent to the DLC.
If bit 0 is set, the function returns only after the message has been transmitted on the J1850 bus.
Bit 1 controls the behavior of the function concerning the message previously queued in the DLC. If Bit 1 is set, the previous message in the DLC is cleared/aborted if it has not been sent yet. If Bit 1 is clear, the function waits for the DLC to be ready before the message is transferred to the DLC.
This function reads the status of the internal message buffer. Bit 0 is set if there is a message in the buffer.
Bit 1 is set if a message was lost because a second message was received before the buffer was emptied. This overflow bit is automatically reset when DLC_Unload_Msg() is called.
The remaining bits are reserved for future use and should be masked.
This function is called to remove a message from the internal buffer. Also the internal message-in-buffer and overflow flags are reset and the buffer is marked as ready for another message.
Used to filter received messages from the bus. If message filtering is off, all messages seen on the bus, including those sent by the DLC itself, will be read by the DLC and appear in the receive buffer. With filtering on, only those messages appear in the buffer that are of interest to the application. The filtering options are tailored to GM messages with three byte headers and no In-Frame response. If other filtering is required, it must be done in the application code.
The first parameter is a bit coded parameter that controls the filtering. The default is zero, which allows all messages to get through. If one or several bits are set, the conditions are ORed, which means that a message is discarded if it meets any of the criteria required.
The second parameter is the module ID of the scantool (Usually in the range of $F0-$FD), the third parameter is the module ID of the peer for some filtering options. Generally, bits 1, 5 and 7 should be set to ensure a valid GM header and suppress echoes of messages we sent ourself (echoes).
For physical messages, it usually makes sense to turn on bits 1 through 3 to only see messages addressed to our module from the peer we're communicating with. For functional messages, bit 6 is usually set in conjunction with the module source ID we're interested in.
| Bit set | |
| Bit 0 | Discard all physical messages |
| Bit 1 | Discard physical messages with source ID = our ID (discard our physical echoes) |
| Bit 2 | Discard physical messages with target ID not equal our ID (Broadcast messages are allowed through) |
| Bit 3 | Discard physical messages with source ID not equal peer ID |
| Bit 4 | Discard all functional messages |
| Bit 5 | Discard all functional messages with source ID = our ID (discard our functional echoes) |
| Bit 6 | Discard all functional messages with source ID not equal peer ID |
| Bit 7 | Check for GM-Header byte (H=0, K=1) |
Exits the J1850-handler and frees all buffers and internal variables again. Must be called before switching to UART- or C3-modes.
Low level function for direct communication with the DLC. The data in ACC is transferred into the DLC's tx data register, the data in R0 is put into the command register. Upon return, ACC contains the rx data register, and R0 contains the status register.
It is usually not necessary to access this function directly, because the basic J1850 functionality is provided be the other DLC functions.
This function prints a value on the display at the current cursor position. Address must be the address in internal RAM containing the data to be displayed. Type describes how the data should be interpreted and displayed. The following table lists all currently supported data types.
| Type | Name | Range | Description |
| 0 | Dec | 0/255 | One byte is output in decimal |
| 1 | Hex | 0/FF | One byte is output in hex |
| 2 | Mul002 | 0/5.1 | One byte, multiplied by 0.02, it output in decimal |
| 3 | Mul01 | 0/25.5 | One byte, multiplied 0.1, is output in decimal |
| 4 | Percent | 0/100.0 | One byte is scaled to a range of 0-100% |
| 5 | Mul25 | 0/6375 | One byte is multiplied by 25 and output in decimal |
| 6 | Cool | -40/150 | One byte is converted to a temperature (degrees Celsius) |
| 7 | Mat | -63/159 | One byte is converted to a temperature (degrees Celsius) |
| 8 | Angle45 | 0/45.0 | One byte is scaled to an angle of 0-45 degrees |
| 9 | Angle90 | 0/90.0 | One byte is scaled to an angle of 0-90 degrees |
| 10 | Oxygen | 0-1.128 | One byte is converted to an O2 sensor voltage |
| 11 | Second | 0-1000.0 | Two bytes are scaled to a range of 0-1000.0ms |
| 12 | Dec16 | 0-65535 | Two bytes are output in decimal (High byte first) |
| 13 | Hex16 | 0/FFFF | Two bytes are output in hex (High byte first) |
| 14 | Baro | 10.0/104.0 | One byte is scaled to a range of 10.0-104.0 kPa |
| 15 | Mul125 | 0/3188 | One byte is multiplied by 12.5 and output in decimal |
This function works exactly like SlotOutput(), but it appends the given string to the output. This is useful for displaying the unit after a value.
This function prints the string "Off" if data is zero, or prints "On" if data is nonzero.
This function prints the string "Open" if data is zero, or prints "Closed" if data is nonzero.
This function prints the string "Lean" if data is zero, or prints "Rich" if data is nonzero.
This function is used to display an item from the current frame. The location is monitored continuously and the display is updated if necessary until the user presses a key.
The function is passed a structure describing the data to be displayed:
struct {
BYTE address; // address of item in internal RAM
BYTE slot; // slot function used to display item
char* prefix; // string displayed before item
char* suffix; // string displayed after item
}
If the 'slot' byte is > 127 (bit 7 set), the lower 7 bits define a binary variable. In this case the bits are defined as follows:
| Bits 0-2 | Bit number in the byte (0-7) |
| Bit 3 | Bit is toggled (inverted) if this bit is set |
| Bits 4-6: | String output |
| 000 | 1=on, 0=off |
| 001 | 1=closed, 0=open |
| 010 | 1=rich, 0=lean |
| 011 | 1=yes, 0=no |
| 1xx | reserved |
This function is a "macro" that does several things. It waits for a new frame, and prints "no data" if nothing has been received for a while. If the user aborts by pressing any key, the function returns zero. If the new data that has arrived can be printed, the function returns $FF.
This function displays a description of a trouble code. It is passed a trouble code number and a pointer to a table describing the trouble codes.
The table describing trouble codes consists of Null separated strings prefixed with the trouble code number. An entry with the trouble code number zero marks the end of the table.
This function is useful whenever a number needs to be converted into one of several corresponding strings.
MOV A,trouble_code MOV DPTR,#TXT_CODE LCALL CODE_TEXT ; TXT_CODE: DB 12,'Code 12: No',13,10,'Distrib. Pulses',0 DB 14,'Code 14: Coolant',13,10,temperature high',0 DB 0 ;End of table
There have been
visitors to this site since May 31, 2000.