NQC Programmer's Guide

Version 3.1 r5 by Dave Baum & John Hansen

Contents
1 2 Introduction .............................................................................................................1 The NQC Language.................................................................................................2 2.1 Lexical Rules ...................................................................................................2 Comments ................................................................................................2 Whitespace...............................................................................................3 Numerical Constants ................................................................................3 Identifiers and Keywords..........................................................................3

2.1.1 2.1.2 2.1.3 2.1.4 2.2

Program Structure............................................................................................4 Tasks........................................................................................................4 Functions .................................................................................................5 Subroutines ..............................................................................................8 Variables..................................................................................................9 Arrays ....................................................................................................11

2.2.1 2.2.2 2.2.3 2.2.4 2.2.5 2.3

Statements .....................................................................................................11 Variable Declaration ..............................................................................11 Assignment ............................................................................................12 Control Structures ..................................................................................13 Access Control and Events .....................................................................16 Other Statements ....................................................................................18

2.3.1 2.3.2 2.3.3 2.3.4 2.3.5 2.4

Expressions....................................................................................................18 Conditions..............................................................................................20

2.4.1 2.5

The Preprocessor............................................................................................21 #include .................................................................................................21 Page i

2.5.1

2.5.2 2.5.3 2.5.4 2.5.5 3

#define ...................................................................................................21 Conditional Compilation ........................................................................22 Program Initialization.............................................................................22 Reserving Storage ..................................................................................22

NQC API...............................................................................................................24 3.1 Sensors ..........................................................................................................24 Types and Modes RCX, CM, Spy...........................................................25 Sensor Information.................................................................................27 Scout Light Sensor Scout .......................................................................28 Spybotics Sensors Spy............................................................................29

3.1.1 3.1.2 3.1.3 3.1.4 3.2

Outputs ..........................................................................................................30 Primitive Calls .......................................................................................30 Convenience Calls..................................................................................31 Global Control RCX2, Scout, Spy ..........................................................33 Spybotics Outputs ..................................................................................35

3.2.1 3.2.2 3.2.3 3.2.4 3.3 3.4 3.5

Sound ............................................................................................................35 LCD Display RCX.........................................................................................37 Communication..............................................................................................38 Messages RCX, Scout ............................................................................38 Serial RCX2, Spy...................................................................................40 VLL Scout, Spy......................................................................................49

3.5.1 3.5.2 3.5.3 3.6 3.7 3.8

Timers ...........................................................................................................49 Counters RCX2, Scout, Spy ...........................................................................50 Access Control RCX2, Scout, Spy .................................................................51 Page ii

3.9

Events RCX2, Scout ......................................................................................51 Configurable Events RCX2, Spy ............................................................52 Scout Events Scout.................................................................................57

3.9.1 3.9.2 3.10 3.11 3.12 3.13 3.14 3.15 3.16 4

Data Logging RCX ........................................................................................59 General Features ............................................................................................61 RCX Specific Features...................................................................................63 Scout Specific Features ..................................................................................63 CyberMaster Specific Features.......................................................................64 Spybotics Specific Features............................................................................66 Swan Specific Features ..................................................................................82

Technical Details ...................................................................................................97 4.1 4.2 The asm statement .........................................................................................97 Data Sources..................................................................................................98

Page iii

NQC Programmer's Guide

1 Introduction
NQC stands for Not Quite C, and is a simple language for programming several LEGO MINDSTORMS products. Some of the NQC features depend on which MINDSTORMS product you are using. This product is referred to as the target for NQC. Presently, NQC supports six different targets: RCX, RCX2 (an RCX running 2.0 firmware), CyberMaster, Scout, Spybotics, and Swan (an RCX running Dick Swans enhanced firmware). All of the targets have a bytecode interpreter (provided by LEGO) which can be used to execute programs. The NQC compiler translates a source program into LEGO bytecodes, which can then be executed on the target itself. Although the preprocessor and control structures of NQC are very similar to C, NQC is not a general purpose language - there are many restrictions that stem from limitations of the LEGO bytecode interpreter. Logically, NQC is defined as two separate pieces. The NQC language describes the syntax to be used in writing programs. The NQC API describes the system functions, constants, and macros that can be used by programs. This API is defined in a special file built in to the compiler. By default, this file is always processed before compiling a program. This document describes both the NQC language and the NQC API. In short, it provides the information needed to write NQC programs. Since there are several different interfaces for NQC, this document does not describe how to use any specific NQC implementation. Refer to the documentation provided with the NQC tool, such as the NQC User Manual for information specific to that implementation. For up-to-date information and documentation for NQC, visit the NQC Web Site at http://bricxcc.sourceforge.net/nqc

Page 1

NQC Programmer's Guide

2 The NQC Language

This section describes the NQC language itself. This includes the lexical rules used by the compiler, the structure programs, statements, and expressions, and the operation of the preprocessor.

2.1

Lexical Rules

The lexical rules describe how NQC breaks a source file into individual tokens. This includes the way comments are written, then handling of whitespace, and valid characters for identifiers.

2.1.1Comments
Two forms of comments are supported in NQC. The first form (traditional C comments) begin with /* and end with */. They may span multiple lines, but do not nest:
/* this is a comment */

/* this is a two line comment */

/* another comment... /* trying to nest... ending the inner comment...*/ this text is no longer a comment! */

The second form of comments begins with // and ends with a newline (sometimes known as C++ style comments).
// a single line comment

Comments are ignored by the compiler. Their only purpose is to allow the programmer to document the source code.

Page 2

NQC Programmer's Guide

2.1.2Whitespace
Whitespace (spaces, tabs, and newlines) is used to separate tokens and to make programs more readable. As long as the tokens are distinguishable, adding or subtracting whitespace has no effect on the meaning of a program. For example, the following lines of code both have the same meaning:
x=2; x = 2 ;

Some of the C++ operators consist of multiple characters. In order to preserve these tokens whitespace must not be inserted within them. In the example below, the first line uses a right shift operator ('>>'), but in the second line the added space causes the '>' symbols to be interpreted as two separate tokens and thus generate an error.
x = 1 >> 4; // set x to 1 right shifted by 4 bits x = 1 > > 4; // error

2.1.3Numerical Constants
Numerical constants may be written in either decimal or hexadecimal form. Decimal constants consist of one or more decimal digits. Hexadecimal constants start with 0x or
0X followed by one or more hexadecimal digits. x = 10; // set x to 10 x = 0x10; // set x to 16 (10 hex)

2.1.4Identifiers and Keywords

Identifiers are used for variable, task, function, and subroutine names. The first character of an identifier must be an upper or lower case letter or the underscore ('_'). Remaining characters may be letters, numbers, and an underscore. A number of potential identifiers are reserved for use in the NQC language itself. These reserved words are call keywords and may not be used as identifiers. A complete list of keywords appears below:
__event_src __nolist __res __sensor __taskid __type abs acquire

Page 3

NQC Programmer's Guide

asm break case catch const continue default do else false for goto if inline int monitor repeat return sign start stop sub switch task true void while

2.2

Program Structure

An NQC program is composed of code blocks and global variables. There are three distinct types of code blocks: tasks, inline functions, and subroutines. Each type of code block has its own unique features and restrictions, but they all share a common structure.

2.2.1Tasks
The RCX implicitly supports multi-tasking, thus an NQC task directly corresponds to an RCX task. Tasks are defined using the task keyword using the following syntax:
task name() { // the task's code is placed here }

The name of the task may be any legal identifier. A program must always have at least one task - named "main" - which is started whenever the program is run. The maximum number of tasks depends on the target - the RCX supports 10 tasks, CyberMaster supports 4, Scout supports 6, and Spybotics supports 8. The body of a task consists of a list of statements. Tasks may be started and stopped using the start and stop statements (described in the section titled Statements). There is also a NQC API command, StopAllTasks, which stops all currently running tasks.

Page 4

NQC Programmer's Guide

2.2.2Functions
It is often helpful to group a set of statements together into a single function, which can then be called as needed. NQC supports functions with arguments, but not return values. Functions are defined using the following syntax:
void name(argument_list) { // body of the function }

The keyword void is an artifact of NQC's heritage - in C functions are specified with the type of data they return. Functions that do not return data are specified to return void. Returning data is not supported in NQC, thus all functions are declared using the void keyword. The argument list may be empty, or may contain one or more argument definitions. An argument is defined by its type followed by its name. Multiple arguments are separated by commas. All values are represented as 16 bit signed integers. However NQC supports six different argument types which correspond to different argument passing semantics and restrictions:
Type int const int int & const int & int* const int * Meaning pass by value pass by value pass by reference pass by reference pass pointer pass pointer Restriction none only constants may be used only variables may be used function cannot modify argument only pointers may be used function cannot modify pointer argument

Arguments of type int are passed by value from the calling function to the callee. This usually means that the compiler must allocate a temporary variable to hold the argument. There are no restrictions on the type of value that may be used. However, since the function is working with a copy of the actual argument, any changes it makes to the value will not be seen by the caller. In the example below, the function foo attempts to set the value of its argument to 2. This is perfectly legal, but since foo is working on a copy of the original argument, the variable y from main task remains unchanged. Page 5

NQC Programmer's Guide

void foo(int x) { x = 2; } task main() { int y = 1; // y is now equal to 1 foo(y); // y is still equal to 1! }

The second type of argument, const int, is also passed by value, but with the restriction that only constant values (e.g. numbers) may be used. This is rather important since there are a number of RCX functions that only work with constant arguments.
void foo(const int x) { PlaySound(x); // ok x = 1; // error - cannot modify argument } task main() { foo(2); foo(4*5); foo(x); }

// ok // ok - expression is still constant // error - x is not a constant

The third type, int &, passes arguments by reference rather than by value. This allows the callee to modify the value and have those changes visible in the caller. However, only variables may be used when calling a function using int & arguments:
void foo(int &x) { x = 2; } task main() { int y = 1; // y is equal to 1 foo(y); foo(2); } // y is now equal to 2 // error - only variables allowed

The fourth type, const int &, is rather unusual. It is also passed by reference, but with the restriction that the callee is not allowed to modify the value. Because of this restriction, the compiler is able to pass anything (not just variables) to functions using Page 6

NQC Programmer's Guide this type of argument. In general this is the most efficient way to pass arguments in NQC. There is one important difference between int arguments and const int & arguments. An int argument is passed by value, so in the case of a dynamic expression (such as a sensor reading), the value is read once then saved. With const int & arguments, the expression will be re-read each time it is used in the function:
void foo(int x) { if (x==x) // this will always be true PlaySound(SOUND_CLICK); } void bar(const int &x) { if (x==x) // may not be true..value could change PlaySound(SOUND_CLICK); } task main() { foo(SENSOR_1); bar(2); bar(SENSOR_1); }

// will play sound // will play sound // may not play sound

The last two types, int * and const int *, pass pointer arguments. Proper usage of pointer arguments requires that they be de-referenced.
void foo(int * p) { *p = 4; } task main() { int x = 2; int* y = &x; // y contains the address of x foo(y); // x = 4 }

Functions must be invoked with the correct number (and type) of arguments. The example below shows several different legal and illegal calls to function foo:
void foo(int bar, const int baz) {

Page 7

NQC Programmer's Guide

// do something here... } task main() { int x; foo(1, 2); foo(x, 2); foo(2, x); foo(2); }

// declare variable x // // // // ok ok error - 2nd argument not constant! error - wrong number of arguments!

NQC functions are always expanded as inline functions. This means that each call to a function results in another copy of the function's code being included in the program. Unless used judiciously, inline functions can lead to excessive code size.

2.2.3Subroutines
Unlike inline functions, subroutines allow a single copy of some code to be shared between several different callers. This makes subroutines much more space efficient than inline functions, but due to some limitations in the LEGO bytecode interpreter, subroutines have some significant restrictions. First of all, subroutines cannot use any arguments. Second, a subroutine cannot call another subroutine. Last, the maximum number of subroutines is limited to 8 for the RCX, 4 for CyberMaster, 3 for Scout, and 32 for Spybotics. In addition, when using RCX 1.0 or CyberMaster, if the subroutine is called from multiple tasks then it cannot have any local variables or perform calculations that require temporary variables. These significant restrictions make subroutines less desirable than functions; therefore their use should be minimized to those situations where the resultant savings in code size is absolutely necessary. The syntax for a subroutine appears below:
sub name() { // body of subroutine }

Page 8

NQC Programmer's Guide

2.2.4Variables
All variables in NQC are of one of two types - specifically 16 bit signed integers or pointers to 16 bit signed integers. Variables are declared using the int keyword followed by a comma separated list of variable names (each with an optional '*' pointer indicator in front of the name) and terminated by a semicolon (';'). Optionally, an initial value for each variable may be specified using an equals sign ('=') after the variable name. Several examples appear below:
int int int int x; y,z; *q, *p a=1,b; // declare x // declare y and z = &x; // declare ptrs q and p, p = address of x // declare a and b, initialize a to 1

Global variables are declared at the program scope (outside any code block). Once declared, they may be used within all tasks, functions, and subroutines. Their scope begins at declaration and ends at the end of the program. Local variables may be declared within tasks, functions, and sometimes within subroutines. Such variables are only accessible within the code block in which they are defined. Specifically, their scope begins with their declaration and ends at the end of their code block. In the case of local variables, a compound statement (a group of statements bracketed by { and }) is considered a block:
int x; // x is global

task main() { int y; // y is local to task main x = y; // ok { // begin compound statement int z; // local z declared y = z; // ok } y = z; // error - z no longer in scope } task foo() { x = 1; // ok y = 2; // error - y is not global }

Page 9

NQC Programmer's Guide In many cases NQC must allocate one or more temporary variables for its own use. In some cases a temporary variable is used to hold an intermediate value during a calculation. In other cases it is used to hold a value as it is passed to a function. These temporary variables deplete the pool of variables available to the rest of the program. NQC attempts to be as efficient as possible with temporary variables (including reusing them when possible). The RCX (and other targets) provide a number of storage locations which can be used to hold variables in an NQC program. There are two kinds of storage locations - global and local. When compiling a program, NQC assigns each variable to a specific storage location. Programmers for the most part can ignore the details of this assignment by following two basic rules: If a variable needs to be in a global location, declare it as a global variable. If a variable does not need to be a global variable, make it as local as possible. This gives the compiler the most flexibility in assigning an actual storage location. The number of global and local locations varies by target Target RCX (1.0) CyberMaster Scout RCX2 Swan Spybotics Global 32 32 10 32 32 32 Local 0 0 8 16 16 4

Page 10

NQC Programmer's Guide

2.2.5Arrays
The RCX2, Swan, and Spybotics targets support arrays (the other targets do not have suitable support in firmware for arrays). Arrays are declared the same way as ordinary variables, but with the size of the array enclosed in brackets. The size must be a constant.
int my_array[3]; // declare an array with three elements

The elements of an array are identified by their position within the array (called an index). The first element has an index of 0, the second has index 1, etc. For example:
my_array[0] = 123; // set first element to 123 my_array[1] = my_array[2]; // copy third into second

Currently there are a number of limitations on how arrays can be used. These limitations will likely be removed in future versions of NQC: An array cannot be an argument to a function. An individual array element, however, can be passed to a function. Neither arrays nor their elements can be used with the increment (++) or decrement (--) operators. The initial values for an array's elements cannot be specified - an explicit assignment is required within the program itself to set the value of an element.

2.3

Statements

The body of a code block (task, function, or subroutine) is composed of statements. Statements are terminated with a semi-colon (';').

2.3.1Variable Declaration
Variable declaration, as described in the previous section, is one type of statement. It declares a local variable (with optional initialization) for use within the code block. The syntax for a variable declaration is:
int variables;

Page 11

NQC Programmer's Guide where variables is a comma separated list of names with optional initial values and an optional pointer indicator:
[*]name[=expression]

Arrays of variables may also be declared (for the RCX2, Swan, and Spybotics only):
int array[size];

2.3.2Assignment
Once declared, variables may be assigned the value of an expression:
variable assign_operator expression;

There are nine different assignment operators. The most basic operator, '=', simply assigns the value of the expression to the variable. The other operators modify the variable's value in some other way as shown in the table below
Operator = += -= *= /= %= &= |= ^= ||= +-= >>= <<= Action Set variable to expression Add expression to variable Subtract expression from variable Multiple variable by expression Divide variable by expression Set variable to remainder after dividing by expression Bitwise AND expression into variable Bitwise OR expression into variable Bitwise exclusive OR into variable Set variable to absolute value of expression Set variable to sign (-1,+1,0) of expression Right shift variable by a constant amount Left shift variable by a constant amount

Some examples:
x = 2; y = 7; x += y; // set x to 2 // set y to 7 // x is 9, y is still 7

Page 12

NQC Programmer's Guide

2.3.3Control Structures
The simplest control structure is a compound statement. This is a list of statements enclosed within curly braces ('{' and '}'):
{ x = 1; y = 2; }

Although this may not seem very significant, it plays a crucial role in building more complicated control structures. Many control structures expect a single statement as their body. By using a compound statement, the same control structure can be used to control multiple statements. The if statement evaluates a condition. If the condition is true it executes one statement (the consequence). An optional second statement (the alternative) is executed if the condition is false. The two syntaxes for an if statement is shown below.
if (condition) consequence if (condition) consequence else alternative

Note that the condition is enclosed in parentheses. Examples are shown below. Note how a compound statement is used in the last example to allow two statements to be executed as the consequence of the condition.
if (x==1) y = 2; if (x==1) y = 3; else y = 4; if (x==1) { y = 1; z = 2; }

The while statement is used to construct a conditional loop. The condition is evaluated, and if true the body of the loop is executed, then the condition is tested again. This process continues until the condition becomes false (or a break statement is executed). The syntax for a while loop appears below:
while (condition) body

It is very common to use a compound statement as the body of a loop:

while(x < 10) { x = x+1; y = y*2; }

Page 13

NQC Programmer's Guide A variant of the while loop is the do-while loop. Its syntax is:
do body while (condition)

The difference between a while loop and a do-while loop is that the do-while loop always executes the body at least once, whereas the while loop may not execute it at all. Another kind of loop is the for loop:
for(stmt1 ; condition ; stmt2) body

A for loop always executes stmt1, then it repeatedly checks the condition and while it remains true executes the body followed by stmt2. The for loop is equivalent to:
stmt1; while(condition) { body stmt2; }

The repeat statement executes a loop a specified number of times:

repeat (expression) body

The expression determines how many times the body will be executed. Note that it is only evaluated a single time, then the body is repeated that number of times. This is different from both the while and do-while loops which evaluate their condition each time through the loop. A switch statement can be used to execute one of several different blocks of code depending on the value of an expression. Each block of code is preceded by one or more
case labels. Each case must be a constant and unique within the switch statement. The

switch statement evaluates the expression then looks for a matching case label. It will then execute any statements following the matching case until either a break statement or the end of the switch is reaches. A single default label may also be used - it will match any value not already appearing in a case label. Technically, a switch statement has the following syntax:
switch (expression) body

The case and default labels are not statements in themselves - they are labels that precede statements. Multiple labels can precede the same statement. These labels have the following syntax Page 14

NQC Programmer's Guide

case constant_expression : default :

A typical switch statement might look like this:

switch(x) { case 1: // do something when X is 1 break; case 2: case 3: // do something else when x is 2 or 3 break; default: // do this when x is not 1, 2, or 3 break; }

The goto statement forces a program to jump to the specified location. Statements in a program can be labeled by preceding them with an identifier and a colon. A goto statement then specifies the label which the program should jump to. For example, this is how an infinite loop that increments a variable could be implemented using goto:
my_loop: x++; goto my_loop;

The goto statement should be used sparingly and cautiously. In almost every case, control structures such as if, while, and switch make a program much more readable and maintainable than using goto. Care should be taken to never use a goto to jump into or out of a monitor or acquire statement. This is because monitor and
acquire have special code that normally gets executed upon entry and exit, and a goto

will bypass that code probably resulting in undesirable behavior. NQC also defines the until macro which provides a convenient alternative to the
while loop. The actual definition of until is: #define until(c) while(!(c))

In other words, until will continue looping until the condition becomes true. It is most often used in conjunction with an empty body statement:
until(SENSOR_1 == 1); // wait for sensor to be pressed

Page 15

NQC Programmer's Guide

2.3.4Access Control and Events

The Scout, RCX2, Swan, and Spybotics support access control and event monitoring. Access control allows a task to request ownership of one or more resources. In NQC, access control is provided by the acquire statement, which has two forms:
acquire ( resources ) body acquire ( resources ) body catch handler

where resources is a constant that specifies the resources to be acquired and body and handler are statements. The NQC API defines constants for individual resources which may be added together to request multiple resources at the same time. The behavior of the acquire statement is as follows: Ownership of the specified resources will be requested. If another task of higher priority already owns the resources, then the request will fail and execution will jump to the handler (if present). Otherwise, the request will succeed, and the body will begin to be executed. While executing the body, if another task of equal or higher priority requests any of the owned resources, then the original task will lose ownership. When ownership is lost, execution will jump to the handler (if present). Once the body has completed, the resources will be returned back to the system (so that lower priority tasks may acquire them), and execution will continue with the statement following the acquire statement. If a handler is not specified, then in both the case of a failed request, or a subsequent loss of ownership, control will pass to the statement following the acquire statement. For example, the following code acquires a resource for 10 seconds, playing a sound if it cannot complete successfully:
acquire(ACQUIRE_OUT_A) { Wait(1000); } catch { PlaySound(SOUND_UP); }

Event monitoring is implemented with the monitor statement, which has a syntax very similar to acquire:
monitor ( events ) body monitor ( events ) body handler_list

Page 16

NQC Programmer's Guide Where handler_list is one or more handlers of the form
catch ( catch_events ) handler

The last handler in a handler list can omit the event specification:
catch handler

Events is a constant that determines which events should be monitored. For the Scout, events are predefined, so there are constants such as EVENT_1_PRESSED which can be used to specify events. With RCX2, Swan, and Spybotics, the meaning of each event is configured by the programmer. There are 16 events (numbers 0 to 15). In order to specify an event in a monitor statement, the event number must be converted to an event mask using the EVENT_MASK() macro. The Scout event constants or event masks may be added together to specify multiple events. Multiple masks can be combined using bitwise OR. The monitor statement will execute the body while monitoring the specified events. If any of the events occur, execution will jump to the first handler for that event (a handler without an event specification handles any event). If no event handler exists for the event, then control will continue at the statement following the monitor statement. The following example waits for 10 seconds while monitoring events 2, 3, and 4 for RCX2:
monitor( EVENT_MASK(2) | EVENT_MASK(3) | EVENT_MASK(4) ) { Wait(1000); } catch ( EVENT_MASK(4) ) { PlaySound(SOUND_DOWN); // event 4 happened } catch { PlaySound(SOUND_UP); // event 2 or 3 happened }

Note that the acquire and monitor statements are only supported for targets that implement access control and event monitoring - specifically the Scout, RCX2, Swan, and Spybotics.

Page 17

NQC Programmer's Guide

2.3.5Other Statements
A function (or subroutine) call is a statement of the form:
name(arguments);

The arguments list is a comma separated list of expressions. The number and type of arguments supplied must match the definition of the function itself. Tasks may be started or stopped with the following statements:
start task_name; stop task_name;

Within loops (such as a while loop) the break statement can be used to exit the loop and the continue statement can be used to skip to the top of the next iteration of the loop. The break statement can also be used to exit a switch statement.
break; continue;

It is possible to cause a function to return before it reaches the end of its code using the
return statement. return;

Any expression is also a legal statement when terminated by a semicolon. It is rare to use such a statement since the value of the expression would then be discarded. The one notable exception is expressions involving the increment (++) or decrement (--) operators.
x++;

The empty statement (just a bare semicolon) is also a legal statement.

2.4

Expressions

Earlier versions of NQC made a distinction between expressions and conditions. As of version 2.3, this distinction was eliminated: everything is an expression, and there are now conditional operators for expressions. This is similar to how C/C++ treats conditional operations.

Page 18

NQC Programmer's Guide Values are the most primitive type of expressions. More complicated expressions are formed from values using various operators. The NQC language only has two built in kinds of values: numerical constants and variables. The RCX API defines other values corresponding to various RCX features such as sensors and timers. Numerical constants in the RCX are represented as 16 bit signed integers. NQC internally uses 32 bit signed math for constant expression evaluation, then reduces to 16 bits when generating RCX code. Numeric constants can be written as either decimal (e.g.
123) or hexadecimal (e.g. 0xABC). Presently, there is very little range checking on

constants, so using a value larger than expected may have unusual effects. Two special values are predefined: true and false. The value of false is zero, while the value of true is only guaranteed to be non-zero. The same values hold for relational operators (e.g. <): when the relation is false, the value is 0, otherwise the value is nonzero. Values may be combined using operators. Several of the operators may only be used in evaluating constant expressions, which means that their operands must either be constants, or expressions involving nothing but constants. The operators are listed here in order of precedence (highest to lowest).
Operator abs() sign() ++, -~ ! *, /, % Description Absolute value Sign of operand Increment, decrement Unary minus Bitwise negation (unary) Logical negation Multiplication, division, modulo +, <<, >> Addition, subtraction Left and right shift left left shift amount must constant x+y x << 4 Associativity n/a n/a left right right right left constant only variables only Restriction Example abs(x) sign(x) x++ or ++x -x ~123 !x x*y

Page 19

NQC Programmer's Guide

<, >, <=, >= ==, != & ^ | && || ?: equal to, not equal to Bitwise AND Bitwise XOR Bitwise OR Logical AND Logical OR conditional value left left left left left left n/a x == 1 x&y x^ y x|y x && y x || y x==1 ? y : z relational operators left x<y

Where needed, parentheses may be used to change the order of evaluation:

x = 2 + 3 * 4; // set x to 14 y = (2 + 3) * 4; // set y to 20

2.4.1Conditions
Conditions are generally formed by comparing two expressions. There are also two constant conditions - true and false - which always evaluate to true or false respectively. A condition may be negated with the negation operator, or two conditions combined with the AND and OR operators. The table below summarizes the different types of conditions. Condition
True False Expr expr1 == expr2 expr1 != expr2 expr1 < expr2 expr1 <= expr2

Meaning
always true always false true if expr is not equal to 0 true if expr1 equals expr2 true if expr1 is not equal to expr2 true if one expr1 is less than expr2 true if expr1 is less than or equal to expr2

Page 20

NQC Programmer's Guide

expr1 > expr2 expr1 >= expr2 ! condition cond1 && cond2

true if expr1 is greater than expr2 true if expr1 is greater than or equal to expr2 logical negation of a condition - true if condition is false logical AND of two conditions (true if and only if both conditions are true)

cond1 || cond2

logical OR of two conditions (true if and only if at least one of the conditions are true)

2.5

The Preprocessor

The preprocessor implements the following directives: #include, #define, #ifdef,

#ifndef, #if, #elif, #else, #endif, #undef. Its implementation is fairly close to a

standard C preprocessor, so most things that work in a generic C preprocessor should have the expected effect in NQC. Significant deviations are listed below.

2.5.1#include
The #include command works as expected, with the caveat that the filename must be enclosed in double quotes. There is no notion of a system include path, so enclosing a filename in angle brackets is forbidden. #include "foo.nqh" // ok #include <foo.nqh> // error!

2.5.2#define
The #define command is used for simple macro substitution. Redefinition of a macro is an error (unlike in C where it is a warning). Macros are normally terminated by the end of the line, but the newline may be escaped with the backslash ('\') to allow multiline macros:
#define foo(x) do { bar(x); \ baz(x); } while(false)

Page 21

NQC Programmer's Guide The #undef directive may be used to remove a macros definition.

2.5.3Conditional Compilation
Conditional compilation works similar to the C preprocessor. The following preprocessor directives may be used:
#if condition #ifdef symbol #ifndef symbol #else #elif condition #endif

Conditions in #if directives use the same operators and precedence as in C. The
defined() operator is supported.

2.5.4Program Initialization
The compiler will insert a call to a special initialization function, _init, at the start of a program. This default function is part of the RCX API and sets all three outputs to full power in the forward direction (but still turned off). The initialization function can be disabled using the #pragma noinit directive:
#pragma noinit // don't do any program initialization

The default initialization function can be replaced with a different function using the
#pragma init directive. #pragma init function // use custom initialization

2.5.5Reserving Storage
The NQC compiler automatically assigns variables to storage locations. However, sometimes it is necessary to prevent the compiler from using certain storage locations. This can be done with the #pragma reserve directive:
#pragma reserve start #pragma reserve start end

This directive forces the compiler to ignore one or more storage locations during variable assignment. Start and end must be numbers that refer to valid storage locations. If only a Page 22

NQC Programmer's Guide start is provided, then that single location is reserved. If start and end are both specified, then the range of locations from start to end (inclusive) are reserved. The most common use of this directive is to reserve locations 0, 1, and/or 2 when using counters for RCX2, Swan, and Spybotics. This is because the RCX2, Swan, and Spybotics counters are overlapped with storage locations 0, 1, and 2. For example, if all three counters were going to be used:
#pragma reserve 0 2

Page 23

NQC Programmer's Guide

3 NQC API
The NQC API defines a set of constants, functions, values, and macros that provide access to various capabilities of the target such as sensors, outputs, timers, and communication. Some features are only available on certain targets. Where appropriate, a section's title will indicate which targets it applies to. The RCX2 and Swan are a superset of RCX features, so if RCX is listed, then the feature works with the original firmware, the 2.0 firmware, and the Swan firmware. If RCX2 is listed, then the feature only applies to the 2.0 firmware and the Swan firmware. If Swan is listed alone, then the feature only applies to the Swan firmware. CyberMaster, Scout, and Spybotics are indicated by CM, Scout, and Spy respectively. The API consists of functions, values, and constants. A function is something that can be called as a statement. Typically it takes some action or configures some parameter. Values represent some parameter or quantity and can be used in expressions. Constants are symbolic names for values that have special meanings for the target. Often, a set of constants will be used in conjunction with a function. For example, the PlaySound function takes a single argument which determines which sound is to be played. Constants, such as SOUND_UP, are defined for each sound.

3.1

Sensors

There are three sensors, which internally are numbered 0, 1, and 2. This is potentially confusing since they are externally labeled on the RCX as sensors 1, 2, and 3. To help mitigate this confusion, the sensor names SENSOR_1, SENSOR_2, and SENSOR_3 have been defined. These sensor names may be used in any function that requires a sensor as an argument. Furthermore, the names may also be used whenever a program wishes to read the current value of the sensor:
x = SENSOR_1; // read sensor and store value in x

Page 24

NQC Programmer's Guide

3.1.1Types and Modes

RCX, CM, Spy

The sensor ports on the RCX are capable of interfacing to a variety of different sensors (other targets don't support configurable sensor types). It is up to the program to tell the RCX what kind of sensor is attached to each port. A sensor's type may be configured by calling SetSensorType. . There are four sensor types, each corresponding to a specific LEGO sensor. A fifth type (SENSOR_TYPE_NONE) can be used for reading the raw values of generic passive sensors. In general, a program should configure the type to match the actual sensor. If a sensor port is configured as the wrong type, the RCX may not be able to read it accurately.
Sensor Type SENSOR_TYPE_NONE SENSOR_TYPE_TOUCH SENSOR_TYPE_TEMPERATURE SENSOR_TYPE_LIGHT SENSOR_TYPE_ROTATION Meaning generic passive sensor a touch sensor a temperature sensor a light sensor a rotation sensor

The RCX, CyberMaster, and Spybotics allow a sensor to be configured in different modes. The sensor mode determines how a sensor's raw value is processed. Some modes only make sense for certain types of sensors, for example
SENSOR_MODE_ROTATION is useful only with rotation sensors. The sensor mode can be

set by calling SetSensorMode. The possible modes are shown below. Note that since CyberMaster does not support temperature or rotation sensors, the last three modes are restricted to the RCX only. Spybotics is even more restrictive, allowing only raw, boolean, and percentage modes.
Sensor Mode SENSOR_MODE_RAW SENSOR_MODE_BOOL SENSOR_MODE_EDGE SENSOR_MODE_PULSE SENSOR_MODE_PERCENT SENSOR_MODE_FAHRENHEIT Meaning raw value from 0 to 1023 boolean value (0 or 1) counts number of boolean transitions counts number of boolean periods value from 0 to 100 degrees F - RCX only

Page 25

NQC Programmer's Guide

SENSOR_MODE_CELSIUS SENSOR_MODE_ROTATION degrees C - RCX only rotation (16 ticks per revolution) - RCX only

When using the RCX, it is common to set both the type and mode at the same time. The SetSensor function makes this process a little easier by providing a single function to call and a set of standard type/mode combinations.
Sensor Configuration SENSOR_TOUCH SENSOR_LIGHT SENSOR_ROTATION SENSOR_CELSIUS SENSOR_FAHRENHEIT SENSOR_PULSE SENSOR_EDGE Type SENSOR_TYPE_TOUCH SENSOR_TYPE_LIGHT SENSOR_TYPE_ROTATION SENSOR_TYPE_TEMPERATURE SENSOR_TYPE_TEMPERATURE SENSOR_TYPE_TOUCH SENSOR_TYPE_TOUCH Mode SENSOR_MODE_BOOL SENSOR_MODE_PERCENT SENSOR_MODE_ROTATION SENSOR_MODE_CELSIUS SENSOR_MODE_FAHRENHEIT SENSOR_MODE_PULSE SENSOR_MODE_EDGE

The RCX provides a boolean conversion for all sensors - not just touch sensors. This boolean conversion is normally based on preset thresholds for the raw value. A "low" value (less than 460) is a boolean value of 1. A high value (greater than 562) is a boolean value of 0. This conversion can be modified: a slope value between 0 and 31 may be added to a sensor's mode when calling SetSensorMode. If the sensor's value changes more than the slope value during a certain time (3ms), then the sensor's boolean state will change. This allows the boolean state to reflect rapid changes in the raw value. A rapid increase will result in a boolean value of 0, a rapid decrease is a boolean value of 1. Even when a sensor is configured for some other mode (i.e. SENSOR_MODE_PERCENT), the boolean conversion will still be carried out.

SetSensor(sensor, configuration)

Function - RCX

Set the type and mode of the given sensor to the specified configuration, which must be a special constant containing both type and mode information.
SetSensor(SENSOR_1, SENSOR_TOUCH);

Page 26

NQC Programmer's Guide

SetSensorType(sensor, type)

Function - RCX

Set a sensor's type, which must be one of the predefined sensor type constants.
SetSensorType(SENSOR_1, SENSOR_TYPE_TOUCH);

SetSensorMode(sensor, mode)

Function - RCX, CM, Spy

Set a sensor's mode, which should be one of the predefined sensor mode constants. A slope parameter for boolean conversion, if desired, may be added to the mode (RCX only).
SetSensorMode(SENSOR_1, SENSOR_MODE_RAW); // raw mode SetSensorMode(SENSOR_1, SENSOR_MODE_RAW + 10); // slope 10

ClearSensor(sensor)

Function - All

Clear the value of a sensor - only affects sensors that are configured to measure a cumulative quantity such as rotation or a pulse count.
ClearSensor(SENSOR_1);

3.1.2Sensor Information
There are a number of values that can be inspected for each sensor. For all of these values the sensor must be specified by its sensor number (0, 1, or 2), and not a sensor name (e.g. SENSOR_1).

SensorValue(n)

Value - All

Returns the processed sensor reading for sensor n, where n is 0, 1, or 2. This is the same value that is returned by the sensor names (e.g. SENSOR_1).
x = SensorValue(0); // read sensor 1

SensorType(n)

Value All

Returns the configured type of sensor n, which must be 0, 1, or 2. Only the RCX has configurable sensors types, other targets will always return the pre-configured type of the sensor.

Page 27

NQC Programmer's Guide

x = SensorType(0);

SensorMode(n)

Value - RCX, CM, Spy

Returns the current sensor mode for sensor n, which must be 0, 1, or 2.

x = SensorMode(0);

SensorValueBool(n)

Value - RCX

Returns the boolean value of sensor n, which must be 0, 1, or 2. Boolean conversion is either done based on preset cutoffs, or a slope parameter specified by calling
SetSensorMode. x = SensorValueBool(0);

SensorValueRaw(n)

Value - RCX, Scout, Spy

Returns the raw value of sensor n, which must be 0, 1, or 2. Raw values may range from 0 to 1023 (RCX, Spy) or 0 to 255 (Scout).
x = SensorValueRaw(0);

3.1.3Scout Light Sensor

Scout

On the Scout, SENSOR_3 refers to the built-in light sensor. Reading the light sensor's value (with SENSOR_3) will return one of three levels: 0 (dark), 1 (normal), or 2 (bright). The sensor's raw value can be read with SensorValueRaw(SENSOR_3), but bear in mind that brighter light will result in a lower raw value. The conversion of the sensor's raw value (between 0 and 1023) to one of the three levels depends on three parameters: lower limit, upper limit, and hysteresis. The lower limit is the smallest (brightest) raw value that is still considered normal. Values below the lower limit will be considered bright. The upper limit is the largest (darkest) raw value that is considered normal. Values about this limit are considered dark. Hysteresis can be used to prevent the level from changing when the raw value hovers near one of the limits. This is accomplished by making it a little harder to leave the dark and bright states than it is to enter them. Specifically, the limit for moving from normal to bright will be a little lower than the limit for moving from bright back to normal. The Page 28

NQC Programmer's Guide difference between these two limits is the amount of hysteresis. A symmetrical case holds for the transition between normal and dark.

SetSensorLowerLimit(value)
Set the light sensor's lower limit. Value may be any expression.
SetSensorLowerLimit(100);

Function - Scout

SetSensorUpperLimit(value)
Set the light sensor's upper limit. Value may be any expression.
SetSensorUpperLimit(900);

Function - Scout

SetSensorHysteresis (value)
Set the light sensor's hysteresis. Value may be any expression.
SetSensorHysteresis(20);

Function - Scout

CalibrateSensor()

Function - Scout

Reads the current value of the light sensor, then sets the upper and lower limits to 12.5% above and below the current reading, and sets the hysteresis to 3.12% of the reading.
CalibrateSensor();

3.1.4Spybotics Sensors

Spy

Spybotics uses built-in sensors instead of externally connected ones. The touch sensor on the front of the Spybotics brick is SENSOR_1. It is normally configured in percentage mode, so it has a value of 0 when not pressed, and a value of 100 when pressed.
SENSOR_2 is the light sensor (the connector on the back of the brick that is used to

communicate with a computer). It is normally configured in percentage mode, where higher numbers indicate brighter light.

Page 29

NQC Programmer's Guide

3.2

Outputs

3.2.1Primitive Calls
All of the functions dealing with outputs take a set of outputs as their first argument. This set must be a constant. The names OUT_A, OUT_B, and OUT_C are used to identify the three outputs. Multiple outputs can be combined by adding individual outputs together. For example, use OUT_A+OUT_B to specify outputs A and B together. The set of outputs must always be a compile time constant (it cannot be a variable). Each output has three different attributes: mode, direction, and power level. The mode can be set by calling SetOutput(outputs, mode). The mode parameter should be one of the following constants:
Output Mode OUT_OFF OUT_ON OUT_FLOAT Meaning output is off (motor is prevented from turning) output is on (motor will be powered) motor can "coast"

The other two attributes, direction and power level, may be set at any time, but only have an effect when the output is on. The direction is set with the SetDirection(outputs, direction) command. The direction parameter should be one of the following constants:
Direction OUT_FWD OUT_REV OUT_TOGGLE Meaning Set to forward direction Set to reverse direction Switch direction to the opposite of what it is presently

The power level can range 0 (lowest) to 7 (highest). The names OUT_LOW, OUT_HALF, and OUT_FULL are defined for use in setting power level. The level is set using the
SetPower(outputs, power) function.

Be default, all three motors are set to full power and the forward direction (but still turned off) when a program starts.

Page 30

NQC Programmer's Guide

SetOutput(outputs, mode)

Function - All

Set the outputs to the specified mode. Outputs is one or more of OUT_A, OUT_B, and
OUT_C. Mode must be OUT_ON, OUT_OFF, or OUT_FLOAT. SetOutput(OUT_A + OUT_B, OUT_ON); // turn A and B on

SetDirection(outputs, direction)

Function - All

Set the outputs to the specified direction. Outputs is one or more of OUT_A, OUT_B, and OUT_C. Direction must be OUT_FWD, OUT_REV, or OUT_TOGGLE.
SetDirection(OUT_A, OUT_REV); // make A turn backwards

SetPower(outputs, power)

Function - All

Sets the power level of the specified outputs. Power may be an expression, but should result in a value between 0 and 7. The constants OUT_LOW, OUT_HALF, and
OUT_FULL may also be used. SetPower(OUT_A, OUT_FULL); // A full power SetPower(OUT_B, x);

OutputStatus(n)

Value - All

Returns the current output setting for motor n. Note that n must be 0, 1, or 2 - not
OUT_A, OUT_B, or OUT_C. x = OutputStatus(0); // status of OUT_A

3.2.2Convenience Calls
Since control of outputs is such a common feature of programs, a number of convenience functions are provided that make it easier to work with the outputs. It should be noted that these commands do not provide any new functionality above the SetOutput and
SetDirection commands. They are merely convenient ways to make programs more

concise.

Page 31

NQC Programmer's Guide

On(outputs)

Function - All

Turn specified outputs on. Outputs is one or more of OUT_A, OUT_B, and OUT_C added together.
On(OUT_A + OUT_C); // turn on outputs A and C

Off(outputs)

Function - All

Turn specified outputs off. Outputs is one or more of OUT_A, OUT_B, and OUT_C added together.
Off(OUT_A); // turn off output A

Float(outputs)

Function - All

Make outputs float. Outputs is one or more of OUT_A, OUT_B, and OUT_C added together.
Float(OUT_A); // float output A

Fwd(outputs)

Function - All

Set outputs to forward direction. Outputs is one or more of OUT_A, OUT_B, and
OUT_C added together. Fwd(OUT_A);

Rev(outputs)

Function - All

Set outputs to reverse direction. Outputs is one or more of OUT_A, OUT_B, and
OUT_C added together. Rev(OUT_A);

Toggle(outputs)

Function - All

Flip the direction of the outputs. Outputs is one or more of OUT_A, OUT_B, and
OUT_C added together. Toggle(OUT_A);

Page 32

NQC Programmer's Guide

OnFwd(outputs)

Function - All

Set outputs to forward direction and turn them on. Outputs is one or more of OUT_A,
OUT_B, and OUT_C added together. OnFwd(OUT_A);

OnRev(outputs)

Function - All

Set outputs to reverse direction and turn them on. Outputs is one or more of OUT_A,
OUT_B, and OUT_C added together. OnRev(OUT_A);

OnFor(outputs, time)

Function - All

Turn outputs on for a specified amount of time, then turn them off. Outputs is one or more of OUT_A, OUT_B, and OUT_C added together. Time is measures in 10ms increments (one second = 100) and may be any expression.
OnFor(OUT_A, x);

3.2.3Global Control
SetGlobalOutput(outputs, mode)

RCX2, Scout, Spy

Function - RCX2, Scout, Spy

Disable or re-enable outputs depending on the mode parameter. If mode is OUT_OFF, then the outputs will be turned off and disabled. While disabled any subsequent calls to SetOutput() (including convenience functions such as On()) will be ignored. Using a mode of OUT_FLOAT will put the outputs in float mode before disabling them. Outputs can be re-enabled by calling SetGlobalOutput() with a mode of
OUT_ON. Note that enabling an output doesn't immediately turn it on - it just allows

future calls to SetOutput() to take effect.

SetGlobalOutput(OUT_A, OUT_OFF); SetGlobalOutput(OUT_A, OUT_ON); // disable output A // enable output A

Page 33

NQC Programmer's Guide

SetGlobalDirection(outputs, direction)

Function - RCX2, Scout, Spy

Reverses or restores the directions of outputs. The direction parameter should be

OUT_FWD, OUT_REV, or OUT_TOGGLE. Normal behavior is a global direction of OUT_FWD. When the global direction is OUT_REV, then the actual output direction

will be the opposite of whatever the regular output calls request. Calling
SetGlobalDirection() with OUT_TOGGLE will switch between normal and

opposite behavior.
SetGlobalDirection(OUT_A, OUT_REV); // opposite direction SetGlobalDirection(OUT_A, OUT_FWD); // normal direction

SetMaxPower(outputs, power)

Function - RCX2, Scout, Spy

Sets the maximum power level allowed for the outputs. The power level may be a variable, but should have a value between OUT_LOW and OUT_FULL.
SetMaxPower(OUT_A, OUT_HALF);

GlobalOutputStatus(n)

Value - RCX2, Scout, Spy

Returns the current global output setting for motor n. Note that n must be 0, 1, or 2 not OUT_A, OUT_B, or OUT_C.
x = GlobalOutputStatus(0); // global status of OUT_A

EnableOutput(outputs)

Function - RCX2, Scout, Spy

A helper function for enabling the specified outputs. Use OUT_A, OUT_B, or OUT_C.
EnableOutput(OUT_A+OUT_B); // enable OUT_A and OUT_B

This is the same as using SetGlobalOutput with the OUT_ON mode.

DisableOutput(outputs)

Function - RCX2, Scout, Spy

A helper function for disabling the specified outputs. Use OUT_A, OUT_B, or OUT_C.
DisableOutput(OUT_A+OUT_B); // disable OUT_A and OUT_B

Page 34

NQC Programmer's Guide This is the same as using SetGlobalOutput with the OUT_OFF mode.

InvertOutput(outputs)

Function - RCX2, Scout, Spy

A helper function for inverting the direction of the specified outputs. Use OUT_A, OUT_B, or OUT_C.
InvertOutput(OUT_A+OUT_B); // reverse dir OUT_A and OUT_B

This is the same as using SetGlobalDirection with the OUT_REV direction.

ObvertOutput(outputs)

Function - RCX2, Scout, Spy

A helper function for returning the direction of the specified outputs to forward. Use OUT_A, OUT_B, or OUT_C.
ObvertOutput(OUT_A+OUT_B); // normal dir OUT_A and OUT_B

This is the same as using SetGlobalDirection with the OUT_FWD direction.

3.2.4Spybotics Outputs
Spybotics has two built-in motors. OUT_A refers to the right motor, and OUT_B is for the left motor. OUT_C will send VLL commands out the rear LED (the one used for communication with a computer). This allows a VLL device, such as a Micro-Scout, to be used as a third motor for Spybotics. The same LED may be controlled using the
SendVLL() and SetLight() functions.

3.3

Sound
Function - All

PlaySound(sound)

Plays one of the 6 preset RCX sounds. The sound argument must be a constant (except on Spybotics, which allows a variable to be used). The following constants are pre-defined for use with PlaySound: SOUND_CLICK, SOUND_DOUBLE_BEEP,
SOUND_DOWN, SOUND_UP, SOUND_LOW_BEEP, SOUND_FAST_UP. PlaySound(SOUND_CLICK);

Page 35

NQC Programmer's Guide The Spybotics brick has additional sound support via this function. It has 64 preset sounds in ROM (numbered 0-63). The additional 58 constants defined for these sounds are: Spybot Sound Effect Constants
SOUND_SHOCKED, SOUND_FIRE_LASER, SOUND_FIRE_ELECTRONET, SOUND_FIRE_SPINNER, SOUND_HIT_BY_LASER, SOUND_HIT_BY_ELECTRONET, SOUND_HIT_BY_SPINNER, SOUND_TAG, SOUND_CRASH, SOUND_FIGHT, SOUND_GOT_IT, SOUND_GENERAL_ALERT, SOUND_OUT_OF_ENERGY_ALERT, SOUND_LOW_ENERGY_ALERT, SOUND_SCORE_ALERT, SOUND_TIME_ALERT, SOUND_PROXIMITY_ALERT, SOUND_DANGER_ALERT, SOUND_BOMB_ALERT, SOUND_FINAL_COUNTDOWN, SOUND_TICK_TOCK, SOUND_GOTO, SOUND_SCAN, SOUND_POINT_TO, SOUND_ACTIVATE_SHIELDS, SOUND_ACTIVATE_REFLECT, SOUND_ACTIVATE_CLOAK, SOUND_ACTIVATE_FLASH_BLIND, SOUND_MAGNET, SOUND_QUAD_DAMAGE, SOUND_REPULSE, SOUND_TURBO, SOUND_FREEZE, SOUND_SLOW, SOUND_REVERSE, SOUND_DIZZY, SOUND_BOOST, SOUND_DEACTIVATE_SHIELDS, SOUND_DEACTIVATE_REFLECT, SOUND_DEACTIVATE_CLOAK, SOUND_REFLECT, SOUND_EXPLOSION, SOUND_BIG_EXPLOSION, SOUND_PLACE_BOMB, SOUND_HIT_BY_WIND, SOUND_OUCH, SOUND_GEIGER, SOUND_WHISTLE, SOUND_IM_IT, SOUND_HELP, SOUND_SIREN, SOUND_BURNT, SOUND_GRINDED, SOUND_SMACKED, SOUND_TRILL_UP, SOUND_TRILL_DOWN, SOUND_YELL, SOUND_WHISPER

A special constant, SOUND_NONE, is also defined for the Spybotics target to indicate that no sound should be played.

PlayTone(frequency, duration)

Function - All

Plays a single tone of the specified frequency and duration. The frequency is in Hz and can be a variable for RCX2, Scout, and Spybotics, but has to be constant for RCX and CyberMaster. The duration is in 100ths of a second and must be a constant.
PlayTone(440, 50); // Play 'A' for one half second

MuteSound()
Stops all sounds and tones from being played.
MuteSound();

Function - RCX2, Scout, Spy

UnmuteSound()
Restores normal operation of sounds and tones.

Function - RCX2, Scout, Spy

Page 36

NQC Programmer's Guide

UnmuteSound();

ClearSound()
Removes any pending sounds from the sound buffer.
ClearSound();

Function - RCX2, Spy

SelectSounds(group)

Function - Scout

Selects which group of system sounds should be used. The group must be a constant.
SelectSounds(0);

3.4

LCD Display

RCX

The RCX has seven different display modes as shown below. The RCX defaults to
DISPLAY_WATCH.
Mode DISPLAY_WATCH DISPLAY_SENSOR_1 DISPLAY_SENSOR_2 DISPLAY_SENSOR_3 DISPLAY_OUT_A DISPLAY_OUT_B DISPLAY_OUT_C LCD Contents show the system "watch" show value of sensor 1 show value of sensor 2 show value of sensor 3 show setting for output A show setting for output B show setting for output C

The RCX2 adds an eighth display mode - DISPLAY_USER. User display mode continuously reads a source value and updates the display. It can optionally display a decimal point at any position within the number. This allows the display to give the illusion of working with fractions even though all values are stored internally as integers. For example, the following call will set the user display to show the value 1234 with two digits appearing after the decimal point, resulting in "12.34" appearing on the LCD.
SetUserDisplay(1234, 2);

The following short program illustrates the update of the user display:
task main() {

Page 37

NQC Programmer's Guide

ClearTimer(0); SetUserDisplay(Timer(0), 0); until(false); }

Because the user display mode continuously updates the LCD, there are certain restrictions on the source value. If a variable is used it must be assigned to a global storage location. The best way to ensure this is to make the variable a global one. There can also be some strange side effects. For example, if a variable is being displayed and later used as the target of a calculation, it is possible for the display to show some intermediate results of the calculation:
int x; task main() { SetUserDisplay(x, 0); while(true) { // display may briefly show 1! x = 1 + Timer(0); } }

SelectDisplay(mode)
Select a display mode.
SelectDisplay(DISPLAY_SENSOR_1);

Function - RCX

// view sensor 1

SetUserDisplay(value, precision)

Function - RCX2

Set the LCD display to continuously monitor the specified value. Precision specifies the number of digits to the right of the decimal point. A precision of zero shows no decimal point.
SetUserDisplay(Timer(0), 0); // view timer 0

3.5

Communication
RCX, Scout

3.5.1Messages

The RCX and Scout can send and receive simple messages using IR. A message can have a value from 0 to 255, but the use of message 0 is discouraged. The most recently Page 38

NQC Programmer's Guide received message is remembered and can be accessed as Message(). If no message has been received, Message() will return 0. Note that due to the nature of IR communication, receiving is disabled while a message is being transmitted.

ClearMessage()

Function - RCX, Scout

Clear the message buffer. This facilitates detection of the next received message since the program can then wait for Message() to become non-zero:
ClearMessage(); // clear out the received message until(Message() > 0); // wait for next message

SendMessage(message)

Function - RCX, Scout

Send an IR message. Message may be any expression, but the RCX can only send messages with a value between 0 and 255, so only the lowest 8 bits of the argument are used.
SendMessage(3); // send message 3 SendMessage(259); // another way to send message 3

SetTxPower(power)

Function - RCX, Scout

Set the power level for IR transmission. Power should be one of the constants
TX_POWER_LO or TX_POWER_HI.

MessageParam()

Value - Swan

Read the message parameter. The Swan firmware supports a 2 byte message parameter in addition to the single byte supported by the RCX firmware.
x = MessageParam(); // read the rcvd msg param value

SendMessageWithParam(const int &m, const int &p)

Function - Swan

Send an IR message with an additional parameter. The first parameter is restricted a single byte while the second parameter can be two bytes.
SendMessageWithParam(3, 1024);

Page 39

NQC Programmer's Guide

SetMessageByteParam(const int m, const int p)

Function - Swan

Set the IR message and its parameter using constants. The parameter must be a single byte value.
SetMessageByteParam(3, 43);

SetMessageWordParam(const int m, const int p)

Function - Swan

Set the IR message and its parameter using constants. The parameter can be 2 bytes.
SetMessageWordParam(3, 1024);

SetMessageVariableParam(const int &m, const int &p) Function - Swan

Set the IR message and its parameter using variables. The parameter can be 2 bytes.
SetMessageVariableParam(x, y);

3.5.2Serial

RCX2, Spy

The RCX2 and Spybotics can transmit serial data out the IR port. Prior to transmitting any data, the communication and packet settings must be specified. Then, for each transmission, data should be placed in the transmit buffer, then sent using the
SendSerial() function.

For the RCX2 the communication settings are set with SetSerialComm. This determines how bits are sent over IR. Possible values are shown below. Option SERIAL_COMM_DEFAULT SERIAL_COMM_4800 SERIAL_COMM_DUTY25 SERIAL_COMM_76KHZ Effect default settings 4800 baud 25% duty cycle 76kHz carrier

The default is to send data at 2400 baud using a 50% duty cycle on a 38kHz carrier. To specify multiple options (such as 4800 baud with 25% duty cycle), combine the individual options using bitwise or (SERIAL_COMM_4800 | SERIAL_COMM_DUTY25). Page 40

NQC Programmer's Guide The RCX2 also allows you to set the packet settings with SetSerialPacket. This controls how bytes are assembled into packets. Possible values are shown below. Option SERIAL_PACKET_DEFAULT SERIAL_PACKET_PREAMBLE SERIAL_PACKET_NEGATED SERIAL_PACKET_CHECKSUM SERIAL_PACKET_RCX Effect no packet format - just data bytes send a packet preamble follow each byte with its complement include a checksum for each packet standard RCX format (preamble, negated data, and checksum)

Note that negated packets always include a checksum, so the

SERIAL_PACKET_CHECKSUM option is only meaningful when SERIAL_PACKET_NEGATED is not specified. Likewise the preamble, negated, and

checksum settings are implied by SERIAL_PACKET_RCX. The transmit buffer can hold up to 16 data bytes. These bytes may be set using
SetSerialData, then transmitted by calling SendSerial. For example, the following

code sends two bytes (0x12 and 0x34) out the serial port:
SetSerialComm(SERIAL_COMM_DEFAULT); SetSerialPacket(SERIAL_PACKET_DEFAULT); SetSerialData(0, 0x12); SetSerialData(1, 0x34); SendSerial(0, 2);

Spybotics uses a different mechanism for configuring the serial transmission parameters. Use SetSerialType to specify the transmission type with the constants described in the following table. Option SERIAL_TYPE_SPYBOT SERIAL_TYPE_RCX SERIAL_TYPE_RC SERIAL_TYPE_USER Effect Spybotics type RCX type RC type User-defined type

Page 41

NQC Programmer's Guide Use SetSerialBaud to specify the baud rate with the constants described in the following table. Option SERIAL_BAUD_2400 SERIAL_BAUD_4800 SERIAL_BAUD_9600 Effect 2400 baud 4800 baud 9600 baud

Use SetSerialChannel to specify the transmission channel with the constants described in the following table. Option SERIAL_CHANNEL_IR SERIAL_CHANNEL_PC Effect IR channel PC channel (visible light)

Use SetSerialPreamblePos to specify the position of the preamble in the 16 bytes of serial data. Use SetSerialPreambleLen to specify the length of the preamble. Use
SetSerialChecksum to specify the checksum type with the constants described in the

following table. Option SERIAL_CHECKSUM_NONE SERIAL_CHECKSUM_SUM SERIAL_CHECKSUM_ZERO_SUM Effect No checksum Sum checksum Zero sum checksum

Use SetSerialBiPhase to specify the bi-phase mode with the constants described in the following table. Option SERIAL_BIPHASE_OFF SERIAL_BIPHASE_ON Effect No bi-phase Use bi-phase

SetSerialComm(settings)

Function - RCX2

Set the communication settings, which determine how the bits are sent over IR

Page 42

NQC Programmer's Guide

SetSerialComm(SERIAL_COMM_DEFAULT);

SetSerialPacket(settings)

Function - RCX2

Set the packet settings, which control how bytes are assembled into packets.
SetSerialPacket(SERIAL_PACKET_DEFAULT);

SetSerialData(n, value)

Function - RCX2, Spy

Set one byte of data in the transmit buffer. N is the index of the byte to set (0-15), and value can be any expression.
SetSerialData(3, x); // set byte 3 to x

SerialData(n)

Value - RCX2, Spy

Returns the value of a byte in the transmit buffer (NOT received data). N must be a constant between 0 and 15.
x = SerialData(7); // read byte #7

SendSerial(start, count)

Function - RCX2, Spy

Use the contents of the transmit buffer to build a packet and send it out the IR port (according to the current packet and communication settings). Start and count are both constants that specify the first byte and the number of bytes within the buffer to be sent.
SendSerial(0,2); // send first two bytes in buffer

InitSpybotComm()

Function - RCX2

Use this function to configure the serial communication registers in preparation for sending messages using the Spybot protocol.
InitSpybotComm(); // prepare IR using Spybot protocol

SendSpybotMsg()

Function - RCX2

Use this function to send a 7 byte Spybot message which was previously set via a call to SetSpybotMessage.
SendSpybotMsg();

Page 43

NQC Programmer's Guide

SetSpybotMessage(mode, myID, addr, cmd, hi, lo)

Function - RCX2

Use this function to set the contents of a Spybot message. The message can then be sent repeatedly via calls to SendSpybotMsg.
SetSpybotMessage(MSG_BROADCAST, 9, 0, CMD_FIRE_LASER, 1, 100);

SendSpybotMessage(mode, myID, addr, cmd, hi, lo)

Function - RCX2

Use this function to send a 7 byte Spybot message. This function calls InitSpybotComm, SetSpybotMessage, and SendSpybotMsg in sequence.
SendSpybotMessage(MSG_BROADCAST, 9, 0, CMD_FIRE_LASER, 1, 100);

SendSpybotCtrlMsg()

Function - RCX2

Use this function to send a 2 byte Spybot controller message which was previously set via a call to SetSpybotCtrlMessage.
SendSpybotCtrlMsg();

SetSpybotCtrlMessage(nMyID, nMsg)

Function - RCX2

Use this function to set the contents of a Spybot controller message. The message can then be sent repeatedly via calls to SendSpybotCtrlMsg.
SetSpybotCtrlMessage(ID_CTRL_1, SPY_CTRL_BTN_1);

SendSpybotCtrlMessage(nMyID, nMsg)

Function - RCX2

Use this function to send a 2 byte Spybot controller message. This function calls InitSpybotComm, SetSpybotCtrlMessage, and SendSpybotCtrlMsg in sequence.
SendSpybotCtrlMessage(ID_CTRL_1, SPY_CTRL_BTN_1);

SendSpybotCtrlPingMsg()

Function - RCX2

Use this function to send a 2 byte Spybot controller ping message which was previously set via a call to SetSpybotCtrlPingMessage.

Page 44

NQC Programmer's Guide

SendSpybotCtrlPingMsg();

SetSpybotCtrlPingMessage(nID)

Function - RCX2

Use this function to set the contents of a Spybot controller ping message. The message can then be sent repeatedly via calls to SendSpybotCtrlPingMsg.
SetSpybotCtrlPingMessage(ID_CTRL_1);

SendSpybotCtrlPingMessage(nID)

Function - RCX2

Use this function to send a 2 byte Spybot controller ping message. This function calls InitSpybotComm, SetSpybotCtrlPingMessage, and SendSpybotCtrlPingMsg in sequence.
SendSpybotCtrlPingMessage(ID_CTRL_1);

SendSpybotPingMsg()

Function - RCX2

Use this function to send a 4 byte Spybot ping message which was previously set via a call to SetSpybotPingMessage.
SendSpybotPingMsg();

SetSpybotPing(nLinkID, nMyID, nInfo)

Function RCX2

Use this function to set the contents of a Spybot ping message. The message can then be sent repeatedly via calls to SendSpybotPingMsg.
SetSpybotPingMessage(ID_CTRL_1, ID_MIN_BOT+1, 10);

SendSpybotPing(nLinkID, nMyID, nInfo)

Function - RCX2

Use this function to send a 2 byte Spybot ping message. This function calls InitSpybotComm, SetSpybotPingMessage, and SendSpybotPingMsg in sequence.
SendSpybotPingMessage(ID_CTRL_1, ID_MIN_BOT+1, 10);

InitRCComm()

Function - RCX2

Use this function to configure the serial communication registers in preparation for sending messages using the Spybot RC protocol. Page 45

NQC Programmer's Guide

InitRCComm(); // prepare to send IR using RC protocol

SendRCMsg()

Function - RCX2

Use this function to send a 4 byte RC message which was previously set via a call to SetRCMessage.
SendRCMsg();

SetRCMessage(nChannel, nLeft, nRight)

Function - RCX2

Use this function to set the contents of a Spybot RC message. The message can then be sent repeatedly via calls to SendRCMsg.
SetRCMessage(RC_CHANNEL_2, RC_CMD_FWD, RC_CMD_FWD);

SendRCMessage(nChannel, nLeft, nRight)

Function - RCX2

Use this function to send a 2 byte Spybot ping message. This function calls InitRCComm, SetRCMessage, and SendRCMsg in sequence.
SendRCMessage(RC_CHANNEL_2, RC_CMD_FWD, RC_CMD_FWD);

DefaultSerialComm()
Returns the default UART transmit parameter configuration.

Value - Swan

x = DefaultSerialComm(); // read default UART xmit config

DefaultSerialPacket()
Returns the default packet data formatting configuration.

Value - Swan

x = DefaultSerialPacket(); // read default packet config

SetDefaultSerialComm(settings)

Function - Swan

Set the default communication settings, which determine how the bits are sent over IR
SetDefaultSerialComm(SERIAL_COMM_DEFAULT);

SetDefaultSerialPacket(settings)

Function - Swan

Set the default packet settings, which control how bytes are assembled into packets.
SetDefaultSerialPacket(SERIAL_PACKET_DEFAULT);

Page 46

NQC Programmer's Guide

SerialType()
Returns the type of the serial transmission.
x = SerialType(); // SERIAL_TYPE_USER ??

Value - Spy

SetSerialType(type)
Sets the type of the serial transmission.

Function - Spy

SetSerialType(SERIAL_TYPE_USER); // set type to user

Use one of the following constants: SERIAL_TYPE_SPYBOT, SERIAL_TYPE_RCX,

SERIAL_TYPE_RC, SERIAL_TYPE_USER.

SerialBaud()
Returns the baud rate of the serial transmission.
x = SerialBaud(); // SERIAL_BAUD_2400 ??

Value - Spy

SetSerialBaud(baud)
Sets the baud rate of the serial transmission.

Function - Spy

SetSerialBaud(SERIAL_BAUD_2400); // set baud to 2400

Use one of the following constants: SERIAL_BAUD_2400, SERIAL_BAUD_4800,

SERIAL_BAUD_9600.

SerialChannel()
Returns the transmission channel.
x = SerialChannel(); // SERIAL_CHANNEL_PC ??

Value - Spy

SetSerialChannel(channel)
Sets the transmission channel.

Function - Spy

SetSerialChannel(SERIAL_CHANNEL_IR); // set channel to IR

Page 47

NQC Programmer's Guide Use one of the following constants: SERIAL_CHANNEL_IR, SERIAL_CHANNEL_PC.

SerialPreamblePos()
Returns the preamble position within the serial data buffer.
x = SerialPreamblePos();

Value - Spy

SetSerialPreamblePos(n)
Sets the position of the preamble within the serial data buffer.

Function - Spy

SetSerialPreamblePos(12); // set preamble pos to 12

SerialPreambleLen()
Returns the preamble length.
x = SerialPreambleLen();

Value - Spy

SetSerialPreambleLen(n)
Sets the length of the preamble.

Function - Spy

SetSerialPreambleLen(3); // set preamble length to 3

SerialChecksum()
Returns the transmission checksum type.
x = SerialChecksum(); // SERIAL_CHECKSUM_SUM ??

Value - Spy

SetSerialChecksum(check)
Sets the transmission checksum type.

Function - Spy

SetSerialChecksum(SERIAL_CHECKSUM_SUM); // use Sum checksum

Use one of the following constants: SERIAL_CHECKSUM_NONE,

SERIAL_CHECKSUM_SUM, SERIAL_CHECKSUM_ZERO_SUM.

SerialBiPhase()
Returns the transmission bi-phase mode.
x = SerialBiPhase(); // SERIAL_BIPHASE_OFF ??

Value - Spy

Page 48

NQC Programmer's Guide

SetSerialBiPhase(mode)
Sets the transmission bi-phase mode.

Function - Spy

SetSerialBiPhase(SERIAL_BIPHASE_OFF); // no bi-phase

Use one of the following constants: SERIAL_BIPHASE_OFF,

SERIAL_BIPHASE_ON.

3.5.3VLL
SendVLL(value)

Scout, Spy
Function Scout, Spy

Sends a Visible Light Link (VLL) command, which can be used to communicate with the MicroScout or Code Pilot. The specific VLL commands are described in the Scout SDK.
SendVLL(4); // send VLL command #4

3.6

Timers

All targets provide several independent timers with 100ms resolution (10 ticks per second). The Scout provides 3 such timers while the RCX, Swan, CyberMaster and Spybotics provide 4. The timers wrap around to 0 after 32767 ticks (about 55 minutes). The value of a timer can be read using Timer(n), where n is a constant that determines which timer to use (0-2 for Scout, 0-3 for the others). RCX2, Swan, and Spybotics provide the ability to read the same timers with higher resolution by using
FastTimer(n), which returns the timer's value with 10ms resolution (100 ticks per

second).

ClearTimer(n)
Reset the specified timer to 0.
ClearTimer(0);

Function - All

Timer(n)
Return the current value of specified timer (in 100ms resolution).

Value - All

Page 49

NQC Programmer's Guide

x = Timer(0);

SetTimer(n, value)

Function - RCX2, Spy

Set a timer to a specific value (which may be any expression).

SetTimer(0, x);

FastTimer(n)
Return the current value of specified timer in 10ms resolution.
x = FastTimer(0);

Value - RCX2, Spy

3.7

Counters

RCX2, Scout, Spy

Counters are like very simple variables that can be incremented, decremented, and cleared. The Scout provides two counters (0 and 1), while RCX2, Swan, and Spybotics provide three (0, 1, and 2). In the case of RCX2, Swan, and Spybotics, these counters are overlapped with global storage locations 0-2, so if they are going to be used as counters, a #pragma reserve should be used to prevent NQC from using the storage location for a regular variable. For example, to use counter 1:
#pragma reserve 1

ClearCounter(n)

Function - RCX2, Scout, Spy

Reset counter n to 0. N must be 0 or 1 for Scout, 0-2 for RCX2 and Spybotics.
ClearCounter(1);

IncCounter(n)

Function - RCX2, Scout, Spy

Increment counter n by 1. N must be 0 or 1 for Scout, 0-2 for RCX2 and Spybotics.
IncCounter(1);

DecCounter(n)

Function - RCX2, Scout, Spy

Decrement counter n by 1. N must be 0 or 1 for Scout, 0-2 for RCX2 and Spybotics.
DecCounter(1);

Page 50

NQC Programmer's Guide

Counter(n)

Value - RCX, Scout, Spy

Return the current value of counter n. N must be 0 or 1 for Scout, 0-3 for RCX2 and Spybotics.
x = Counter(1);

3.8

Access Control

RCX2, Scout, Spy

Access control is implemented primarily by the acquire statement. The SetPriority function can be used to set a task's priority, and the following constants may be used to specify resources in an acquire statement. Note that the user defined resources are only available on the RCX2 and Swan. Constant ACQUIRE_OUT_A, ACQUIRE_OUT_B, ACQUIRE_OUT_C ACQUIRE_SOUND ACQUIRE_LED ACQUIRE_USER_1, ACQUIRE_USER_2, ACQUIRE_USER_3, ACQUIRE_USER_4 Resource outputs

sound LEDs (Spybotics only) user defined RCX2 and Swan only

SetPriority(p)

Function - RCX2, Scout, Spy

Set a task's priority to p, which must be a constant. RCX2, Swan, and Spybotics support priorities 0-255, while Scout supports priorities 0-7. Note that lower numbers are higher priority.
SetPriority(1);

3.9

Events

RCX2, Scout

Although the RCX2, Swan, Scout, and Spybotics share a common event mechanism, the RCX2, Swan, and Spybotics provide 16 completely configurable events while the Scout Page 51

NQC Programmer's Guide has 15 predefined events. The only functions common to both targets are the commands to inspect or force events.

ActiveEvents(task)

Value - RCX2, Scout, Spy

Return the set of events that have been triggered for a given task.
x = ActiveEvents(0);

CurrentEvents()

Value - RCX2, Spy

Return the set of events that have been triggered for the active task.
x = CurrentEvents();

Event(events)

Function - RCX2, Scout, Spy

Manually triggers the specified events. This can be useful in testing event handling of the program, or in other cases simulating an event based on other criteria. Note that the specification of the events themselves is slightly different between brick types. RCX2, Swan, and Spybotics use the EVENT_MASK macro to compute an event mask, while Scout has predefined masks.
Event(EVENT_MASK(3)); // triggering an RCX2 event Event(EVENT_1_PRESSED); // triggering a Scout event

3.9.1Configurable Events

RCX2, Spy

RCX2, Swan, and Spybotics provide an extremely flexible event system. There are 16 events, each of which can be mapped to one of several event sources (the stimulus that can trigger the event), and an event type (the criteria for triggering). A number of other parameters may also be specified depending on the event type. For all of the configuration calls an event is identified by its event number - a constant from 0 to 15. Legal event sources are sensors, timers, counters, or the message buffer. An event is configured by calling SetEvent(event, source, type), where event is a constant event number (0-15), source is the event source itself, and type is one of the types shown below (some combinations of sources and types are illegal).

Page 52

NQC Programmer's Guide Event Type

EVENT_TYPE_PRESSED EVENT_TYPE_RELEASED EVENT_TYPE_PULSE EVENT_TYPE_EDGE EVENT_TYPE_FASTCHANGE EVENT_TYPE_LOW EVENT_TYPE_NORMAL EVENT_TYPE_HIGH EVENT_TYPE_CLICK EVENT_TYPE_DOUBLECLICK EVENT_TYPE_MESSAGE EVENT_TYPE_ENTRY_FOUND EVENT_TYPE_MSG_DISCARD EVENT_TYPE_MSG_RECEIVED EVENT_TYPE_VLL_MSG_RECEIVED EVENT_TYPE_ENTRY_CHANGED EVENT_TYPE_4 EVENT_TYPE_5 EVENT_TYPE_6 EVENT_TYPE_VIRTUAL_MOTOR_CH ANGE EVENT_TYPE_VIRTUAL_MOTOR_PO WER EVENT_TYPE_VIRTUAL_SENSOR_D EF EVENT_TYPE_INFRARED_IDLE EVENT_TYPE_RESET

Condition value becomes on value becomes off value goes from off to on to off value goes from on to off or vice versa value changes rapidly value becomes low value becomes normal value becomes high value from low to high back to low two clicks within a certain time new message received World entry found Message discarded Message received Message received World entry changed Event type 4 Event type 5 Event type 6 Virtual motor changes Virtual motor power Virtual sensor def Infrared goes idle reset

Event Source sensors only sensors only sensors only (RCX2) sensors only (RCX2) sensors only (RCX2) any any any any Any (RCX2) Message() only (RCX2) VLL() only (Spy) VLL() only (Spy) VLL() only (Spy) VLL() only (Spy) VLL() only (Spy) any (Swan) any (Swan) any (Swan) any (Swan) any (Swan) any (Swan) any (Swan) any (Swan)

Page 53

NQC Programmer's Guide The first four event types make use of a sensor's boolean value, thus are most useful with touch sensors. For example, to set event #2 to be triggered when a touch sensor on port 1 is pressed, the following call could be made:
SetEvent(2, SENSOR_1, EVENT_TYPE_PRESSED);

In order for EVENT_TYPE_PULSE or EVENT_TYPE_EDGE to be used, the sensor must be configured in the SENSOR_MODE_PULSE or SENSOR_MODE_EDGE respectively.
EVENT_TYPE_FASTCHANGE should be used with sensors that have been configured with

a slope parameter. When the raw value changes faster than the slope parameter an
EVENT_TYPE_FASTCHANGE event will be triggered.

The next three types (EVENT_TYPE_LOW, EVENT_TYPE_NORMAL, and

EVENT_TYPE_HIGH) convert an event source's value into one of three ranges (low,

normal, or high), and trigger an event when the value moves from one range into another. The ranges are defined by the lower limit and upper limit for the event. When the source value is lower than the lower limit, the source is considered low. When the source value is higher than the upper limit, the source is considered high. The source is normal whenever it is between the limits. The following example configures event #3 to trigger when the sensor on port 2's value goes into the high range. The upper limit is set for 80, and the lower limit is set for 50. This configuration is typical of how an event can be triggered when a light sensor detected a bright light.
SetEvent(3, SENSOR_2, EVENT_TYPE_HIGH); SetLowerLimit(3, 50); SetUpperLimit(3, 80);

A hysteresis parameter can be used to provide more stable transitions in cases where the source value may jitter. Hysteresis works by making the transition from low to normal a little higher than the transition from normal to low. In a sense, it makes it easier to get into the low range than get out of it. A symmetrical case applies to the transition between normal and high. A transition from low to high back to low will trigger a EVENT_TYPE_CLICK event, provided that the entire sequence is faster than the click time for the event. If two Page 54

NQC Programmer's Guide successive clicks occur and the time between clicks is also less than the click time, then an EVENT_TYPE_DOUBLECLICK event will be triggered. The system also keeps track of the total number of clicks for each event. The last event type, EVENT_TYPE_MESSAGE, is only valid when Message() is used as the event source. The event will be triggered whenever a new message arrives (even if its value is the same as a previous message). The monitor statement and some API functions (such as ActiveEvents() or Event()) need to handle multiple events. This is done by converting each event number to an event mask, and then combining the masks with a bitwise OR. The EVENT_MASK(event) macro converts an event number to a mask. For example, to monitor events 2 and 3, the following statement could be used:
monitor(EVENT_MASK(2) | EVENT_MASK(3))

SetEvent(event, source, type)

Function - RCX2, Spy

Configure an event (a number from 0 to 15) to use the specified source and type. Both event and type must be constants, and source should be the actual source expression.
SetEvent(2, Timer(0), EVENT_TYPE_HIGH);

ClearEvent(event)

Value - RCX2, Spy

Clear the configuration for the specified event. This prevents it from triggering until it is re-configured.
ClearEvent(2); // clear event #2

ClearAllEvents()
Clear the configurations for all events.
ClearAllEvents();

Value - RCX2, Spy

EventState(event)

Value - RCX2, Spy

Return the state of a given event. States are 0: Low, 1: Normal, 2: High, 3: Undefined, 4: Start calibrating, 5: Calibrating in process. Page 55

NQC Programmer's Guide

x = EventState(2);

CalibrateEvent(event, lower, upper, hyst)

Function - RCX2, Spy

Calibrate the event by taking an actual sensor reading and then applying the specified lower, upper, and hyst ratios to determine actual limits and hysteresis value. The specific formulas for calibration depend on sensor type and are explained in the LEGO SDK. Calibration is not instantaneous - EventState() can be checked to determine when the calibration is complete (typically about 50ms).
CalibrateEvent(2, 50, 50, 20); until(EventState(2) != 5); // wait for calibration

SetUpperLimit(event, limit)

Function - RCX2, Spy

Set the upper limit for the event, where event is a constant event number and limit can be any expression.
SetUpperLimit(2, x); // set upper limit for #2 to x

UpperLimit(event)
Return the current upper limit for the specified event number.

Value - RCX2, Spy

x = UpperLimit(2); // get upper limit for event 2

SetLowerLimit(event, limit)

Function - RCX2, Spy

Set the lower limit for the event, where event is a constant event number and limit can be any expression.
SetLowerLimit(2, x); // set lower limit for #2 to x

LowerLimit(event)
Return the current lower limit for the specified event number.

Value - RCX2, Spy

x = LowerLimit(2); // get lower limit for event 2

SetHysteresis(event, value)

Function - RCX2, Spy

Set the hysteresis for the event, where event is a constant event number and value can be any expression. Page 56

NQC Programmer's Guide

SetHysteresis(2, x);

Hysteresis(event)
Return the current hysteresis for the specified event number.
x = Hysteresis(2);

Value - RCX2, Spy

SetClickTime(event, value)

Function - RCX2, Spy

Set the click time for the event, where event is a constant event number and value can be any expression. The time is specified in increments of 10ms, so one second would be a value of 100.
SetClickTime(2, x);

ClickTime(event)
Return the current click time for the specified event number.
x = ClickTime(2);

Value - RCX2, Spy

SetClickCounter(event, value)

Function - RCX2

Set the click counter for the event, where event is a constant event number and value can be any expression.
SetClickCounter(2, x);

ClickCounter(event)
Return the current click counter for the specified event number.
x = ClickCounter(2);

Value - RCX2

3.9.2Scout Events
table below. Event Name EVENT_1_PRESSED Condition sensor 1 pressed

Scout

The Scout provides 15 events, each of which has a predefined meaning as shown in the

Page 57

NQC Programmer's Guide EVENT_1_RELEASED EVENT_2_PRESSED EVENT_2_RELEASED EVENT_LIGHT_HIGH EVENT_LIGHT_NORMAL EVENT_LIGHT_LOW EVENT_LIGHT_CLICK EVENT_LIGHT_DOUBLECLICK EVENT_COUNTER_0 EVENT_COUNTER_1 EVENT_TIMER_0 EVENT_TIMER_1 EVENT_TIMER_2 EVENT_MESSAGE sensor 1 released sensor 2 pressed sensor 2 released light sensor "high" light sensor "normal" light sensor "low" low to high to low two clicks counter 0 over limit counter 1 over limit timer 0 over limit timer 1 over limit timer 2 over limit new message received

The first four events are triggered by touch sensors connected to the two sensor ports.
EVENT_LIGHT_HIGH, EVENT_LIGHT_NORMAL, and EVENT_LIGHT_LOW are triggered

by the light sensor's value changing from one range to another. The ranges are defined by SetSensorUpperLimit, SetSensorLowerLimit, and SetSensorHysteresis which were described previously.
EVENT_LIGHT_CLICK and EVENT_LIGHT_DOUBLECLICK are also triggered by the light

sensor. A click is a transition from low to high and back to low within a certain amount of time, called the click time. Each counter has a counter limit. When the counter exceeds this limit,
EVENT_COUNTER_0 or EVENT_COUNTER_1 is triggered. Timers also have a limit, and

they generate EVENT_TIMER_0, EVENT_TIMER_1, and EVENT_TIMER_2.

EVENT_MESSAGE is triggered whenever a new IR message is received.

Page 58

NQC Programmer's Guide

SetSensorClickTime(value)

Function - Scout

Set the click time used to generate events from the light sensor. Value should be specified in increments of 10ms, and may be any expression.
SetSensorClickTime(x);

SetCounterLimit(n, value)

Function - Scout

Set the limit for counter n. N must be 0 or 1, and value may be any expression.
SetCounterLimit(0, 100); // set counter 0 limit to 100

SetTimerLimit(n, value)

Function - Scout

Set the limit for timer n. N must be 0, 1, or 2, and value may be any expression.
SetTimerLimit(1, 100); // set timer 1 limit to 100

3.10 Data Logging

RCX

The RCX contains a datalog which can be used to store readings from sensors, timers, variables, and the system watch. Before adding data, the datalog first needs to be created using the CreateDatalog(size) command. The 'size' parameter must be a constant and determines how many data points the datalog can hold.
CreateDatalog(100); // datalog for 100 points

Values can then be added to the datalog using AddToDatalog(value). When the datalog is uploaded to a computer it will show both the value itself and the source of the value (timer, variable, etc). The datalog directly supports the following data sources: timers, sensor values, variables, and the system watch. Other data types (such as a constant or random number) may also be logged, but in this case NQC will first move the value into a variable and then log the variable. The values will still be captured faithfully in the datalog, but the sources of the data may be a bit misleading.
AddToDatalog(Timer(0)); // add timer 0 to datalog AddToDatalog(x); // add variable 'x' AddToDatalog(7); // add 7 - will look like a variable

The RCX itself cannot read values back out of the datalog. The datalog must be uploaded to a host computer. The specifics of uploading the datalog depend on the NQC Page 59

NQC Programmer's Guide environment being used. For example, in the command line version of NQC, the following commands will upload and print the datalog:
nqc datalog nqc -datalog_full

The Swan (and the standard LEGO firmware version 3.30 which is available via the ROBOLAB software) adds the ability to read values and types out of the datalog. New firmware sources are used to implement this functionality. Use the DatalogType, DatalogValue, and DatalogByte functions to programmatically access these sources.

CreateDatalog(size)

Function - RCX

Create a datalog of the specified size (which must be a constant). A size of 0 clears the existing datalog without creating a new one.
CreateDatalog(100); // datalog for 100 points

AddToDatalog(value)

Function - RCX

Add the value, which may be an expression, to the datalog. If the datalog is full the call has no effect.
AddToDatalog(x);

UploadDatalog(start, count)

Function - RCX

Initiate and upload of count data points beginning at start. This is of relatively little use since the host computer usually initiates the upload.
UploadDatalog(0, 100); // upload entire 100 point log

DatalogType(n)

Value Swan (and RCX2+)

Read or write the 8-bit datalog type specified by the parameter. If a variable is used the type is read or written indirectly.
x = DatalogType(0);

Page 60

NQC Programmer's Guide

DatalogValue(n)

Value Swan (and RCX2+)

Read or write the 16-bit datalog value specified by the parameter. If a variable is used the value is read or written indirectly.
x = DatalogValue(0);

DatalogByte(n)

Value Swan (and RCX2+)

Read or write the 8-bit datalog byte specified by the parameter. If a variable is used the byte is read or written indirectly.
x = DatalogByte(0);

3.11 General Features

Wait(time) Function - All

Make a task sleep for specified amount of time (in 100ths of a second). The time argument may be an expression or a constant:
Wait(100); // wait 1 second Wait(Random(100)); // wait random time up to 1 second

StopAllTasks()

Function - All

Stop all currently running tasks. This will halt the program completely, so any code following this command will be ignored.
StopAllTasks(); // stop the program

Random(n)
Return a random number between 0 and n. N must be a constant.
x = Random(10);

Value - All

SetRandomSeed(n)

Function - RCX2, Spy

Seed the random number generator with n. N may be an expression.

SetRandomSeed(x); // seed with value of x

Page 61

NQC Programmer's Guide

BatteryLevel()
Return the battery level in millivolts.
x = BatteryLevel();

Value - RCX2, Spy

FirmwareVersion()

Value - RCX2, Spy

Return the firmware version as an integer. For example, version 3.2.6 is 326.
x = FirmwareVersion();

SetSleepTime(minutes)

Function - All

Set the sleep timeout the requested number of minutes (which must be a constant). Specifying 0 minutes disables the sleep feature.
SetSleepTime(5); // sleep after 5 minutes SetSleepTime(0); // disable sleep time

SleepNow()

Function - All

Force the device to go to sleep. Only works if the sleep time is non-zero.
SleepNow(); // go to sleep

Indirect(n)

Value - RCX2, Spy

Read the value of a variable indirectly. The parameter is the address of a global variable whose value is the address of the variable you wish to read.
x = Indirect(0); // the value of var pointed to by var 0

SetIndirectVar(const int &v, const int &n)

Value - RCX2, Spy

Set the value of a variable indirectly. The first parameter is the global variable whose value is the address of the variable you wish to set. The second parameter is the value you wish to set it to.
SetIndirectVar(x, 200);

Page 62

NQC Programmer's Guide

3.12 RCX Specific Features

Program()
Number of the currently selected program.
x = Program();

Value - RCX

SelectProgram(n)

Function - RCX2

Select the specified program and start running it. Note that programs are numbered 0-4 (not 1-5 as displayed on the LCD).
SelectProgram(3);

Watch()
Return the value of the system clock in minutes.
x = Watch();

Value - RCX

SetWatch(hours, minutes)

Function - RCX

Set the system watch to the specified number of hours and minutes. Hours must be a constant between 0 and 23 inclusive. Minutes must be a constant between 0 and 59 inclusive.
SetWatch(3, 15); // set watch to 3:15

3.13 Scout Specific Features

SetScoutRules(motion, touch, light, time, fx)
Set the various rules used by the scout in stand-alone mode.

Function - Scout

ScoutRules(n)

Value - Scout

Return current setting for one of the rules. N should be a constant between 0 and 4.
x = ScoutRules(1); // get setting for rule #1

Page 63

NQC Programmer's Guide

SetScoutMode(mode)

Function - Scout

Put the scout into stand-alone (0) or power (1) mode. As a programming call it really only makes sense to put into stand-alone mode since it would already be in power mode to run an NQC program.

SetEventFeedback(events)
Set which events should be accompanied by audio feedback.
SetEventFeedback(EVENT_1_PRESSED);

Function - Scout

EventFeedback()
Return the set of events that have audio feedback.
x = EventFeedback();

Value - Scout

SetLight(mode)

Function - Scout

Control the Scout's LED. Mode must be LIGHT_ON or LIGHT_OFF.

SetLight(LIGHT_ON); // turn on LED

3.14 CyberMaster Specific Features

CyberMaster provides alternate names for the sensors: SENSOR_L, SENSOR_M, and
SENSOR_R. It also provides alternate names for the outputs: OUT_L, OUT_R, OUT_X.

Additionally, the two internal motors have tachometers, which measure 'clicks' and speed as the motors turn. There are about 50 clicks per revolution of the shaft. The tachometers can be used, for example, to create a robot which can detect if it has bumped into an object without using any external sensors. The tachometers have maximum values of 32767 and do not differentiate between directions. They will also count up if the shaft is turned by hand, including when no program is running.

Drive(motor0, motor1)

Function - CM

Turns on both motors at the power levels specified. If a power level is negative, then the motor will run in reverse. Equivalent to this code: Page 64

NQC Programmer's Guide

SetPower(OUT_L, abs(power0)); SetPower(OUT_R, abs(power1)); if(power0 < 0) { SetDirection(OUT_L, OUT_REV) else { SetDirection(OUT_L, OUT_FWD) if(power1 < 0) { SetDirection(OUT_R, OUT_REV) else { SetDirection(OUT_R, OUT_FWD) SetOutput(OUT_L + OUT_R, OUT_ON);

} } } }

OnWait(motors, n time)

Function - CM

Turns on the motors specified, all at the same power level then waits for the given time. The time is in 10ths of a second, with a maximum of 255 (or 25.5 seconds). Equivalent to this code:
SetPower(motors, abs(power)); if(power < 0) { SetDirection(motors, OUT_REV) } else { SetDirection(motors, OUT_FWD) } SetOutput(motors, OUT_ON); Wait( time * 10 );

OnWaitDifferent(motors, n0, n1, n2, time)

Function - CM

Like OnWait(), except different power levels can be given for each motor.

ClearTachoCounter(motors)
Resets the tachometer for the motor(s) specified.

Function - CM

TachoCount(n)
Returns the current value of the tachometer for a specified motor.

Value - CM

TachoSpeed(n)

Value - CM

Returns the current speed of the tachometer for a specified motor. The speed is fairly constant for an unladen motor at any speed, with a maximum value of 90. (This will

Page 65

NQC Programmer's Guide be lower as your batteries lose power!) The value drops as the load on the motor increases. A value of 0 indicates that the motor is stalled.

ExternalMotorRunning()

Value - CM

This is actually a measure of the current being drawn by the motor. The values returned tends to fluctuate slightly, but are, on average, as follows for an unladen motor: 0 1 <=7 motor is floating motor is off motor is running at around this power level. This is where the value

fluctuates the most (probably related to the PWM method used to drive the motors.) In any case, you should know what power level you set the motor to in the first place. The value increases as the load on the motor increases, and a value between 260 and 300 indicates that the motor has stalled.

AGC()

Value - CM

Return the current value of the automatic gain control on the RF receiver. This can be used to give a very rough (and somewhat inaccurate) measure of the distance between the CyberMaster and the RF transmitter.
x = AGC();

3.15 Spybotics Specific Features

SetLED(mode, value) Function - Spy

A single command, SetLED(mode, value), can be used to control all of the different LEDs on the Spybotics brick. The function takes two arguments, a mode and a value. The mode parameter selects which group of LEDs to control, and how they should be affected.

Page 66

NQC Programmer's Guide LED Mode Constants

LED_MODE_ON, LED_MODE_BLINK, LED_MODE_DURATION, LED_MODE_SCALE, LED_MODE_SCALE_BLINK, LED_MODE_SCALE_DURATION, LED_MODE_RED_SCALE, LED_MODE_RED_SCALE_BLINK, LED_MODE_GREEN_SCALE, LED_MODE_GREEN_SCALE_BLINK, LED_MODE_YELLOW, LED_MODE_YELLOW_BLINK, LED_MODE_YELLOW_DURATION, LED_MODE_VLL, LED_MODE_VLL_BLINK, LED_MODE_VLL_DURATION

The meaning of value parameter depends on the mode. Sometimes it is a mask of which LEDs should be controlled (as with LED_MODE_ON). Sometimes it is a single value that is used to determine how many LEDs to turn on (as with
LED_MODE_SCALE).

LED Value Constants

LED_RED1, LED_RED2, LED_RED3, LED_GREEN1, LED_GREEN2, LED_GREEN3, LED_YELLOW, LED_ALL_RED, LED_ALL_GREEN, LED_ALL_RED_GREEN, LED_ALL

Here is a short program that blinks all six of the top red/green LEDs.
task main() { SetLED(LED_MODE_BLINK, LED_ALL_RED_GREEN); Wait(200); }

LED(mode)

Value - Spy

Return the value of the LED control registers. Use the LED Mode constants as the parameter.
x = LED(LED_MODE_ON);

SetAnimation(number)

Function - Spy

A more sophisticated way to control the top LEDs is to use animations. An animation is a sequence of LED patterns. Each pattern is displayed for a certain amount of time, then the next pattern is displayed. Animations are activated using the
SetAnimation(number) function. There are 8 pre-defined animations in ROM.

ROM Animation Constants

ANIMATION_SCAN, ANIMATION_SPARKLE, ANIMATION_FLASH, ANIMATION_RED_TO_GREEN, ANIMATION_GREEN_TO_RED,

Page 67

NQC Programmer's Guide

ANIMATION_POINT_FORWARD, ANIMATION_ALARM, ANIMATION_THINKING

Here is a short program that runs a ROM animation.

task main() { SetAnimation(ANIMATION_SCAN); Wait(200); }

ANIMATION

Resource Declaration - Spy

It is also possible to define custom animations. This is done with a resource declaration (a new NQC feature). The declaration must be done at the global level (not within a task/sub/function), and must occur before the animation is used in the program. An animation declaration looks like this:
ANIMATION name { data ... };

Where name is a name you pick for the animation, and data is a series of bytes that determine the animation's appearance. The data bytes are interpreted in pairs, with the first byte of each pair specifying a mask of the LEDs that should be turned on, and the second byte determining how many 10ms ticks that pattern should be displayed for. A pair of 255,0 causes the animation to loop continuously. You can also use the following two special commands (in a comma-separated list) to define an animation: Animation Commands
AnimateLED(led_mask, time) RepeatAnimation()

Once the animation is declared, its name may be used as an argument to

SetAnimation(). Here is an example: ANIMATION my_animation { AnimateLED(1, 10), AnimateLED(2, 10), AnimateLED(4, 10), AnimateLED(2, 10), RepeatAnimation() }; task main()

Page 68

NQC Programmer's Guide

{ SetAnimation(my_animation); Wait(500); }

AnimateLED(led_mask, time)

Animation Macro - Spy

User animations contain LED patterns. The led_mask parameter is a mask of the LEDs that should be turned on (see the LED value constants defined above). The time parameter is the number of 10 ms steps to display the pattern for, ranging from 1 to 255 (2.55 seconds).
AnimationLED(LED_RED1, 10)

RepeatAnimation()
Repeat the user animation from the beginning.
RepeatAnimation()

Animation Macro - Spy

SOUNDEFFECT

Resource Declaration - Spy

With Spybotics you can define up to 15 of your own sound effects using a resource declaration. The declaration must be done at the global level (not within a task/sub/function), and must occur before the sound effect is used in the program. A sound effect declaration looks like this:
SOUNDEFFECT name { data ... };

Where name is a name you pick for the sound effect, and data is a series of bytes that determine the sound effect sound. Use the following special commands (in a commaseparated list) to define the sound effect. User Sound Effect Commands
Gate(on, period) GateOff() Glide(freq1, freq2, time) Vibrato(freq1, freq2, time) WaitEffect(time) FixedWaitEffect(time) Tone(freq, time) FixedTone(freq, time) RepeatEffect()

Page 69

NQC Programmer's Guide Once the sound effect is declared, its name may be used as an argument to
PlaySound(). Here is an example: SOUNDEFFECT my_effect { Gate(1, 10), Glide(294, 660, 60), GateOff(), WaitEffect(50), Vibrato(294, 660, 60), FixedTone(500, 50), RepeatEffect() }; task main() { PlaySound(my_effect); Wait(500); }

Gate(on, period)

Sound Effect Macro - Spy

User sound effects can be changed by turning the sound on and off rapidly. The on parameter is that portion of the period during which sound is output. The period parameter is the length of the gate cycle in 10 ms steps from 1 to 255 (2.55 seconds).
Gate(1, 10)

GateOff()
Stop gating the sound effect.
GateOff()

Sound Effect Macro - Spy

Glide(frequency1, frequency2, duration)

Sound Effect Macro - Spy

User sound effects can contain sounds which glide from one frequency to another. The two frequency parameters can range from 32 to 20000 Hz. The duration parameter is the time to glide from the first frequency to the second in 10 ms steps from 1 to 255 (2.55 seconds).
Glide(294, 660, 60)

Page 70

NQC Programmer's Guide

Vibrato(frequency1, frequency2, duration)

Sound Effect Macro - Spy

User sound effects can contain vibratos, where the sound alternates rapidly between two frequencies. The two frequency parameters can range from 32 to 20000 Hz. The duration parameter is the number of 10 ms steps from 1 to 255 (2.55 seconds).
Vibrato(294, 660, 60)

WaitEffect(duration)

Sound Effect Macro - Spy

User sound effects can contain wait periods. The duration parameter is the length of the wait in 10 ms steps from 1 to 255 (2.55 seconds).
WaitEffect(60)

FixedWaitEffect(duration)

Sound Effect Macro - Spy

User sound effects can contain fixed wait periods. The duration parameter is the length of the wait in 10 ms steps from 1 to 255 (2.55 seconds). This wait period will be unaffected by adjustments to the sound effect time.
FixedWaitEffect(60)

Tone(frequency, duration)

Sound Effect Macro - Spy

User sound effects can contain simple tones. The frequency parameter is the tone to be played, ranging from 32 to 20000 Hz. The duration parameter is the length of the wait in 10 ms steps from 1 to 255 (2.55 seconds).
Tone(440, 60)

FixedTone(frequency, duration)

Sound Effect Macro - Spy

User sound effects can contain fixed wait periods. The frequency parameter is the tone to be played, ranging from 32 to 20000 Hz. The duration parameter is the length of the wait in 10 ms steps from 1 to 255 (2.55 seconds). This wait period will be unaffected by adjustments to the sound effect sound or time.
FixedTone(440, 60)

Page 71

NQC Programmer's Guide

RepeatEffect()
Repeat the user sound effect from the beginning.
RepeatEffect()

Sound Effect Macro - Spy

EffectSound()
Return the value of the sound effect frequency adjustment register.
x = EffectSound(); // read the sound effect freq adj

Value - Spy

EffectTime()
Return the value of the sound effect time adjustment register.
x = EffectTime(); // read the sound effect time adj

Value - Spy

SetEffectSound(s)

Function - Spy

Set the value of the sound effect frequency adjustment register. The parameter can range from 0 to 255 where 100 = 1.0 * the frequency.
SetEffectSound(50); // cut freq in half (50%)

SetEffectTime(t)

Function - Spy

Set the value of the sound effect time adjustment register. The parameter can range from 0 to 255 where 100 = 1.0 * the duration.
SetEffectTime(50); // cut sound duration in half (50%)

ClearWorld()
Clear the contents of the world relationship table.
ClearWorld(); // empty world table

Function - Spy

FindWorld(v, relationSource, criteria, threshold)

Function - Spy

Sets variable v to the next entry in the world relationship table that matches the criteria specified.
task main() { int v = -1;

Page 72

NQC Programmer's Guide

ClearWorld(); FindWorld(v, SPY_RANGE, REL_GT, RANGE_NOWHERE); while (v != -1) { SetWorldNote(v, 40); SetTargetID(v); FindWorld(v, SPY_RANGE, REL_GT, RANGE_NOWHERE); }

Criteria Constants
REL_GT, REL_LT, REL_EQ, REL_NE

Target(n)

Value - Spy

Return the value from the specified relation source for the current target.
x = Target(SPY_RANGE); // get the target range

Relation Source Constants

SPY_TARGETID, SPY_NOTE, SPY_LINKID, SPY_RANGE, SPY_DIRECTION, SPY_ASPECT, SPY_INFO, SPY_SHORTID

SetTargetID(v)

Function - Spy

Set the current target based on the value of v. Setting the target to TARGET_NONE stops tracking.
int x = 5; SetTargetID(x); // set the target ID

ID Constants
TARGET_NONE, ID_NONE, ID_CTRL1, ID_CTRL2, ID_CTRL3, ID_CTRL4, ID_CTRL5, ID_CTRL6, ID_PC, ID_BOT_MIN, ID_BOT_MAX

SetTargetNote(v)
Set the current target's game note.
SetTargetNote(50); // set the target's note to 50

Function - Spy

GetWorld(relationSource, target, v)

Function - Spy

Set variable v to the value in the relationSource for the specified target.
GetWorld(SPY_RANGE, t, v); // set v to target t's range

GetWorldAspect(t, v)
Set variable v to the specified target's aspect.

Function - Spy

Page 73

NQC Programmer's Guide

GetWorldAspect(t, v); // set v to target t's aspect

Aspect Constants
ASPECT_FRONT_LEFT, ASPECT_FRONT, ASPECT_FRONT_RIGHT, ASPECT_BACK_RIGHT, ASPECT_BACK, ASPECT_BACK_LEFT

GetWorldDirection(t, v)

Function - Spy

Set variable v to the value in the relationSource for the specified target.
GetWorldDirection(t, v); // set v to target t's direction

Direction Constants
DIRECTION_LEFT, DIRECTION_LEFT_OF_CENTER, DIRECTION_CENTER, DIRECTION_RIGHT_OF_CENTER, DIRECTION_RIGHT

GetWorldLinkID(t, v)
Set variable v to the specified target's link ID.

Function - Spy

GetWorldLinkID(t, v); // set v to target t's link ID

GetWorldNote(t, v)
Set variable v to the specified target's note.
GetWorldNote(t, v); // set v to target t's note

Function - Spy

GetWorldRange(t, v)
Set variable v to the specified target's range.
GetWorldRange(t, v); // set v to target t's range

Function - Spy

Range Constants
RANGE_NOWHERE, RANGE_ANYWHERE, RANGE_THERE, RANGE_HERE

GetWorldShortID(t, v)
Set variable v to the specified target's short ID.

Function - Spy

GetWorldShortID(t, v); // set v to target t's short ID

SetWorldNote(t, v)
Set the specified target's note to the value v.
SetWorldNote(t, v); // set target t's note

Function - Spy

Page 74

NQC Programmer's Guide

Pop(n)
Pop n entries off the stack.
Pop(2); // pop 2 entries off the stack

Function - Spy

Push(v)
Push a value onto the stack

Function - Spy

Push(v); // push the contents of variable v onto the stack

Stack(index)
Return the value at the specified stack index.
x = Stack(0); // set x to first stack entry

Value - Spy

SetStack(index, v)
Set the stack entry specified by index to the value v.
SetStack(0, 4); // set the first stack entry to 4

Function - Spy

TimerState(n)
Return the current running state of timer n.
x = TimerState(0); // set x to timer 0's state

Value - Spy

SetTimerState(n, s)
Set the running state of the specified timer.
SetTimerState(0, TIMER_STOPPED); // stop timer 0

Function - Spy

State Constants
TIMER_RUNNING, TIMER_STOPPED

EEPROM(n)

Value - Spy

Return the value stored at the EEPROM location specified by index (either directly or indirectly.
x = EEPROM(10); // read contents of EEPROM location 10

Page 75

NQC Programmer's Guide

SetEEPROM(i, d)

Function - Spy

Set the EEPROM location specified by index (directly or indirectly) to the value d.
SetEEPROM(0, 5); // set EEPROM location 0 to 5 int i = 3; SetEEPROM(i, TimerState(0)); // set EEPROM location 3

CurrentTaskID()
Return the current task ID.
x = CurrentTaskID(); // read current task ID

Value - Spy

RxMessageLock()
Return the receive buffer locking value.

Value - Spy

x = RxMessageLock(); // read the message locking value

SetRxMessageLock(lock)

Function - Spy

Set the receive buffer locking value. To lock both IR and PC buffers use MSG_IR+MSG_PC.
SetRxMessageLock(MSG_IR); // lock the IR message buffer

Receive Message Locking Constants

MSG_NONE, MSG_IR, MSG_PC

RxMessageIndex()
Return the index for the latest NewEntry event.
x = RxMessageIndex();

Value - Spy

RxMessageChannel()
Return the channel containing the latest received message.
x = RxMessageChannel();

Value - Spy

RxMessageID(channel)

Value - Spy

Extract an ID from a received IR or PC message and convert it into an index. The desired channel is MSG_IR or MSG_PC. Page 76

NQC Programmer's Guide

x = RxMessageID(MSG_IR);

RxMessage(channel, byte)

Value - Spy

Read the contents of a received IR or PC message (4 bytes total). The desired channel is MSG_IR or MSG_PC. The desired byte is specified using MSG_INDEX, MSG_COMMAND, MSG_HI_BYTE, or MSG_LO_BYTE.
if (RxMessage(MSG_IR, MSG_COMMAND) == COMMAND_CONTROLLER) { x = RxMessage(MSG_IR, MSG_HI_BYTE); }

PingControl(n)
Return the value of the ping control registers (n = 0..2).
x = PingControl(1); // read the current ping interval

Value - Spy

PingData()
Return the current 8 bit information for ping messages
x = PingData();

Value - Spy

SetPingData(d)
Set the 8 bit information for ping messages.
SetPingData(55); // send the value 55 when pinging

Function - Spy

PingInterval()
Return the current ping interval.
x = PingInterval();

Value - Spy

SetPingInterval(interval)

Function - Spy

Set the ping interval in 10ms steps. Setting the interval to zero will disable pinging.
SetPingInterval(0); // disable pings

PingID()
Return the Spybotics ping ID number.

Value - Spy

Page 77

NQC Programmer's Guide

x = PingID(); // x = my ping ID

BeaconControl(n)
Return the value of the beacon control registers (n = 0..3).
x = BeaconControl(1); // read the RC receive channel

Value - Spy

LinkID()
Return the link ID (0-7; 0 = no link, 1-6 control unit ID, 7 = PC).
x = LinkID(); // read link ID

Value - Spy

ID Constants
ID_NONE, ID_CTRL1, ID_CTRL2, ID_CTRL3, ID_CTRL4, ID_CTRL5, ID_CTRL6, ID_PC

RCRxChannel()
Return the RC receive channel.
x = RCRxChannel(); // read RC receive channel

Value - Spy

SetRCRxChannel(channel)
Set the RC receive channel.
SetRCRxChannel(RC_CHANNEL_1);

Function - Spy

RC Channel Constants RC_CHANNEL_BROADCAST, RC_CHANNEL_1, RC_CHANNEL_2, RC_CHANNEL_3, RC_CHANNEL_DISABLED

RCTxChannel()
Return the RC transmit channel.
x = RCTxChannel(); // read RC transmit channel

Value - Spy

SetRCTxChannel(channel)
Set the RC transmit channel.
SetRCTxChannel(RC_CHANNEL_1);

Function - Spy

RCTxMode()
Return the current RC transmit mode.

Value - Spy

Page 78

NQC Programmer's Guide

x = RCTxMode(); // read RC transmit mode

SetRCTxMode(mode)
Set the RC transmit mode.
SetRCTxMode(RCTXMODE_SINGLE_SHOT);

Function - Spy

RC Tx Mode Constants
RCTXMODE_SINGLE_SHOT, RCTXMODE_CONTINUOUS

StartTask(task)
Start a task by numeric value rather than by name.
StartTask(9); // start task number 9

Function - Spy

StopTask(task)
Stop a task by numeric value rather than by name.
StopTask(9); // stop task number 9

Function - Spy

Action(nSound, nDisplay, nMovement, nRepeat, nTime) Function - Spy

Built-in ROM subroutine number 44. This subroutine plays any combination of sound, LED animation, and movement, like a multimedia presentation. nSound is the sound to play (0-79, -1 means no sound). nDisplay is the LED animation to play (015, -1 means no animation). nMovement is the Spybot motion (see BasicMove, FancyMove, RandomMove, SlowDownMove, and SpeedUpMove) with -1 meaning no movement. nRepeat is the number of times to repeat the motion. nTime is the time to wait if nMovement equals -1, otherwise it is passed on to the movement subroutines.
Action(SOUND_GEIGER, ANIMATION_FLASH, -1, 0, 300);

Disp(display)

Function - Spy

Built-in ROM subroutine number 42. This subroutine displays one of the LED animations. Passing an undefined user animation will turn the display off (8-15).
Disp(ANIMATION_FLASH);

Page 79

NQC Programmer's Guide

BasicMove(move, time)

Function - Spy

Built-in ROM subroutine number 43. This subroutine performs the requested motion for the specified duration. The motors are not floated or braked and motor power is not restored on exit.
BasicMove(MOVE_BASIC_AVOID_LEFT, 500);

Basic Motion Constants

MOVE_BASIC_FORWARD, MOVE_BASIC_BACKWARD, MOVE_BASIC_SPIN_LEFT, MOVE_BASIC_SPIN_RIGHT, MOVE_BASIC_TURN_LEFT, MOVE_BASIC_TURN_RIGHT, MOVE_BASIC_AVOID_LEFT, MOVE_BASIC_AVOID_RIGHT, MOVE_BASIC_REST, MOVE_BASIC_STOP

FancyMove(move, time)

Function - Spy

Built-in ROM subroutine number 47. This subroutine performs the requested motion for the specified duration. The motors are not floated or braked and motor power is not restored on exit.
FancyMove(MOVE_FANCY_ZIGZAG, 500);

Fancy Motion Constants

MOVE_FANCY_ZIGZAG, MOVE_FANCY_SHAKE, MOVE_FANCY_SCAN, MOVE_FANCY_STEP, MOVE_FANCY_STEP_BACK, MOVE_FANCY_SEARCH, MOVE_FANCY_FAKE_LEFT, MOVE_FANCY_RAKE_RIGHT, MOVE_FANCY_BUG_FORWARD, MOVE_FANCY_LAZY, MOVE_FANCY_WALK, MOVE_FANCY_WALK_BACK, MOVE_FANCY_DANCE

RandomMove(move, time)

Function - Spy

Built-in ROM subroutine number 46. This subroutine performs the requested motion for the specified duration. The motors are not floated or braked and motor power is not restored on exit.
RandomMove(MOVE_RANDOM_FORWARD, 500);

Random Motion Constants

Page 80

NQC Programmer's Guide

MOVE_RANDOM_FORWARD, MOVE_RANDOM_BACKWARD, MOVE_RANDOM_SPIN_LEFT, MOVE_RANDOM_SPIN_RIGHT, MOVE_RANDOM_TURN_LEFT, MOVE_RANDOM_TURN_RIGHT, MOVE_RANDOM_REST

SlowDownMove(move, time)

Function - Spy

Built-in ROM subroutine number 48. This subroutine performs the requested motion for the specified duration. The motors are not floated or braked and motor power is not restored on exit.
SlowDownMove(MOVE_SLOWDOWN_FORWARD, 500);

SlowDown Motion Constants

MOVE_SLOWDOWN_FORWARD, MOVE_SLOWDOWN_BACKWARD, MOVE_SLOWDOWN_SPIN_LEFT, MOVE_SLOWDOWN_SPIN_RIGHT

SpeedUpMove(move, time)

Function - Spy

Built-in ROM subroutine number 49. This subroutine performs the requested motion for the specified duration. The motors are not floated or braked and motor power is not restored on exit.
SpeedUpMove(MOVE_SPEEDUP_FORWARD, 500);

SpeedUp Motion Constants

MOVE_SPEEDUP_FORWARD, MOVE_SPEEDUP_BACKWARD, MOVE_SPEEDUP_SPIN_LEFT, MOVE_SPEEDUP_SPIN_RIGHT

Sum2Mem(mem, value)

Function - Spy

Built-in ROM subroutine number 50. This subroutine adds value to a 2-byte location in EEPROM. The value is stored low byte first. No overflow checking is performed.
Sum2Mem(50, 400);

Sum4Mem(mem, value)

Function - Spy

Built-in ROM subroutine number 51. This subroutine adds value to a 4-byte location in EEPROM. The value is stored least significant byte first. No overflow checking is performed.
Sum4Mem(50, 400);

Page 81

NQC Programmer's Guide

SendAllRangeMessage (nMessage, nData)

Function - Spy

Built-in ROM subroutine number 38. This subroutine sends nMessage to all Spybots in the world relation table that are in the here, there, or anywhere zones with the actual Spybot range as the high byte of each message.
SendAllRangeMessage(50, 40);

SendRCXMessage (nMessage)

Function - Spy

Built-in ROM subroutine number 37. This subroutine sends an RCX message at 2400 baud with bi-phase encoding and sum checksum. These messages can be received by an RCX or Scout.
SendRCXMessage(50);

SendSpybotMessage(nIndex, nCmd, nHiByte, nLoByte) Function - Spy

Built-in ROM subroutine number 34. This subroutine sends a message to a Spybot. If nIndex is a controller or PC then it does nothing. nIndex is the index of the Spybot in the world relation table (0-15), INDEX_LINKCAST, or INDEX_BROADCAST.
SendSpybotMessage(INDEX_LINKCAST, 50, 0, 10);

3.16 Swan Specific Features

SetMotorPowerSigned(const int motor, const int &v)
Set the power of a motor to the specified signed value.
SetMotorPowerSigned(MTR_A, 10);

Function - Swan

The motor can be specified using the following constants. Motor Constant MTR_A MTR_B MTR_C MTR_D MTR_E MTR_F Meaning output A output B output C virtual output D virtual output E virtual output F Page 82

NQC Programmer's Guide There are additional constants for the motor power functions and values. Motor Power Direction MPD_FWD MPD_REV MPD_FLOAT MPD_OFF Motor State MS_FLOAT MS_BRAKE MS_FWD MS_REV Motor Forward Power MTR_FWD_POWER_1 MTR_FWD_POWER_2 MTR_FWD_POWER_3 MTR_FWD_POWER_4 MTR_FWD_POWER_5 MTR_FWD_POWER_6 MTR_FWD_POWER_7 MTR_FWD_POWER_8 Motor Reverse Power MTR_REV_POWER_1 MTR_REV_POWER_2 MTR_REV_POWER_3 MTR_REV_POWER_4 MTR_REV_POWER_5 MTR_REV_POWER_6 MTR_REV_POWER_7 MTR_REV_POWER_8 Motor Float Power MTR_FLOAT_POWER_1 MTR_FLOAT_POWER_2 MTR_FLOAT_POWER_3 MTR_FLOAT_POWER_4 MTR_FLOAT_POWER_5 MTR_FLOAT_POWER_6 MTR_FLOAT_POWER_7 MTR_FLOAT_POWER_8 Meaning foward reverse float off Meaning float state brake state forward state reverse state Meaning forward at power level 1 forward at power level 2 forward at power level 3 forward at power level 4 forward at power level 5 forward at power level 6 forward at power level 7 forward at power level 8 Meaning reverse at power level 1 reverse at power level 2 reverse at power level 3 reverse at power level 4 reverse at power level 5 reverse at power level 6 reverse at power level 7 reverse at power level 8 Meaning float at power level 1 float at power level 2 float at power level 3 float at power level 4 float at power level 5 float at power level 6 float at power level 7 float at power level 8

Motor Brake Power Meaning MTR_BRAKE_POWER_1 brake at power level 1 MTR_BRAKE_POWER_2 brake at power level 2 Page 83

NQC Programmer's Guide MTR_BRAKE_POWER_3 MTR_BRAKE_POWER_4 MTR_BRAKE_POWER_5 MTR_BRAKE_POWER_6 MTR_BRAKE_POWER_7 MTR_BRAKE_POWER_8 brake at power level 3 brake at power level 4 brake at power level 5 brake at power level 6 brake at power level 7 brake at power level 8

MotorPowerSigned(const int motor)

Read the signed power setting of a motor.
x = MotorPowerSigned(MTR_A);

Value - Swan

SetMotorBrakePower(const int motor, const int &v)

Set the brake power of a motor to the specified value.
SetMotorBrakePower(MTR_A, 10);

Function - Swan

MotorBrakePower(const int motor)

Read the brake power setting of a motor.
x = MotorBrakePower(MTR_A);

Value - Swan

SetMotorPower8(const int motor, const int &v)

Function - Swan

Set the power of a motor to the specified value (using a scale from 0 to 7).
SetMotorPower8(MTR_A, 7);

MotorPower8(const int n)
Read the power setting of a motor (using a scale from 0 to 7).
x = MotorPower8(MTR_A);

Value - Swan

SetMotorPower128(const int motor, const int &v)

Function - Swan

Set the power of a motor to the specified value (using a scale from 0 to 127).
SetMotorPower128(MTR_A, 100);

MotorPower128(const int n)
Read the power setting of a motor (using a scale from 0 to 127).
x = MotorPower128(MTR_A);

Value - Swan

Page 84

NQC Programmer's Guide

SetEventType(const int n, const int &v)

Set the event type of event n to the type specified by v.
SetEventType(MyEvent, EVENT_TYPE_PRESSED);

Function - Swan

EventType(const int n)
Read the event type of an event.
x = EventType(MyEvent);

Value - Swan

SetEventSrc(const int n, const int &v)

Set the event source of event n to the source specified by v.
SetEventSrc(MyEvent, EST_SENSOR_1);

Function - Swan

Event Source EST_SENSOR_1 EST_SENSOR_2 EST_SENSOR_3 EST_TIMER_1 EST_TIMER_2 EST_TIMER_3 EST_TIMER_4 EST_LAST_IR_MSG EST_COUNTER_1 EST_COUNTER_2 EST_COUNTER_3 EST_USER_EVENT_0 EST_USER_EVENT_1 EST_USER_EVENT_2 EST_USER_EVENT_3 EST_USER_EVENT_4 EST_VIRTUAL_MOTOR EST_VIRTUAL_SENSOR EST_WAIT_FOR_MSG EST_INFRARED_STATUS EST_SENSOR_UNUSED

Meaning sensor 1 source sensor 2 source sensor 3 source timer 1 source timer 2 source timer 3 source timer 4 source IR msg source counter 1 source counter 2 source counter 3 source user event source user event source user event source user event source user event source virtual motor source virtual sensor source IR msg source IR msg source sensor source

EventSrc(const int n)
Read the event source of an event.
x = EventSrc(MyEvent);

Value - Swan

There are also constants for event states Page 85

NQC Programmer's Guide Event Source ES_BELOW_LOWER ES_BETWEEN ES_ABOVE_UPPER ES_UNDETERMINED Meaning below lower threshold between lower and upper thresholds above upper threshold undetermined state

SetEventCounts(const int n, const int &v)

Set the event count of event n to the count specified by v.
SetEventCounts(MyEvent, 10);

Function - Swan

EventCounts(const int n)
Read the event counts of an event.
x = EventCounts(MyEvent);

Value - Swan

ResetMSTimer(const int n)
Set the specified 1 ms timer back to zero.
ResetMSTimer(T1);

Function - Swan

MSTimer(const int n)
Read the specified 1 ms timer value.
x = MSTimer(T1); // get the value of timer 1

Value - Swan

WaitMS(const int &v)

Wait for the specified number of milliseconds.
WaitMS(T1);

Function - Swan

System(const int n)
Read the specified system value.

Value - Swan

x = System(SYS_BATTERY_LEVEL); // get the system value

SetSystem(const int n, const int &v)

Set the system item to the specified value.
SetSystem(SYS_OPCODES_PER_TIMESLICE, 10);

Function - Swan

Page 86

NQC Programmer's Guide System Constants SYS_BATTERY_LEVEL SYS_DEBUG_TASK_MODE SYS_MEMORY_MAP_ADDRESS SYS_CURRENT_TASK SYS_SERIAL_LINK_STATUS SYS_OPCODES_PER_TIMESLICE SYS_MOTOR_TRANSITION_DELAY SYS_SENSOR_REFRESH_RATE SYS_EXPANDED_RC_MESSAGES SYS_LCD_REFRESH_RATE SYS_NO_POWER_DOWN_ON_AC SYS_DEFAULT_TASK_STACK_SIZE SYS_TASK_ACQUIRE_PRIORITY SYS_TRANSMITTER_RANGE SYS_FLOAT_DURING_INACTIVE_PWM SYS_ROT_ERRORS_COUNT SYS_ROT_DEBOUNCED_GLITCHES SYS_PREAMBLE_SIZE SYS_UNSOLICITED_MESSAGE SYS_EXPANDED_SUBROUTINES SYS_POWER_DOWN_DELAY SYS_WATCH_FORMAT SYS_SENSOR_MISSED_CONVERSIONS SYS_IGNORE_MESSAGES_CPU SYS_COMM_ERRORS_TIMEOUT SYS_COMM_ERRORS_PARITY SYS_COMM_ERRORS_FRAMING SYS_COMM_ERRORS_OVERRUN SYS_INTER_CHAR_TIMEOUT SYS_TASK_SCHEDULING_PRIORITY SYS_VOLUME SYS_SOUND_PLAYING SYS_PLAY_SOUNDS SYS_QUEUED_SOUND_COUNT SYS_SENSOR_STARTUP_DELAY SYS_SENSOR_DELAY_CYCLES SYS_SENSOR_REFRESH_STATE SYS_SENSOR_SCAN_COUNT SYS_DATALOG_SIZE Meaning battery level debug task mode memory map address current task serial link status opcodes per timeslice motor transition delay sensor refresh rate expanded remote control messages LCD refresh rate power down while on AC default task size task acquire priority transmitter range float motors during inactive PWM rotation sensor errors count rotation sensor debounce glitches preamble size unsolicited messages expanded subroutines power down delay watch format sensor missed conversions ignore messages CPU count of timeout errors count of parity errors count of framing errors count of overrun errors inter-character timeout task scheduling priority volume level sound playing state enable/disable sound playing count of sounds waiting to be played sensor startup delay sensor delay cycles sensor refresh state sensor scan count datalog size

ImmediateBatteryLevel()
Read the immediate battery level.

Value - Swan

Page 87

NQC Programmer's Guide

x = ImmediateBatteryLevel();

DebugTaskMode()
Read the debug task mode.
x = DebugTaskMode();

Value - Swan

MemoryMapAddress()
Read the memory map address.
x = MemoryMapAddress();

Value - Swan

CurrentTask()
Read the current task number.
x = CurrentTask();

Value - Swan

SerialLinkStatus()
Read the serial link status.
x = SerialLinkStatus();

Value - Swan

Serial Link Status Constants SLS_WAIT_FOR_MSG SLS_RECEIVING_MSG SLS_TRANSMITTING SLS_UNKNOWN

Meaning waiting for message receiving message transmitting unknown

OpcodesPerTimeslice()
Read the number of opcodes to execute per timeslice.
x = OpcodesPerTimeslice();

Value - Swan

SetOpcodesPerTimeslice(const int &v)

Set the system item to the specified value.
SetOpcodesPerTimeslice(10);

Function - Swan

MotorTransitionDelay()

Value - Swan

Read the number of milliseconds to delay when changing motor direction. Page 88

NQC Programmer's Guide

x = MotorTransitionDelay();

SetMotorTransitionDelay(const int &v)

Set the motor transition delay to the specified value.
SetMotorTransitionDelay(10);

Function - Swan

SensorRefreshRate()
Read the sensor refresh rate.
x = SensorRefreshRate();

Value - Swan

SetSensorRefreshRate(const int &v)

Set the sensor refresh rate to the specified value.
SetSensorRefreshRate(10);

Function - Swan

ExpandedRemoteMessages()

Value - Swan

Read a boolean value indicating whether or not to support expanded remote control messages.
x = ExpandedRemoteMessages(); // 0 or 1

SetExpandedRemoteMessages(const int &v)

Enable or disable expanded remote control messages.
SetExpandedRemoteMessages(false);

Function - Swan

LCDRefreshRate()
Read the LCD refresh rate.
x = LCDRefreshRate();

Value - Swan

SetLCDRefreshRate(const int &v)

Set the LCD refresh rate.
SetLCDRefreshRate(10);

Function - Swan

Page 89

NQC Programmer's Guide

NoPowerDownOnAC()

Value - Swan

Read a boolean value specifying whether or not to power down while running on AC power.
x = NoPowerDownOnAC();

SetNoPowerDownOnAC(const int &v)

Enable or disable power down while running on AC power.
SetNoPowerDownOnAC(false);

Function - Swan

DefaultStackSize()
Read the default stack size.
x = DefaultStackSize();

Value - Swan

SetDefaultStackSize(const int &v)

Set the default stack size.
SetDefaultStackSize(10);

Function - Swan

TaskAcquirePriority()
Read the task acquire priority level.
x = TaskAcquirePriority();

Value - Swan

SetTaskAcquirePriority(const int &v)

Set the task acquire priority level.
SetTaskAcquirePriority(10);

Function - Swan

TransmitterRange()
Read the transmitter range value.
x = TransmitterRange();

Value - Swan

Page 90

NQC Programmer's Guide

FloatDuringInactivePWM()

Value - Swan

Read a boolean value specifying whether or not to float motors during inactive pulse width modulation.
x = FloatDuringInactivePWM();

SetFloatDuringInactivePWM(const int &v)

Function - Swan

Enable or disable floating the motors during inactive pulse width modulation.
SetFloatDuringInactivePWM(false);

RotErrorsCount()
Read the rotation sensor errors count.
x = RotErrorsCount();

Value - Swan

RotDebouncedGlitches()
Read the rotation sensor debounced glitches.
x = RotDebouncedGlitches();

Value - Swan

SystemPreambleSize()
Read the system preamble size.
x = SystemPreambleSize();

Value - Swan

SetSystemPreambleSize(const int &v)

Set the system preamble size.
SetSystemPreambleSize(10);

Function - Swan

UnsolicitedMessages()

Value - Swan

Read a boolean value specifying whether or not to accept unsolicted messages.

x = UnsolicitedMessages();

Page 91

NQC Programmer's Guide

ExpandedSubroutines()

Value - Swan

Read a boolean value specifying whether or not to allow an expanded number of subroutines.
x = ExpandedSubroutines();

SetExpandedSubroutines(const int &v)

Function - Swan

Enable or disable support for an expanded number of subroutines.

SetExpandedSubroutines(false);

PowerDownDelay()
Read the power down delay.
x = PowerDownDelay();

Value - Swan

WatchFormat()
Read the watch format.
x = WatchFormat();

Value - Swan

SetWatchFormat(const int &v)

Set the watch format.
SetWatchFormat(10);

Function - Swan

Watch Format Constants FMT_HHMM FMT_MMSS FMT_MSSTENTHS

Meaning hours and minutes minutes and seconds minutes, seconds, and tenths of seconds

MissedSensorADConversions()
Read the number of missed sensor analog to digital conversions.
x = MissedSensorADConversions();

Value - Swan

IgnoreMessagesCPU()

Value - Swan

Read a boolean value specifying whether or not to ignore CPU messages.

x = IgnoreMessagesCPU();

Page 92

NQC Programmer's Guide

CommErrorsTimeout()
Read the number of communication timeout errors.
x = CommErrorsTimeout();

Value - Swan

CommErrorsParity()
Read the number of communication parity errors.
x = CommErrorsParity();

Value - Swan

CommErrorsFraming()
Read the number of communication framing errors.
x = CommErrorsFraming();

Value - Swan

CommErrorsOverrun()
Read the number of communication overrun errors.
x = CommErrorsOverrun();

Value - Swan

InterCharTimeout()
Read the inter-character timeout value.
x = InterCharTimeout();

Value - Swan

SetInterCharTimeout(const int &v)

Set the inter-character timeout value.
SetInterCharTimeout(10);

Function - Swan

TaskSchedulingPriority()
Read the task scheduling priority.
x = TaskSchedulingPriority();

Value - Swan

SetTaskSchedulingPriority(const int &v)

Set the task scheduling priority.
SetTaskSchedulingPriority(10);

Function - Swan

Page 93

NQC Programmer's Guide

Volume()
Read the system volume level.
x = Volume();

Value - Swan

SetVolume(const int &v)

Function - Swan

Set the system volume level. The maximum volume level is MAX_VOLUME.
SetVolume(10);

SoundActive()

Value - Swan

Read a boolean value specifying whether or not a sound is currently playing.

x = SoundActive();

PlaySounds()

Value - Swan

Read a boolean value specifying whether or not to allow sound playing.

x = PlaySounds();

SetPlaySounds(const int &v)

Enable or disable support for playing sounds.
SetPlaySounds(false);

Function - Swan

QueuedSoundCount()
Read the number of sounds currently waiting to be played.
x = QueuedSoundCount();

Value - Swan

SensorStartupDelay()
Read the sensor startup delay.
x = SensorStartupDelay();

Value - Swan

SetSensorStartupDelay(const int &v)

Set the sensor startup delay.
SetSensorStartupDelay(10);

Function - Swan

Page 94

NQC Programmer's Guide

SensorDelayCycles()
Read the number of sensor delay cycles.
x = SensorDelayCycles();

Value - Swan

SensorRefreshState()
Read the sensor refresh state.
x = SensorRefreshState();

Value - Swan

SensorScanCount()
Read the sensor scan count.
x = SensorScanCount();

Value - Swan

DatalogSize()
Read the datalog size.
x = DatalogSize();

Value - Swan

IntrinsicIndGlobal(const int n)
Access the value of an intrinsic indirectly.
x = IntrinsicIndGlobal(15);

Value - Swan

GlobalVar(const int &n)

Value - Swan

Read or write the value of a global variable (either directly or indirectly).

x = GlobalVar(y);

StackAddress(const int task)

Read the stack address of the specified task.
x = StackAddress(1);

Value - Swan

StackSize(const int task)

Read the size of the stack for the specified task.
x = StackSize(1);

Value - Swan

Page 95

NQC Programmer's Guide

ClearAll(const int &v)

Function - Swan

Clear the specified items. The constants can be added together to clear multiple items at once.
ClearAll(CLR_TIMERS);

ClearAll Constants CLR_TIMERS CLR_INPUTS CLR_VARIABLES CLR_TASK_STACK CLR_EVENTS CLR_BREAKPOINTS CLR_DATALOG

Meaning clear all timers clear all inputs clear all variables clear all task stacks clear all events clear all breakpoints clear the datalog

BitSet(const int &result, const int &operand)

Set the bit in the result specified by the operand.
BitSet(x, 0x01);

Function - Swan

BitClear(const int &result, const int &operand)

Clear the bit in the result specified by the operand.
BitClear(x, 0x01);

Function - Swan

Negate(const int &result, const int &operand)

Negate the bits in the result specified by the operand.
Negate(x, 0x01);

Function - Swan

Page 96

NQC Programmer's Guide

4 Technical Details
This section explains some of the low-level features of NQC. In general, these mechanisms should only be used as a last resort since they may change in future releases. Most programmers will never need to use the features described below - they are mainly used in the creation of the NQC API file.

4.1

The asm statement

The asm statement is used to define almost all of the NQC API calls. The syntax of the statement is:
asm { item1, item2 ... itemN }

Where an item is one of the following

constant_expression $ expression $ expression : restrictor

The statement simply emits the values of each of the items as raw bytecodes. Constant items are the simplest - they result in a single byte of raw data (the lower 8 bits of the constant value). For example, the API file defines the following inline function:
void ClearMessage() { asm { 0x90 }; }

Whenever ClearMessage() is called by a program, the value 0x90 is emitted as a bytecode. Many API functions take arguments, and these arguments must be encoded into an appropriate effective address for the bytecode interpreter. In the most general case, an effective address contains a source code followed by a two byte value (least significant byte first). Source codes are explained in the SDK documentation available from LEGO. However, it is often desirable to encode the value in some other manner - for example to use only a single byte value after the source code, omit the source code itself, or only allow certain sources to be used. A restrictor may be used to control how the effective address is formatted. A restrictor is a 32 bit constant value. The lower 24 bits form a bitmask indicating which sources are valid (bit 0 should be set to allow source 0, etc). Page 97

NQC Programmer's Guide The upper 8 bits include formatting flags for the effective address. Note that when no restrictor is specified, this is the same as using a restrictor of 0 (no restriction on sources, and a format of source followed by two value bytes). The API file defines the following constants which can be used to build restrictors:
#define __ASM_SMALL_VALUE #define __ASM_NO_TYPE #define __ASM_NO_LOCAL 0x01000000 0x02000000 0x04000000

#if __RCX==2 // no restriction #define __ASM_SRC_BASIC #define __ASM_SRC_EXT #else #define __ASM_SRC_BASIC #define __ASM_SRC_EXT #endif 0x000005 0x000015 0 0

The __ASM_SMALL_VALUE flag indicates that a one-byte value should be used instead of a two-byte value. The __ASM_NO_TYPE flag indicates that the source code should be omitted. The __ASM_NO_LOCAL flag specifies that local variables are not a legal source for the expression. Note that the RCX2 firmware is less restrictive than the other interpreters, thus the definition of __ASM_SRC_BASIC and __ASM_SRC_EXT are relaxed in the RCX2 case. The API definition file for NQC contains numerous examples of using restrictors within asm statement. If you are using a command-line version of NQC, you can emit the API file by typing the following command:
nqc -api

4.2

Data Sources

The bytecode interpreters use different data sources to represent the various kinds of data (constants, variables, random numbers, sensor values, etc). The specific sources depend

Page 98

NQC Programmer's Guide to a certain extent on which device you are using and are described in the SDK documentation available from LEGO. NQC provides a special operator to represent a data source:
@ constant

The value of this expression is the data source described by the constant. The lower 16 bits of the constant represent the data value, and the next 8 bits are the source code. For example, the source code for a random number is 4, so the expression for a random number between 0 and 9 would be:
@0x40009

The NQC API file defines a number of macros which make the use of the @ operator transparent to the programmer. For example, in the case of random numbers:
#define Random(n) @(0x40000 + (n))

Note that since source 0 is the global variable space, the global storage locations can be referenced by number: @0 refers to storage location 0. If for some reason you need explicit control over where variables are being stored, then you should use #pragma
reserve to instruct NQC not to use those storage locations, and then access them

manually with the @ operator. For example, the following code snippet reserves location 0 and creates a macro for it called x.
#pragma reserve 0 #define x (@0)

Because of how sensors have been implemented it is necessary to convert the sensor's data source into a sensor index for use in macros such as SensorValueRaw(). The __sensor expression can be used to do this:
#define SensorValueRaw(n) @(0xc0000 + (__sensor(n)))

Page 99