Brian Connors
posted: 9 October 1999
last updated: 16 October 1999
This package is a very simple implementation of semaphores and intertask messages for Lego Mindstorms designed for use with the NQC package. It is designed to provide explicit notations for intertask communication within RCX programs. What it doesn't do is operate between separate programs on one RCX; though the RCX firmware seems to be preemptively multitasking within programs, it runs only one program at once and the concept is therefore moot. It also does not provide an external (i.e. infrared) messaging API; IR messaging works somewhat differently than the design laid out here, though I'm not ruling out adding it later on.
This package also doesn't do
In accordance with the prevailing practice in the MindStorms developer community, NQCIPC is (c)1999 Brian Connors, made available under the terms of the Mozilla Public License. I would also appreciate recieving a free copy of anything that you use my code in.
Neither the author nor this software is associated with Lego Group, so don't go crying to them if this code doesn't work. They've never heard of me anyway. Equally, Dave Baum wrote a pretty good programming language given what he had to work with, but NQCIPC isn't part of his package, so don't tell him that my stuff doesn't work.
This is a simple package to do a simple job. I don't guarantee that it's good for anything in particular, so you use it at your own risk. Remember that whatever you may think it's good for, Mindstorms is intended as a toy, so use some common sense when you're playing with my code.
The NQCIPC package consists of the following files:
NQCIPC requires the use of David Baum's NQC compiler (version 2.0 or later), and can be used with Lego's Mindstorms and Cybermaster robotics products. It is intended for use with the standard Lego firmware, though I wouldn't mind seeing someone port the API to LegOS.
Note that NQC does not support Lego's standalone Mindstorms Robotics Discovery Kit or Star Wars Droid Developer kit; though it is theoretically possible for a computer to communicate with the former, both are marketed as self-contained toys at present and details of their internal systems ("Scout" and "MicroScout") remain unpublished.
As I write, I don't actually have an RCX of my own yet, but they're very simple macros (based on canned code), so I don't expect bug problems. If you do have any, you can contact me at connorbd@yahoo.com and let me know what the problem is. Include the filename and version number (defined under SEMVER and MSGVER for semaphores and messages respectively) and a fix if you have it.
This file contains three macros for handling semaphores. A semaphore is like a "talking stick": it's a variable that several tasks have access to that lets them know not to all talk at once. It's useful for synchronizing several operations; for example, perhaps multiple tasks need access to the motors. If two different tasks try to execute movement instructions at the same time, they might wind up causing the robot to do lots of random things (or maybe nothing at all); likewise, in a regular computer program, this sort of collision might cause a file to be scrambled or a pointer to be redirected into the void, causing core dumps and other unpleasantness. These functions implement basic semaphore semantics.
For readability, rcxsem.nqh allows you to define a variable of type sem. This is not enforced by the compiler, but it may be helpful for writing readable code.
Syntax:
sem_clear(s);
sem_clear() takes one argument, a semaphore variable named s, and clears it. It is recommended that you don't use this macro outside your main task, as it could create confusion.
Syntax:
sem_acquire(s);
sem_acquire() waits for semaphore s to clear, then takes command of it.
Syntax:
sem_release(s);
sem_release() relinquishes control of semaphore s.
The SSET and SCLEAR constants allow you to check the current status of a semaphore variable:
sem s;
...
if (s == SSET) {
//do something appropriate to a set semaphore
}
In the current implementation, SSET = 1 and SCLEAR = 0.
NQC contains functions that handle messages over the IR link (to the controlling computer or to other RCXen), but none that allow tasks to communicate with each other. Given the architecture of the RCX firmware, any interrupt-driven design is impossible, but a simple drop-box algorithm is trivially implemented in a manner much like the semaphore implementation.
The messaging system has two notable limitations: the only data that can be passed are standard NQC integers, since NQC doesn't support strings or any other data type; and all message buffers are considered shared space, so all msg_send() operations are technically broadcasts. It is recommended that if targeted messages are needed, multiple buffers be set aside for the purpose.
rcxmsg.h defines a datatype msg which behaves exactly as the sem type does. It is optional, but useful.
Syntax:
msg_clear(buf);
msg_clear() sets the contents of buf to 0. For the most part, you should avoid using msg_clear() in any routine except task main().
Syntax:
msg_send(buf,msg);
msg_send() sets the contents of buf to msg.
Syntax:
msg_await(buf,val);
msg_await() blocks (as with sem_acquire() above) until the value in buf is equal to val, then continues.
Syntax:
msg_read(buf,v);
msg_read() copies the contents of buf into variable v.
Syntax:
msg_biff(buf);
msg_biff() returns true if there is a message (i.e. nonzero value) in buf. It's named for the BSD UNIX mail-alert program, in case you didn't know.
Due to limitations in GeoCities' file handling, you have to download NQCIPC piece by piece. The following are the files you need:
The following are some useful Lego Mindstorms links that relate more or less directly to this software and its uses.
The standard RCX architecture is a bit strange and limited in places, but it's good enough to get the job done. NQCIPC simply extends the package a bit to make it a little more professional, and it's simple enough to give a beginning programmer an education in multitasking.
This (10/9/99) is the first release of this package, and as yet it's untested (since I have the NQC docs but no Mindstorms set of my own). I'm willing to take suggestions and contributions (especially example code); just email them to me at connorbd@yahoo.com and I'll put them in if I like them. Finally, if you like this stuff, send me an email and tell me what you're doing with it.
Enjoy!
/Brian
