Version 2.1 rev 1, written by Dave Baum

NQC stands for Not Quite C, and is a simple language for programming the LEGO RCX. 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 standard RCX firmware.

Although NQC was created specifically for the RCX, there still is a logical separation between the NQC language and the RCX API used to control the RCX. This division tends to get blurred is a few special cases such as multi-tasking support. In general, the compiler implements the language, and a special NQC file defines the RCX API in terms of the primitives of the language itself.

This document describes the NQC language and the RCX 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 an 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://www.enteract.com/~dbaum/nqc

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:

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

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

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:

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.

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.

Identifiers are used for variable, task, and function names. The first character of an identifier must be an upper or lower case letter or the underscore ('_'). Remaining characters may be letters, numbers, 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:

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.

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:

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. A program may also contain up to 9 additional tasks.

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 an RCX API command, StopAllTasks, which stops all currently running tasks.

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:

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 in the RCX are represented as 16 bit signed integers. However NQC supports four different argument types which correspond to different argument passing semantics and restrictions:

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.

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.

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:

The last 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 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:

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:

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.

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 RCX, subroutines have some significant restrictions. First of all, subroutines cannot use any arguments. Second, a subroutine cannot call another subroutine. Last, a maximum of 8 subroutines may be defined in a program. In addition, if the subroutine is called from multiple tasks then it cannot have any local variables (or temporary variables). These significant restrictions make subroutines less desirable than inline 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:

All variables in the RCX are of the same type - specifically 16 bit signed integers. The RCX supports up to 32 such variables. This pool of variables is utilized by NQC in several different ways. Variables are declared using the int keyword followed by a comma separated list of variable names 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:

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:

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 available variables in the RCX. NQC attempts to be as efficient as possible with temporary variables (including reusing them when possible).

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

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:

where variables is a comma separated list of names with optional initial values:

Once declared, variables may be assigned the value of an 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

Some examples:

The simplest control structure is a compound statement. This is a list of statements enclosed within curly braces ('{' and '}'):

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.

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.

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:

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

A variant of the while loop is the do-while loop. Its syntax is:

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.

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

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:

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

A typical switch statement might look like this:

NQC also defines the until macro which provides a convenient alternative to the while loop. The actual definition of until is:

In other words, until will continue looping until the condition becomes true. It is most often used in conjunction with an empty body statement:

A function (or subroutine) call is a statement of the form:

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:

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.

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

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.

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

In C there is no distinction between expressions and conditions. However, within NQC they are two syntactically different entities. The legal operations for expressions cannot be used on conditions and vice versa.

Expressions can be assigned to variables, used as arguments in a function, or as the count in a repeat statement. Conditions are used in most of the conditional control structures (if, while, etc.).

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.

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

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

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.

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.

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!

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 multi-line macros:

The #undef directive may be used to remove a macro’s definition.

Conditional compilation works similar to the C preprocessor. The following preprocessor directives may be used:

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

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:

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

The RCX API defines a set of constants, functions, values, and macros that provide access to features of the RCX such as sensors and outputs. The RCX API is defined by a system include file that is generally included before any source code (unless the -n option is used for NQC). There are two versions of the system include file: rcx1.nqh and rcx2.nqh. The first file contains the old version of the API used by NQC 1.x compilers. The second file describes the current 2.x version of the API. Both system include files are contained within the compiler itself, however they are also included as separate files in the NQC distribution for reference purposes.

The names SENSOR_1, SENSOR_2, and SENSOR_3 are used to identify the RCX's sensor ports. Before a sensor's value can be read, it must be configured properly. A sensor has two different settings: its type and its mode. The type determines how the RCX reads the sensor electrically, while the mode determines how the sensors value is interpreted. For some sensors types only one mode makes sense, but for others (such as the temperature sensor) it can be read equally well in multiple modes (e.g. Fahrenheit and Celsius). The type and mode may be set using SetSensorType(sensor, type) and SetSensorMode(sensor, mode).

For convenience both the mode and type may be set using the SetSensor(sensor, configuration) command. This is the easiest and most common way to configure a sensor.

Valid constants for a sensor's type, mode, and configuration are given below.

A sensor's value can be read by using its name within an condition. For example, the following code checks to see if the value of sensor 1 is greater than 20:

Some sensor types (such as SENSOR_TYPE_ROTATION) allow you to reset the sensor's internal counter with the following command:

The names OUT_A, OUT_B, and OUT_C are used to identify the RCX's three outputs. All of the commands to control outputs can work on multiple outputs at the same time. In order to specify more than one output for a command, add the names of the outputs together. For example, use "OUT_A + OUT_B" to specify outputs A and B together.

Each output has three different attributes: mode, direction, and power level. The mode can be set with the SetOutput(outputs, mode) command. The mode parameter should be one of the following constants:

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:

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) command.

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

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.

Some examples of using the output commands are shown below:

All of the output functions require constants for their arguments with the following exceptions:

OnPower - an expression may be used for the power level

OnFor - and expression may be used for the time

Wait(time) - Make a task sleep for specified amount of time (in 100ths of a second). The time argument may be an expression or a constant:

PlaySound(sound) - Play one of the 6 preset RCX sounds. The sound argument must be a constant. 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.

PlayTone(frequency, duration) - Play a single tone of the specified frequency and duration. Both arguments must be constant. The frequency is in Hz, the duration is in 100ths of a second.

SelectDisplay(mode) - Select which mode the LCD display should use. There are seven different display modes as shown below. The RCX defaults to DISPLAY_WATCH.

Mode	LCD Contents
DISPLAY_WATCH	show the system "watch"
DISPLAY_SENSOR_1	show value of sensor 1
DISPLAY_SENSOR_2	show value of sensor 2
DISPLAY_SENSOR_3	show value of sensor 3
DISPLAY_OUT_A	show setting for output A
DISPLAY_OUT_B	show setting for output B
DISPLAY_OUT_C	show setting for output C

ClearMessage() - Clear the message buffer for RCX to RCX communication. This allows detection of the next received IR message. The Message() expression may be used to read the current contents of the receive buffer.

SendMessage(message) - Send an IR message to another RCX. '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.

SetWatch(hours, minutes) - 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.

ClearTimer(timer) - Clear one of the RCX's four internal timers. The timer parameter must be a constant between 0 and 3 inclusive.

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

SetTxPower(power) - Set the power level for the RCX's IR transmitter. The power level should be either TX_POWER_LO or TX_POWER_HI.

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.

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.

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 environment being used. For example, in the command line version of NQC, the following commands will upload and print the datalog:

The RCX has several different sources of data: sensors, variables, timers, etc. Within NQC, these data sources can be accessed using special expressions.

The RCX contains four timers which measure time in increments of a tenth of a second (100ms). To read the value of a timer, use the Timer(n) expression where n is a constant between 0 and 3 and specifies which timer to read.

Sensors have a number of different values associated with them. The sensor's raw value, its boolean value, or its normal value can be read. In addition, it is possible for a program to read a sensor's configured type and mode. All of the expressions for sensor values require an argument specifying which sensor to use. This argument should be between 0 and 2. Note that the names SENSOR_1, SENSOR_2, and SENSOR_3 are really just macros for SensorValue(n) expressions:

The RCX API also provides expressions to generate a random number, read the system watch, or read the last received IR message. All of the RCX API expressions are summarized below:

Conditions are used within control statements to make decisions. In most cases, the condition will involve a comparison between expressions.

There are a number of different values that can be used within expressions including constants, variables, and sensor values. Note that SENSOR_1, SENSOR_2, and SENSOR_3 are macros that expand to SensorValue(0), SensorValue(1), and SensorValue(2) respectively.

Values may be combined by using operators. Several of the operators may only be used in evaluating constant expressions, which means that their operands must be either constants or expressions involving nothing but constants. The operators are listed here in order of precedence (highest to lowest).

Most of the functions require all arguments to be constant expressions (numbers or operations involving other constant expressions). The exceptions are functions that use a sensor as an argument and those that can use any expression. In the case of sensors, the argument should be a sensor name: SENSOR_1, SENSOR_2, or SENSOR_3. In some cases there are predefined names (e.g. SENSOR_TOUCH) for appropriate constants.

Many of the values for RCX functions have named constants that can help make code more readable. Where possible, use a named constant rather than a raw value.

Keywords are those words reserved by the NQC compiler for the language itself. It is an error to use any of these as the names of functions, tasks, or variables.