NetLogoLab and the GoGo Board Extension

What is NetLogoLab?

NetLogoLab is the technological infrastructure that connects NetLogo and the physical world. It can be used for robotics, interactive art, scientific investigations, and model validation. For more information, please check the NetLogoLab web site, where you will find academic papers and demos.

NetLogoLab is comprised of the following software and hardware components:

  1. A NetLogo extension to control a robotics or data-logging board.
  2. A robotics or data-logging board (also know as a serial interface board, or analog-to-digital board).
  3. Sensor and actuator toolkits.
  4. NetLogo models.

NetLogo's robotics/data-logging board of choice is the GoGo Board - an open-source, easy-to-build, low-cost interface originally designed at the MIT Media Lab by Arnan Sipitakiat. Other robotics hardware can be used with NetLogo, including those that are commercially available, such as Vernier and Pasco sensors and actuators, Phidgets, Lego robotics kits, and VEX kits - but specific extensions still need to be developed for each of those platforms. So far, only the GoGo Board extension is available with NetLogo's standard distribution.

The GoGo Board NetLogo extension

The GoGo Board extension is a software component that enables the user to connect NetLogo with the physical world using sensors, motors, light bulbs, LEDs, relays and other devices. The GoGo Extension for NetLogo provides simple primitives to communicate with a GoGo board.

GoGo Board: a low-cost robotics and data-logging board

A GoGo Board is an open source, easy-to-build, low cost, general purpose serial interface board especially designed to be used in school and for educational projects. It was created by Arnan Sipitakiat with the collaboration of Paulo Blikstein at the MIT Media Lab in 2001, and has been actively developed since then. It is currently used in over 10 countries, such as: the United States, China, Thailand, Brazil, Portugal, Mexico, Malaysia, and Egypt.

Up to 8 sensors (i.e., temperature, light, pressure) and 4 output devices (i.e., motors, light bulbs, LEDs, relays) can be connected to the board simultaneously. The board also has a connector for add-on devices (such as a small display or a wireless communication module). Coupled to a serial Bluetooth dongle (such as the Iogear or WCSC models), instead of a serial cable, it can be used as a wireless device as well.

Sensor and actuator toolkits

NetLogo models can interact with the physical world in two ways. First, they can gather data from the environment. This information can be used by the model to change or calibrate its behavior. This data is gathered using electronic sensors, which can measure a wide range of phenomena: temperature, light, touch (see pictures below), pH, chemical concentration, pressure, etc.

Temperature sensor Light sensor Touch sensor

The second mode of interaction between NetLogo and the physical world is the control of output devices, or "actuators" - motors, light bulbs (see pictures below), LEDs, and more complex devices that include these outputs such as toys, remote controlled cars, electrical appliances, and automated laboratory equipment.

Motor

For educators willing to start robotics or sensing projects, there are some important considerations regarding the exact type of sensors and actuators to use - for example, the sturdiness, reliability, "openness", and cost of these devices. Both vary greatly in price and complexity. For example, for most educational projects, off-the-shelf, generic, low-cost sensors can be used with very reliable results. A generic temperature sensor with a precision of 0.5 degrees Celsius can be purchased for approximately US$ 1.00 at most sensor and electronics retailers. Using generic, low-cost sensors requires very basic knowledge of electronics. For example, some basic soldering might be needed to attach a piece of wire to the sensors. While this is feasible in schools and has been tried in several educational settings, some educators might prefer to buy proprietary sensors and actuators, which come assembled and ready to be used. Some companies offer proprietary systems for educational sensing which are more sturdy and reliable than generic sensors, but are also much more expensive. As a comparison, a proprietary temperature sensor could cost as much as US$ 50.00. Actuators follow the same rule: for example, a generic geared motor could cost from US$ 3 to 10, while a proprietary version would retail for US$ 30 or 40.

Sensors and actuators can be found through online retailers such as Digikey, Mouser, Phidgets, Spark Fun, and Solarbotics. More information about how to make sensors is available from the "How to Make Sensors" web page on the GoGo board web site.

NetLogo models

To make use of the GoGo Board extension and the NetLogoLab framework, users need to create NetLogo models using the special primitives made available by the extension. Later in this document, we will provide examples of models that do this.

How to get a GoGo Board?

The GoGo Board is not a commercial product, and thus cannot be bought at stores. To get a GoGo Board, you have to build one yourself or ask someone to do it for you. Many companies can assemble boards, but they normally require a minimum quantity, which can range from 5 to 50. The board was especially designed to be easy and cheap to build, even if you don't have electronics skills. The main resource about the GoGo Board is the web site www.gogoboard.org, where you will find step-by-step instructions on how to buy components, design the printed circuit board, and assemble it. The GoGo Board mailing list is gogoboard@yahoogroups.com, and you can join it by going to Yahoo groups. The GoGo Board wiki can be found at www.edudesign.org/gogowiki

Installing and testing the GoGo Extension

The GoGo Board needs to communicate with the computer in some way, and to do so it uses the serial port. The choice of this port instead of a USB port was motivated by the board's low cost principle: the components needed to build a USB compatible board would be more expensive. If your computer does not have a serial port, you need to purchase a USB-to-Serial adapter, which can be easily found in computer stores with prices ranging from US$ 15 to US$ 30 (if you have a Mac or Linux machine, make sure the adapter is compatible with your platform). One brand that normally works quite well for all platforms is Keyspan (USA-19HS model), although it is one of the most expensive ones.

If you are using a serial to USB adapter you will need to make sure the drivers are installed before you begin, the adapter may come with a CD with the appropriate drivers, otherwise you will need to download them from the company's web site. Make sure to plug the adapter into the computer and the GoGo board. Turn the GoGo board on using the switch behind the power connector. The GoGo board will beep and the red light will turn on.

Windows

The GoGo extension requires no special installation on Windows.

Mac OS X

There is a bug either in Mac OS X or in the RXTX library that we use for the serial connection which requires you to enter the following commands in the Terminal application (/Applications/Utilities/Terminal.app) before the GoGo board will work:

sudo mkdir /var/lock
sudo chmod 1777 /var/lock
sudo rm /var/spool/uucp/*

Once you've completed the previous step you can start NetLogo. Open the GoGoMonitor example and press the setup button. A dialog will pop up presenting a list of available ports. Select the port that the GoGo board is plugged into. It might look something like this:

/dev/tty.KeySerial1

Where the words after /dev/tty. might be something related to the brand of adapter you have and include the word "serial". If you can't figure out which port is the correct one you can find it in the System Profiler (Apple Menu -> About This Mac -> More Info)

After you setup press the ping button, it should print true in the command center. You should also notice values in the sensor monitors that may be fluctuating slightly.

If this does not work please contact us at bugs@ccl.northwestern.edu.

Linux

You will need to be able to write to the serial devices, normally /dev/ttyS*. In most Linux distributions this can be set up through the User Manager.

Using the GoGo Extension

The GoGo Extension comes preinstalled when you download and install NetLogo. To use the extension in your model, add this line to the top of your procedures tab:

extensions [gogo]

If your model already uses other extensions, then it already has an extensions line in it, so just add gogo to the list.

After loading the extension, see what ports are available by typing the following into the command center:

print gogo:ports

You can open the serial port that the GoGo Board is connected to so that commands can begin to be sent to the board by using the gogo:open command. To make sure the board is properly connected, check that it is responding with the ping reporter. Note that in order to communicate with the board, you need to know which communications port it is connected to. If you are not sure which port is being used, you can use the gogo:ports primitive (see below), or you can find out by using the Device Manager on a Windows computer (in the Control Panel, click on the System icon), or the System Profiler on Macintosh OS X.

On Windows:

gogo:open "COM1"
print gogo:ping

On Linux:

gogo:open "/dev/ttyS01"
print gogo:ping

On Mac:

gogo:open "/dev/tty.KeySerial1"
print gogo:ping

For more information on NetLogo extensions, see the Extensions Guide.

Models saved as applets (using "Save as Applet" from the File menu) cannot use the GoGo extension. Applets cannot use extensions that require additional libraries nor can they access external devices. For examples that use the GoGo extension, see the Robotics/NetLogoLab section under Sample Models in NetLogo's Models Library.

Examples of NetLogoLab models

Controlling a car

The first step when creating a NetLogoLab model is to add the extensions command to NetLogo's procedure tab. Just go to the procedures tab and add this line:

extensions [gogo]

The second step is to create a button to connect NetLogo to the GoGo board using the correct serial port for your operating system as described above.

gogo:open "COM1" ;; (for Windows machines)

When you are done creating the button, the "edit" dialog should look like this:

setup button

Now let's actually start the model. Imagine that we want to control a car with four wheels and two motors attached to the back wheels. We will assume that you have built such as car and connected the motors to the output ports "a" and "b" on the GoGo board. One very simple approach could be to create two buttons for each motor, "on" and "off":

on off buttons

The code associated with these buttons is very simple: for the "on" button, we could simply have

gogo:talk-to-output-ports ["a"]
gogo:output-port-on

For the off button, it would be very similar:

gogo:talk-to-output-ports ["a"]
gogo:output-port-off

The other set of "on" and "off" buttons, used to control the second motor, would have very similar code, except that we would use the second output port ("b"), so:

gogo:talk-to-output-ports ["b"]

We could make our model more interesting by adding a "toggle direction" button, adding a button with the following code, which would reverse the direction of motors "a" and "b":

gogo:talk-to-output-ports ["a" "b"]
gogo:output-port-reverse

A simple sensing project

To create a simple sensing project, we will assume that you have added the GoGo extension to your model and successfully opened a connection to the GoGo board, i.e., adding the "extensions" command to the Procedures Tab and adding a "setup" button as previously described. For this sensing project we do not need motors, but we will need another device: a temperature sensor (click to see more information about a typical temperature sensor at Digikey's web site). Instructions on how to purchase and assemble a temperature sensor can be found in the "Making Sensors" tutorial on the GoGo Board's web site. This is how a temperature sensor will look after it has been assembled:

Temperature sensor

The simplest use of a temperature sensor, obviously, is to display the temperature. We could achieve this by adding a monitor to the NetLogo interface with this code:

gogo:sensor 1

Sensor monitor

The sensor values shown are arbitrary numbers within a given range, and need to be properly converted to actual temperature units such as degrees Celsius or Fahrenheit. For all sensors, the GoGo Board's reporting range is from 0 to 1023. Every sensor comes with a data sheet with a converting formula or table that will transform the arbitrary 0-1023 range into an actual physical unit. Let us imagine that the sensor's data sheet contains a conversion formula that looks like this: degrees = arbitrary value / 30. The monitor on the NetLogo interface could be changed to:

gogo:sensor 1 / 30

The sensor value could also be used to control on-screen objects, such as turtles. For example, let us create two buttons: a "create one turtle" button, which will clear the world and create a turtle, and a "move with heat" button, that will cause the turtle to move forwards depending on the temperature reading from the sensor. The code would look like this:

to create-one-turtle
  clear-all  
  create-turtle
end
    
to move-with-heat
  if gogo:sensor 1 < 500
    [ forward 1 ]
end

If the "move with heat" forever button is activated and the user heats up the sensor (by rubbing it, or slowly bringing a flame near it), the heat threshold will be achieved (< 500) and the turtle will move. (Note that we are using one kind of temperature sensor for which resistance decreases with temperature, and so the sensor readings will go down as we heat the sensor up. This is a very common and inexpensive off-the-shelf sensor).

A more elaborate use of this sensor apparatus would be to control output devices, such as motors. The user could, for example, turn a motor on when the value from the temperature sensor reaches 500, using the following code:

to turn-motor-on-with-heat
  if gogo:sensor 1 < 500
  [ 
    gogo:talk-to-output-ports ["a"]
    gogo:output-port-on
  ]
end

Another possible use of the sensing primitives is to plot and log data. Logging could be useful for more elaborate data analysis and comparison, and can be achieved with NetLogo's list commands. For example, if the user wants to log sensor values from sensor 1 every 0.5 seconds, the code could look like this:

to log-data-from-sensor
  set data-vector lput (gogo:sensor 1) data-vector
  wait 0.5
end

Finally, plotting data is straightforward. The following code, for example, would create a graph for the value of sensor 1:

plot (gogo:sensor 1)

For more information on the GoGo Board's extensions functionalities and primitives, please refer to these two sample models: GoGoMonitor.nlogo and GoGoMonitorSimple.nlogo.

Primitives

gogo:close gogo:open gogo:open? gogo:ports gogo:output-port-coast gogo:output-port-off gogo:output-port-reverse gogo:output-port-[that|this]way gogo:ping gogo:sensor gogo:set-output-port-power gogo:talk-to-output-ports

gogo:close

gogo:close

Close the connection to the GoGo Board.

See also gogo:open and gogo:open?.

gogo:open

gogo:open port-name

Open a connection to the GoGo Board connected to serial port named port-name. See gogo:ports for more information about port names.

If the GoGo Board is not responding, or you attempt to open a port without a GoGo Board connected to it, an error will be generated.

Example:

gogo:open "COM1"

See also gogo:open? and gogo:close.

gogo:open?

gogo:open?

Reports true if there is a connection to a GoGo Board open. Reports false otherwise.

gogo:ports

gogo:ports

Reports a list of serial port names that a GoGo Board may be connected to. On certain computers, you might get a list of two or three different serial ports. In that case, try to open each of them until the connection is successful.

gogo:output-port-coast

gogo:output-port-coast

Turns off the power of the active ports. When attached to motors, does not apply a braking force as gogo:output-port-off does. Therefore, the motor will gradually slow down before stopping completely. This will have the same effect as gogo:output-port-off on most output devices other than motors. The output-ports affected by this command are determined by the gogo:talk-to-output-ports command.

The following code will turn on an output port a for 1 second, and then stop the motor gradually:

gogo:talk-to-output-ports ["a"]
gogo:output-port-on
wait 1
gogo:output-port-coast

gogo:output-port-off

gogo:output-port-off

Turns off power to the output ports. If using motors, a braking force is applied. The output ports affected by this command are determined by the gogo:talk-to-output-ports command.

gogo:output-port-on

gogo:output-port-on

Turns on power to the output ports. The output ports affected by this command are determined by the gogo:talk-to-output-ports command.

gogo:output-port-reverse

gogo:output-port-reverse

Reverses the direction of the output ports. The output ports affected by this command are determined by the gogo:talk-to-output-ports command.

gogo:output-port-[that/this]way

gogo:output-port-thatway

gogo:output-port-thisway

Apply power to the output port in a given direction. Output ports can be powered in two directions, arbitrarily called thisway and thatway. The output-ports affected by the command are determined by the gogo:talk-to-output-ports command. Note that this is different from gogo:output-port-reverse because thisway and thatway will always be the same direction provided the connector's polarity is the same.

gogo:talk-to-output-ports

gogo:talk-to-output-ports output-portlist

This command will set the corresponding output ports as active. They will be the ones affected by the commands such as gogo:output-port-on and gogo:output-port-off. The user can "talk" to one or multiple ports at the same time. Output ports are typically connected to motors, but you could also use bulbs, LEDs and relays. Output ports are identified by one letter names: "a", "b", "c", and "d".

Examples:

;; talk to all output-ports
gogo:talk-to-output-ports [ "a" "b" "c" "d" ]
;; will give power to all output-ports
gogo:output-port-on

;; talk to output-ports A and D
gogo:talk-to-output-ports [ "a" "d" ]
;; will turn off output-ports A and D.
;; The other output-ports will keep
;; their current state
gogo:output-port-off

gogo:talk-to-output-ports [ "c" "b" ]
;; turn off remaining output-ports
gogo:output-port-off

gogo:ping

gogo:ping

Checks the status of GoGo board. This is mostly used to make sure the board is connected to the correct serial port. It reports true if the GoGo Board responds to a diagnostic message, and false otherwise.

Example:

print gogo:ping

gogo:sensor

gogo:sensor sensor

Reports the numeric value of the sensor named sensor. Sensors are identified by numbers 1 to 8. Values range between 0-1023. 1023 is returned when there is no sensor attached to the port (highest resistance), or when the sensor is an "open" state. Zero is returned when the sensor is short circuited (no resistance).

Examples:

print gogo:sensor 1
;; prints the value of sensor 1

foreach [ 1 2 3 4 5 6 7 8 ]
  [print (word "Sensor " ? " = " gogo:sensor ?)]
;; prints the value of all sensors

if gogo:sensor 1 < 500 [ ask turtles [ fd 10 ]]
;; will move all turtles 10 steps forward if sensor 1's value is less than 500. loop [if gogo:sensor 1 < 500 [ ask turtles [ fd 10 ] ] ]
;; will continuously check sensor 1's value and ;; move all turtles 10 steps forward every time ;; that the sensor value is less than 500.

gogo:set-output-port-power

gogo:set-output-port-power power-level

Sets the power level of the active output ports. power-level is a number between 0 (off) and 7 (full-power). The output-ports affected by this command are determined by the gogo:talk-to-output-ports command. Note that for many practical applications it is more efficient to use mechanical devices, such as gears and pulleys, to control the torque of motors.

Example:

gogo:talk-to-motors ["a" "b" "c" "d"]
gogo:set-motor-power 4
;; will lower the power of all output ports by half of the full power .