HubNet Guide

NetLogo 1.2.1 User Manual   

HubNet is a technology that lets you use NetLogo to run participatory simulations in the classroom. In a participatory simulation, a whole class takes part in enacting the behavior of a system as each student controls a part of the system by using an individual device, such as a TI-83+ calculator or a networked computer.

For example, in the Gridlock simulation, each student controls a traffic light in a simulated city. The class as a whole tries to make traffic flow efficiently through the city. As the simulation runs, data is collected which can afterwards be analyzed on a calculator or computer.

For more information on participatory simulations and their learning potential, please visit the Participatory Simulations Project web site.

About HubNet

HubNet Types

Currently, there are two types of HubNet available. One, called Calculator HubNet, was created in conjunction with Texas Instruments and makes use of TI's Navigator system. This type of HubNet uses TI-83+ graphing calculators as the clients, the devices used to control a portion of a NetLogo model.

The second type of HubNet is Computer HubNet. This is adapted from the calculator version and uses laptop or desktop networked computers as the clients.

In the future, we hope to add more types of HubNet that support other types of clients such as PDA's (Personal Digital Assistants).

What do I need to get started?

Calculator HubNet

NOTE: Navigator is not yet commercially available. To learn more about the system, visit Texas Instruments' site. Navigator is currently only available to select pilot sites, but TI has announced that it will be commercially available in the Second Quarter of 2003. However, we are not certain if HubNet will work with the first commercially available version of Navigator; it might only work with a future release version of Navigator.

Computer HubNet

NOTE: Computer HubNet is still in the process of being developed and is only being released as an alpha version. There may be some features that are lacking or bugs that we have not found. Please send us any feature requests or bugs that you find to feedback@ccl.northwestern.edu

First-time NetLogo user?

NetLogo is a programmable modeling environment. It comes with a large library of existing simulations, both participatory and traditional, that you can use and modify. Content areas include social science and economics, biology and medicine, physics and chemistry, and mathematics and computer science. You and your students can also use it to build your own simulations, if you choose.

In traditional NetLogo simulations, the simulation runs according to rules that the simulation author specifies. HubNet adds a new dimension to NetLogo by letting simulations run not just according to rules, but by direct human participation. Since HubNet builds upon NetLogo, we recommend that before trying HubNet for the first time, you should be familiar with the basics of NetLogo.

Teacher workshops

For information on upcoming workshops and NetLogo and HubNet use in the classroom, please contact us at feedback@ccl.northwestern.edu.

Getting Started With HubNet

Using NetLogo

We recommend that you become familiar with NetLogo itself before using the HubNet technology.

You can become familiar with NetLogo by trying out some of the models in the Models Library. Open the Models Library from the File menu in NetLogo. Then click on a model that you want to try and press the Open button. The Information tab in each of the models gives background information and instructions.

Other sections of the NetLogo User Manual may be helpful when learning NetLogo. We suggest that beginning users focus on the section Tutorial #1: Running Models.

If you have any questions about NetLogo, feel free to E-mail us. You can reach us at feedback@ccl.northwestern.edu.

HubNet Activities

Below are the current HubNet activities that are fully developed. Be aware that some of these models have only been implemented for one type of HubNet. For many models, you will find its educational goals and suggested ways to incorporate them into your classroom in the Participatory Simulations Guide which can be found on the Participatory Simulations Project web site.

NOTE: In addition to the discussion of learning goals and classroom techniques, these materials also contain step by step instructions and screen shots. As of December 2002, they are out of date and no longer match the actual activities in many respects. We are working on updating them. In the meantime, please use these materials for the discussions, but for step by step instructions, rely instead on the QuickStart Instructions built into the activities (see next section).

Running an activity

You'll find the HubNet activities in NetLogo's Models Library, under the HubNet Calculator Activities and HubNet Computer Activities folders.

When you open the first HubNet activity for each session of NetLogo, you will be prompted by the HubNet Settings dialog. This prompts you to enter information (such as what type of HubNet you wish to use, User Id or Password) that is necessary for connecting to the appropriate server and running the HubNet activity. If you don't actually want to run the model, just press the Cancel button. (Be aware you may still get NetLogo Runtime errors if you do press Cancel.)

If you wish to use Calculator HubNet, make sure that the Calculator HubNet checkbox is checked and Computer HubNet is not checked. You must also fill in login information regarding the User Id, Password, and perhaps other information as well.

If you wish to use Computer HubNet, make sure that the Computer HubNet checkbox is checked and Calculator HubNet is not checked.

In each of the activities, you'll see a box on the screen labeled "QuickStart Instructions". It contains step by step instructions on how to run that activity. Click the "Next>>>" button to advance to the next instruction.

We suggest doing a few practice runs of the activity before trying it in front of an actual class.

If you have any questions about running the activities, feel free to E-mail us. You can reach us at feedback@ccl.northwestern.edu.

Calculator HubNet

For more information about how to log in to the calculators and other details of using Calculator HubNet, please refer to the Participatory Simulations Guide which can be found on the Participatory Simulations Project web site.

Computer HubNet

Setting up a Computer Activity

Once you have pressed the Login button in the HubNet Settings dialog, NetLogo will start a server which will allow people will be able to join the activity. You should then follow the instructions for the particular model found in the QuickStart Instructions monitor. Most models will require you to press a forever button, often called GO. You, as the leader, should notify everyone that they may join. This will require you to give the users the IP address for the computer that is running NetLogo. The IP address of the server can be found in the HubNet Control Center, which can be opened by choosing the HubNet Control Center option in NetLogo's Tools menu. Every user will have to enter this IP address to be able to enter the activity.

Every participant will also have to enter a unique User Id. A good method for choosing a unique User Id is to combine the first and last name of the user. For example, if the user's name is Joe Smith, he might want to choose the User Id, joesmith. Another good method for getting a unique User Id is for you, the leader, give out unique User Id's to everyone. If you decide to use this second method, be sure to inform every user what User Id he or she is supposed to use.

Joining a Computer Activity

Once the leader has informed you that you can join, you should open up the HubNet Client application. This will prompt you for the IP address of the computer running NetLogo. Enter the IP address that the leader gave you. You then will be prompted to enter a User Id. Please enter one. The leader will give directions on how to choose one. If no one else is using the one you enter, NetLogo will send you the client interface and you can start playing. If you didn't choose a unique User Id, your client application will display a message indicating this. You should keep trying new User Id's until you are able to enter. A good method for choosing a unique User Id is to use your first and last name together. For example, if your name is Joe Smith, you might want to choose the User Id, joesmith.

HubNet Control Center

One new feature of Computer HubNet is the HubNet Control Center. You can open this using the HubNet Control Center option in the Tools Menu when a Computer HubNet Activity is open and the server is running. The Control Center shows you useful information, such as the IP address of the computer, who is logged in, etc. It also allows you to disconnect clients from the activity and send out messages for all the clients to read.

In addition to these features, the HubNet Control Center allows you to control whether debugging output is on or off. Debugging output is useful when creating your own HubNet activity or to keep track of which participant sent what data when. Any output is sent to the log.txt file on Windows machines, or the Console to Macs. The Control Center also allows you to control whether the NetLogo Graphics Window and plots are mirrored on the clients. These options are useful if there are a lot of changes to the Graphics Window or plots or if you just don't wish the clients to see what is happening on the clients. By default, these options are turned off since they in an experimental stage.

HubNet Authoring Guide

If you wish to learn more about authoring or modifying HubNet activities, you should look at the HubNet Authoring Guide.

Computer HubNet Troubleshooting Tips

Here are some things that have been known to go wrong and ways of fixing or working around them.

I have tried quitting a HubNet Client, but it just sits there and won't quit no matter how many times I try.

You will have to force the client to quit. On Macs, force quit the application (Command+Option+Esc). On Windows, open the Windows Task Manager (Ctrl+Alt+Delete), select Hubnet and press 'End Task'. Then you should inform the leader of the simulation to use the HubNet Control Center to kick your the client out of the simulation.

When I pressed the Login button in the HubNet Settings dialog, I got an Internal Error similar to this:

java.net.BindException: Address in use
 at java.net.PlainSocketImpl.bind(PlainSocketImpl.java:376)
 at java.net.ServerSocket.(ServerSocket.java:131)
 at java.net.ServerSocket.(ServerSocket.java:68)
 at nLogo.hubnet.server.Server.run(Server.java:33)

Another program (perhaps another copy of NetLogo) is using a port that HubNet needs. Check to see if you have another copy of NetLogo open that is running Computer HubNet. If you do, quit it and then try reopening the model. If you don't, you can try quitting other programs and reopening the model until you are able to start the Computer HubNet server successfully.

When I tried logging into a HubNet Client, the login fails for an unknown cause and I get an error similar to this:

Login failed for unknown cause: 
java.net.NoRouteToHostException: Operation timed out 
 at java.net.PlainSocketImpl.doConnect(PlainSocketImpl.java:295)
 at java.net.PlainSocketImpl.connectToAddress(PlainSocketImpl.java:137)
 at java.net.PlainSocketImpl.connect(PlainSocketImpl.java:124)
 at java.net.Socket.(Socket.java:214)
 at java.net.Socket.(Socket.java:82)
 at nLogo.hubnet.client.ClientPanel.attemptLogin(ClientPanel.java:128)
 at nLogo.hubnet.client.ClientPanel.access$1(ClientPanel.java:0)
 at nLogo.hubnet.client.ClientPanel$4.run(ClientPanel.java:119)
 at java.lang.Thread.run(Thread.java:492)

Either there is no computer that has the IP address that you typed in or that computer is not currently running a Computer HubNet server. One reason for this is that you might have typed the wrong IP address. Quit the client, reopen another, and try logging in again.

Another potential problem is that you might not be connected to the proper network. Check your network connection.

Somehow two or more HubNet Clients are controlling the same agents in the simulation and they aren't supposed to. What can I do to fix this problem?

Remove all but one of the clients from the simulation by either by having the people quit the client or by using the Kick Client feature in the HubNet Control Center to forcibly remove them. If you wish them all to still be in the simulation, the ones that quit should log back in.

I had run and then stopped a HubNet model. I changed windows or minimized NetLogo or did something else to obscure or redraw the Graphics Window. When I came back to the NetLogo, the Graphics Window was all gray. What happened? Is all my data lost?

In order to reduce the number of messages sent to the clients, we use the no-display and display primitives to "turn off" the drawing to the Graphics Window and only update it periodically. This has the unfortunate side affect of causing the Graphics Window to become gray if it is redrawn and the GO button is not pressed. You can simply type display into the command center to redraw the current state of the turtles and patches in this situation.

My computer went to sleep while running a HubNet activity. When I woke the computer up, I got an error and HubNet wouldn't work anymore.

We have reports that if a computer goes to sleep while running Computer HubNet (either the HubNet Client or the server), sometimes things do not work after the computer wakes up. Please send us the error message along with the situation that caused it. However, we suggest that people keep their computers from sleeping while running an activity.

I am in the process of creating an activity. I was doing some testing, and while I was setting up or running model, the turtle suddenly disappeared, but my client was still logged in.

The way things are set up now, if you try to send a message to a client that has a tag that is not associated with an interface element in the client, the send will fail causing a hubnet-exit-message to be generated NetLogo. This causes the turtle to disappear through the normal handling of the hubnet-exit-message. However, since the hubnet-exit-message is generated by NetLogo and not sent by the client, the client doesn't know that it is supposed to have quit.

Known Computer HubNet Issues

If HubNet malfunctions, please send us a bug report. See the "Contact Us" section for instructions.

Known bugs (all systems)

Windows-only bugs:

Appendix: HubNet Architecture

HubNet architecture diagram