Token Code Index
Glossary of general commands


Glossary of 'Avise 2.4' I/O commands:
(updated 22 Apr 2002)

In the versions for the AT90S4433 some functions are missing due to lack of code memory. Enter WORDS to get a list of functions of your specific version. Differences between different hardware versions are outlined where necessary

+W

(x addr -- )    token code = A6 (not available for AT90S4433 with external EEPROM)

Adds the second stack entry "x" directly to the value of SRAM cell located at "addr" (must be within SRAM addresses <= 0xFF), i.e. specially intended for manipulation of 'Avise' global variables
Performs integer addition 16 bit without carry
Circular overflow, i.e. appropriate for signed as unsigned numbers.


-W

( x addr -- )    token code = A9 (not available for AT90S4433 with external EEPROM)

subtracts the second stack entry "x" directly from the value of SRAM cell located at "addr" (must be within SRAM addresses <= 0xFF), i.e. specially intended for manipulation of 'Avise' global variables

Performs integer subraction 16 bit without carry.
Circular overflow, i.e. appropriate for signed as unsigned numbers.


AIN

( bsel -- x )    token code = 8C(only for CPU models with built-in ADC)

Start one single measurement of the AT90LS4433, AT90S8535 or ATmega163 internal ADC converter, multiplexer input "bsel" selected.
Result is lower 10 bits of TOS.
Polling of the ADC converter ready state is used. By default, 'Avise' uses the supply voltage as reference of the ADC converter. After conversion, the ADC is switched off to save engery. The respective input should be initialized before by the user as HiZ port input.


BCLR

( addr b -- )    token code = 83

Clear bit (set to 0=L) at position "b" (0...15) of SRAM byte at address "addr".
According to the AVR memory model, this can be a controller register, controller SRAM ( addresses <= 0xFF) or an I/O register. A read-modify-write operation is performed, which may give unwanted results at certain I/O registers .


BSET

( addr b -- )    token code = 82

Set bit (set to 1=H) at position "b" (0...15) of SRAM byte at address "addr".
According to the AVR memory model, this can be a controller register, controller SRAM (addresses <= 0xFF) or an I/O register. A read-modify-write operation is performed, which may give unwanted resultsat certain I/O registers.


BTST

( addr b -- TRUE|FALSE )    token code = 84

Test bit at position "b" (0...15) of SRAM byte at address "addr". TRUE is reported, if bit is set (=1, high), FALSE else
According to the AVR memory model, this can be a controller register, controller SRAM (addresses <= 0xFF) or an I/O register.


COUNT

( -- x )    token code = 91 (not available for AT90S4433)

The negative pulses on the INT1 input (PortD,3 for AT90S8515 and AT90S8535) are permanently counted in a background process. COUNT reports the present value of this counter. Circular overflow behaviour. See also ENCODE


ENCODE

( -- x )    token code = 92 (not available for AT90S4433)

Similar function as COUNT, but a counter is incremented or decremented depending on the present level of a second input PortD,4 (AT90S8515) respectively PortD,6 (AT90S8535). Circular overflow behaviour. This function is useful together with 2-phase rotary encoders. When used with mechanical encoders, these must be debounced with appropriate external hardware!


IACK

( -- TRUE|FALSE )    token code = E1

Sends the I2C ACKNOWLEDGE command on the I2C interface. Success is reported as a boolean flag on the stack. User has to decide how to handle FALSE answer.


IRECV

( -- b )    token code = E2 (not available for AT90S4433)

Receives one byte through the I2C interface performing the "current read" method without ACK. Note that this is a receive primitive. According to the I2C protocol, further commands have to be executed previously to ensure correct read address; and further commands may have to be hooked after to close the interface correctly.


ISEND

( b -- )    token code = E3 (not available for AT90S4433)

Sends one byte via the I2C interface without ACK. Note that this is a send primitive. To perform a real write operation to the I2C interface, a sequence of further commands is necessary. Refer to the I2C protocol of the specific device to be connected.


ISPEED

( TRUE|FALSE -- )    token code = DE (not available for AT90S4433)

Adjust the I2C bus clock speed: TRUE does set it to 400 kHz speed (or maximum possible); FALSE does limit it to 100 kHz speed.


ISTART

( -- )    token code = DF (not available for AT90S4433)

Sends the I2C START command on the I2C interface.
The interface is shared with the program EEPROM. Because I2C chips have individual device addresses, this will not cause conflicts. Any overload, hardware or wiring error caused by the user may block the operation of the 'Avise' kernel.


ISTOP

( -- )    token code = E0 (not available for AT90S4433)

Sends the I2C STOP command on the I2C interface.


PBRD

( b -- TRUE|FALSE )    token code = 88

"Pin Bit ReaD". Reads one byte from the specified microcontroller I/O port (PINx register) tests the questionned bit and puts the result conditionned as a boolean flag on the data stack.
Port and bit are coded in byte b as follows: the upper nibble describes the port and may have the hex values B,C,D. (A is allowed for kernel modifications with AT90S8515, AT90S8535 or ATmega. E is allowed for ATmega161. The lower nibble describes the I/O number of this port (0 ... 7).
Example: B1 PBRD


PBHI

( b -- )    token code = 86

"Port Bit HIgh". Sets one bit at the specified microcontroller I/O port (PORTx register, DDRx register) to INPUT with PullUp resistor ("SOFT HIGH"). Comment on port bit coding see PBRD.


PBLO

( b -- )    token code = 87

"Port Bit LOw". Sets one bit at the specified microcontroller I/O port (PORTx register, DDRx register) to OUTPUT LOW. Comment on port bit coding see PBRD.


PWM8

( bhi bmod-- )    token code = 95

Start AVR timer 1 or 2 in 8 bit PWM mode.
Addressing of the timer and prescaler setting is contained in bmod: The high nibble of bmod can be 0, A or B. 0 means Timer2 (when available by hardware). The low nibble of bmod is transferred into the TCCR1B or TCCR2 register, i.e. sets the prescaler. In general, for D/A conversion or automotive contol, bmod should be 1, A1(hex) or B1(hex). Higher prescaler values are recommended to contol RC servo actuators. The ratio (bhi/256) gives the percentage of high phase. The respective PWM output (CPU dependent) is set as output by 'Avise' firmware.
PWM8 or PWM10 cannot be activated at the same time as WAVE. Each of these commands will cancel the operation of the previously given one.


PWM10

(xhi bmod -- )    token code = 96 (not available for AT90S4433)

Start the AVR timer 1 in 10 bit PWM mode.
Addressing of the timer and prescaler setting is contained in bmod: The high nibble of bmod can be A or B. The low nibble of bmod is transferred into the TCCR1B register, i.e. sets the prescaler. The ratio (xhi/65636) gives the percentage of high phase. The respective PWM output (CPU dependent) is set as output by 'Avise' firmware.
PWM8 or PWM10 cannot be activated at the same time as WAVE. Each of these commands will cancel the operation of the previously given one.


R

( addr -- x )    token code = 80

Reads one data word from the microcontroller SRAM memory space to the data stack. According to the AVR memory model, this can be a controller register, controller SRAM (address <=0xFF) or an I/O register.
Byte from "addr" is loaded to TOSL, byte from "addr+1" is loaded to TOSH. If "addr" < 0x60, then only TOSL is read from "addr" and TOSH is set = 0.


RPIN

( addr -- b )    token code = 8B

Reads one byte from the specified microcontroller I/O port (PINx register) and puts the result on the data stack. In contrast to PBIN, this is a multiple line reading byte operation. The addressed port is specially coded in byte "addr": it describes the port name and may have the hex values 0x0B,0x0C,0x0D. (0x0A is allowed for kernel modifications with AT90S4414, AT90S8515 or AT90S8535). The PINx register readout is returned on the stack without further filtering. Note that not all port lines are physically available and some of the available ones may have special functions, which do not represent user I/O.


W

(x addr -- )    token code = 81

Write one data word from the data stack to the microcontroller SRAM memory space (address <= 0xFF). According to the AVR memory model, this can be a controller register, controller SRAM or an I/O register.
Avise2: byte from TOSL is written to "addr" , byte from TOSH is written to "addr+1". If "addr" < 0x60, only the byte from TOSL is written to "addr", TOSH is ignored.
Attention: most registers and many I/O resources are internally used by 'Avise'. Wrong operation may cause buggy operation of 'Avise'. Hardware reset or INIT command will normally clear this malfunction.


WAVE

( b -- )    token code = 93 (AT90S4433: performs always 50% duty cycle)

Start the AVR timer 1 as frequency generator with a low cycle period defined by WAVELO. Before starting WAVE, the low period MUST be set with WAVELO. When WAVE is already busy, every part can be changed independently. The low period, however, must not be greater or equal than the total period. Frequency range is about 15 Hz to 32 kHz. Frequency is about 62500 kHz/(b+1). 16 bit resolution of frequency control. Port OC1A (CPU depdendent) is set as output by 'Avise' firmware.
As they share resources, WAVE, PWM8 and PWM10 (with Timer1) cannot be activated at the same time.
The Timer1 prescaler register is available to the user. WAVE does activate the Timer1 Output Compare Match interrupt.


WAVELO

( b -- )    token code = 94 (not available for AT90S4433)

Sets the duration of the low period of WAVE in units of about 16 microseconds.


WDDR

( b addr -- )    token code = 8A
Writes one byte "b" into the data direction register of the specified microcontroller I/O port. In contrast to PBHI and PBLO, this is a multiple line write operation. The addressed port is specially coded in byte "addr": it describes the port name and may have the hex values B,C,D. (A is allowed for kernel modifications with AT90S8515, AT90S8535 or ATmega. E is allowed for ATmega161). Note that not all port lines are physically available, and some are locked against user access as there are: serial interface and I2C control lines.


WPORT

( b addr -- )    token code = 89
Writes one byte "b" into the port register of the specified microcontroller I/O port. In contrast to PBHI and PBLO, this is a multiple line write operation. The addressed port is specially coded in byte "addr": it describes the port name and may have the hex values B,C,D. (A is allowed for kernel modifications with AT90S8515, AT90S8535 or ATmega. E is allowed for ATmega161). Note that not all port lines are physically available, and some are locked against user access as there are: serial interface and I2C control lines.


XR

( addr -- b )    token code = EF (not available for AT90S4433 without external EEPROM)
Reads one byte from the external EEPROM (if available) to the data stack (into TOSL and TOSH is set =0). addr is limited by the capacity of the EEPROM.
Note: when EEPROM types 24C64 or 24C128 or equivalent are used, logical addresses of user words (token codes) are transformed into physical EEPROM pages. For a 24C64 EEPROM, token code 0x20 is compiled to physical page address 0x800 and so on. For a 24C128 EEPROM, token code 0x20 is compiled to physical page address 0x1000 and so on. For a 24C256 EEPROM, token code 0x20 is compiled to physical page address 0x2000 and so on. XR always reads from physical addresses as given by the stack.


XW

( b addr -- )    token code = F0 (not available for AT90S4433 without external EEPROM)
Writes one byte from the data stack (TOSL) to the external EEPROM(if available) to the data stack. addr is limited by the capacity of the EEPROM
Note: when EEPROM types 24C64 or 24C128 or equivalent are used, logical addresses of user words (token codes) are transformed into physical EEPROM pages. For a 24C64 EEPROM, token code 0x20 is compiled to physical page address 0x800 and so on. For a 24C128 EEPROM, token code 0x20 is compiled to physical page address 0x1000 and so on. For a 24C256 EEPROM, token code 0x20 is compiled to physical page address 0x2000 and so on. XW always writes to physical addresses as given by the stack. Attention: Writing into program code or symbol table may cause error in the 'Avise' kernel operation.


ZR

( addr -- b )    token code = ED
Reads one byte from the CPU internal EEPROM to the data stack.


ZW

( b addr -- )    token code = EE
Writes one byte from the data stack to the CPU internall EEPROM.
Attention: Should only be used, if no user functions are compiled into this EEPROM.


Abbreviations and notation used in this glossary

Dont be confused by these bureaucratic things. Look at the "programming crashcourse". Start programming by copy and modify.

For each word entry there is a boldface headline, in which the most essential features are concentrated. E.g. an imaginary one:

TEST

( x -- addr ; <namestring> )   token code = 4B

On top, there is the word name in big letters
Below an expression in brackets, called stack comment. The stack comment shows a precise description of all changes of the data stack during call and execution of this word. This information is necessary for succesful programmer's work:

( consumed stack entries -- produced stack entries ) or
( stack before -- stack after )
The upper or youngest stack entry is positionned most right. Deeper stack entries, which are not influenced by this word, are not listed in the stack comment. If you have to do complicated operations, you are advised to solve them writing your own stack comments.
In some cases the token does consume subsequent string tokens. This is shown by an annotation separated from the data stack image by a semicolon. For example, see the colon command.

Following abbreviations are used in the stack commands:

  • C means "COMPILE ONLY". This command can only be compiled, not executed interactively.
  • I means "IMMEDIATE". This word (command, function) is not compiled. Within a word compilation it does temporarily switch ''Avise'' into interpreting state to execute this word. This way, more complex compile operations are performed, especially to build conditional branches and loops.
  • P means "runtime primitive". Cannot be called directly out of user programs; but is implicitely compiled by immediate words to provide their runtime behaviour. (Due to lack of memory, in the AT90A4433 versions the runtime primitives are not listed by WORDS, but they are present in the system as listed in the glossary of general commands.)
  • Last not least, for each word its token code is written as a hexadecimal byte in this informational line. This is less of importance during programming, but can be a great help in difficile debugging operations.

The mnemonics in the stack comment give some hints relating the data type which is effectively handled (though in a technical sense ''Avise'' can only handle bytes on the stack). Longer data are represented by two or more stack entries.
Differing from standard Forth systems, in 'Avise1' for multi byte arguments, the most significant byte is always put first or deeper on the stack ! This makes multi byte arithmetics and its intuitive visual recognition more easy and convenient.
addrL= least significant byte of 16 bit address
addrH= most significant byte of 16 bit address
addr =Avise2:16 bit word address, Avise1:byte address. Higher address part may be zero page or defined by context
x = general data word. For clarity, in some cases specific descriptional characters may be added.
Avise2: data word means 16 bit data. Avise1: data word means 8 bit data (byte).
bL= least significant byte of 16 bit general data word
bH= most significant byte of 16 bit general data word
xL= least significant word of 32 bit general data word
xH= most significant word of 32 bit general data word
b = general data byte. For clarity, in some cases specific descriptional characters may be added.
When used with Avise2: only TOSL is employed in the operation. When a "byte" is taken from the stack,TOSH is ignored. When a "byte" is put on the stack, TOSH is set = 0
TRUE|FALSE = TRUE or FALSE: boolean flag expressed by one byte on the stack.
TRUE = TRUE boolean flag on the stack.TRUE is exactly expressed by the integer number -1 or 0xFFFF. But in practice all values not equal zero are interpreted as TRUE.
FALSE = FALSE boolean flag on the stack. FALSE can only be expressed by integer value Ø (zero).
| separates stack values which occur as alternatives. If necessary, groups of entries which belong together are expressed by spaces
'Avise' does not know formal declarations of data types. Correct interpretation - and in case re-interpretation - lies in the programmer's responsibility.

  • TOS means "Top of Stack" = uppermost stack element
    Avise2: TOSH is most significant byte of TOS, TOSL is least significant byte of TOS
  • NOS means "Next of Stack" = second upper stack entry.


Token Code Index
Glossary of general commands