Glossary of 'Avise 4.3' I/O Commands

For every command, a "stack comment" added:
(stack before -- stack after),
where the TOS (top of stack) is written righthand. But only the upper stack entries, which are influenced by the command are written.
When a command needs to be followed by a (name)string, this is additionally noted separated by a semicolon.

Note: in the following text, "argument" or "operand" means TOS for postscript operations, "first argument" or "left argument" means NOS, "second argument" or "right argument" means TOS, the same order Forth stack comments are written. The phrases "returned" and "pushed" mean as much as "put on the stack" whereas "popped" means "taken from the stack".

AIN

Resolution of the analog inputs is 10 bit, i.e. lower 10 bits of the result (at some inputs of the ATmega8 bits 0 and 1 are uncertain).
To detect the end of the ADC converion, the ADC converter ready flag is polled. By default, 'Avise' uses the supply voltage as reference of the ADC converter. The analog inputs are initialized by default as HiZ port inputs. Normally they should be kept in this state. But it is possible to use the analog port as a standard digital I/O, too.

CØZ

C1Z

CNTØ

CNT1

ENCØ

ENC1

IACK

TRUE=1 is returned, if slave does acknowledge. FALSE=0 is returnded, when acknowledgement fails. User has to decide how to handle FALSE answer.

IMACK

TRUE=1 is returned, if slave does acknowledge. FALSE=0 is returnded, when acknowledgement fails. User has to decide how to handle FALSE answer.

IP

In contrast to WPORT and WDDR, this is a single line write operation. Comment on port bit coding see RIO.

IRECV

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. Refer to the I2C protocol of the specific device to be read.

ISEND

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 written.

ISTART

The I2C interface is shared with the program EEPROM, which is not necessarily used with Avise4. Because I2C chips have individual device addresses, normally this will not cause conflicts. The I2C bus of 'Avise' operates with 100 kHz clock speed. So it can be used together with all standard I2C equipment, sometimes not at the highest possible speed.

ISTOP

IZ

In contrast to WPORT and WDDR, this is a single line write operation. Comment on port bit coding see RIO.

OH

In contrast to WPORT and WDDR, this is a single line write operation. Comment on port bit coding see RIO.

OL

In contrast to WPORT and WDDR, this is a single line write operation. Comment on port bit coding see RIO.

PWM1

Example:
$2080 PWM1
the same with decimal argument
& 8192 128 + PWM1
or in general, see table below
HiArg LoArg + PWM1

Resolution, setting of base frequency and output waveform are contained in one single argument:
The HiArg sets PWM resolution and base frequency. The LoArg, i.e. the least 10 or 8 bits set the relative part of the high level phase of the output waveform. With 8 bit resolution, high percentage is LoArg/255, with 10 bit resolution, high percentage is LoArg/1023.

The respective PWM output (CPU dependent) is set as output by 'Avise' firmware.
Once the PWM has started, only a new LoArg has to be entered (i.e. HiArg=0).

The argument has to be composed as follows:
4096

Hi Arg (hex)	Hi Arg (dec)	Res(Bit)	Freq(Hz) @8MHz	Freq(Hz) @16MHz	Freq(Hz) @18.43MHz	Lo Arg (hex)	Lo Arg (dec)
1000	8	15686	31373	36141	0..FF	0..255
2000	8192	8	1961	3922	4518	0..FF	0..255
3000	12288	8	245	490	565	0..FF	0..255
4000	16384	8	61	123	141	0..FF	0..255
5000	20480	8	15	31	35	0..FF	0..255
9000	36864	10	3910	7820	9009	0..3FF	0..1023
A000	40960	10	489	978	1126	0..3FF	0..1023
B000	45056	10	61	122	141	0..3FF	0..1023
C000	49152	10	15	30	35	0..3FF	0..1023
D000	53248	10	3.8	7.6	8.8	0..3FF	0..1023

PWM2

Example:
$27F PWM2
the same with decimal argument
& 512 127 + PWM2
or in general, see table below
  HiArg LoArg + PWM2

Setting of base frequency and output waveform are contained in one single argument:
The HiArg sets the PWM base frequency. The LoArg, i.e. the least 8 bits set the relative part of the high level phase of the output waveform. The high percentage is LoArg/255.

The respective PWM output (CPU dependent) is set as output by 'Avise' firmware.
Once the PWM has started, only a new LoArg has to be entered (i.e. HiArg=0).

The argument has to be composed as follows:

Hi Arg (hex)	Hi Arg (dec)	Freq(Hz) @8MHz	Freq(Hz) @16MHz	Freq(Hz) @18.43MHz	Lo Arg (hex)	Lo Arg (dec)
100	256	15686	31373	36141	0..FF	0..255
200	512	1961	3922	4518	0..FF	0..255
300	786	490	980	1129	0..FF	0..255
400	1024	245	490	565	0..FF	0..255
500	1280	122	245	282	0..FF	0..255
600	1536	61	122	141	0..FF	0..255
700	1792	15	30	35	0..FF	0..255

RIO

Port and bit are coded in byte b as follows using hexadecimal numbers: the upper nibble describes the port and may have the hex values B,C,D. (A is allowed for kernel versions with ATmega32 only). The lower nibble describes the I/O number of this port (0 ... 7). This scheme is attractive, because the hex numbers are synonymous with the Atmel data sheet enumeration.
People who prefer working with decimal numbers should use the following equivalents:
Port A, Pin n: use (160 + n) as argument
Port B, Pin n: use (176 + n) as argument
Port C, Pin n: use (192 + n) as argument
Port D, Pin n: use (208 + n) as argument
In contrast to RPIN, this is a single line reading bit operation.

RPIN

The addressed port is specially coded in byte "ABCD": it describes the port name and may have the hex values A,B,C,D. (0x0A is allowed for kernel versions with ATmega32 only). The PINx register readout is returned 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.In contrast to RIO, this is a multiple line reading byte operation.

WAVE

Example:
$ 300 WAVEHI 400 WAVE
the same with decimal argument
& 768 WAVEHI 1024 WAVE

Before starting WAVE, the high phase MUST be set with WAVEHI. When WAVE is already busy, every part can be changed independently. The high phase, however, must not be greater or equal than the total period.

Frequency range is about:
    0.5 Hz to 15.625 kHz (@ 8 MHz CPU clock)
    1.0 Hz to 31.250 kHz (@ 16 MHz CPU clock)
    1.1 Hz to 36.000 kHz (@ 18.432 MHz CPU clock)

The WAVE period can be changed in units of time (per increment/decrement of argument):
    in units of about 32 microseconds (@ 8MHz clock)
    in units of about 16 microseconds (@ 16MHz clock)
    in units of about 13.89 microseconds (@ 18,432MHz clock)

Port OC1A (CPU depdendent) is set as output by 'Avise' firmware.

WAVEHI

WDDR

In contrast to IP,IZ,OP and OL, this is a multiple line write operation. The addressed port is specially coded in byte "ABCD": it describes the port name and may have the hex values A,B,C,D. (A is allowed for kernel versions with ATmega32 only). 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

Comment see at WDDR