HubNet Authoring Guide

NetLogo User Manual   

This explains how to use NetLogo to modify the existing HubNet activities or build your own, new HubNet activities.

General HubNet Information

If you are interested in more general information on what HubNet is or how to run HubNet activities, you should refer to the HubNet Guide.

NetLogo Primitives

In the model, the modeler uses a set of commands to set the model up to use a type of HubNet, extract data from and send data to the Navigator system or the computer clients. Below you can find explanations of each of the NetLogo primitives used to do these tasks.

Setup

In order to make a NetLogo model into a HubNet one, it is necessary to establish a connection with the Navigator server in the case of Calculator HubNet and to start a HubNet server in the case of Computer HubNet. For Calculator HubNet, it is also necessary for NetLogo to tell the Navigator server what variables to send to NetLogo. For all forms of HubNet, it is also necessary to inform NetLogo what the client interface is. All these tasks are done with the following primitives:

hubnet-reset
This starts up the HubNet system. HubNet must be started to use any of the other HubNet primitives with the exception of hubnet-set-client-interface. HubNet remains running as long as this model is open; it stops running when the model is closed or you quit NetLogo.

If this is the first time called for this NetLogo session and you are using Calculator HubNet, the TI-Navigator Login dialog appears prompting you to input the appropriate information to be able to log into the Navigator system. Once you press the Login button, NetLogo will attempt to log you into the TI-Navigator system and start HubNet. If you successfully log into the Navigator system, you will not be prompted by this dialog again as long as this session of NetLogo remains open.

If you are using Computer HubNet, you will be prompted by a dialog asking for a unique name for your computer. This is an optional identifier to help make servers discovered on the client more different and unique. If you don't wish to enter a name, just press the Cancel button.

hubnet-set-client-interface client-type client-info
If client-type is "TI-83+", client-info is a list containing two items. The first item is a string containing the name of the activity to enable on the TI Navigator web site. hubnet-set-client-interface "TI-83+" notifies the user to enable this activity. The second item is a list of the tags for which to check. The tag list sets which variables NetLogo expects from the calculators. NetLogo will only check for these variables and will ignore all others. Currently, the valid types that NetLogo will be able to receive from the calculator are the following:

If client-type is "COMPUTER", client-info is a list containing a string with the file name and path (relative to the model) to the file which will serve as the client's interface. This interface will be sent to any clients that log in.

hubnet-set-client-interface "TI-83+" [ "AAA - Gridlock 1.3" ["L1" "LOCS"] ] 
;; notifies the user to enable the activity AAA - Gridlock 1.3 and looks for the 
;; calculator lists L1 and LOCS on the Navigator server

hubnet-set-client-interface "COMPUTER" [ "clients/Disease client.nlogo" ]
;; when clients log in, they will will get the interface described in the file
;; Disease client.nlogo in the clients subdirectory of the model directory
This primitive must be called before you try to use HubNet calling the hubnet-reset reporter so NetLogo can know which type of HubNet you are going to be using.

These primitives are usually best called from the startup procedure of the NetLogo model since they should only be called once in a model.

Data extraction

The data extraction primitives are:

hubnet-message-waiting?
This looks for new information sent by the clients. It reports TRUE if there is new data, and FALSE if there is not.
hubnet-fetch-message
If there is any new data sent by the clients, this retrieves the next piece of data, so that it can be accessed by hubnet-message. This will cause an error if there is no new data from the clients. So be sure to check for data with hubnet-message-waiting? before calling this.
hubnet-message-source
This reports the user name of the client that sent the data. This will cause an error if no data has been fetched. So be sure to fetch the data with hubnet-fetch-message before calling this.
hubnet-message-tag
This reports the tag that is associated with the data that was sent. For Calculator HubNet, this will report one of the variable names set with the hubnet-set-client-interface primitive. For Computer HubNet, this will report one of the Display Names of the interface elements in the client interface. (See below for more information about the Computer HubNet tags.) For both types of HubNet, this primitive will cause an error if no data has been fetched. So be sure to fetch the data with hubnet-fetch-message before calling this.
hubnet-message
This reports the data collected by hubnet-fetch-message. This will cause an error if no data has been fetched. So be sure to fetch the data with hubnet-fetch-message before calling this.

There are two additional data extraction primitives that are only used in Computer HubNet models.

hubnet-enter-message?
Reports true if a new computer client just entered the simulation. Reports false otherwise.
hubnet-exit-message?
Reports true if a new computer client just exited the simulation. Reports false otherwise.

For both hubnet-enter-message? and hubnet-exit-message?, hubnet-message-source will contain the user name of the client that just logged on or off. Also, if hubnet-message and hubnet-message-tag are used while hubnet-enter-message? or hubnet-exit-message? are true, a Runtime Error will be given.

Sending data

It is also possible to send data from NetLogo to the clients. For Calculator HubNet, NetLogo sends the data to the Navigator server, and then the calculators can then access it. For Computer HubNet, NetLogo is able to send the data directly to the clients.

Note: Since NetLogo must send the data to the Navigator server in Calculator HubNet, it is not currently possible to send data from NetLogo directly to only an individual calculator. However, once the server has the data, any connected calculator can grab it. This is done using the calculators' communication facilities, rather than through NetLogo.

The primitives for sending data to the server are:

hubnet-broadcast tag-name value
This broadcasts value from NetLogo to the variable, in the case of Calculator HubNet, or interface element, in the case of Computer HubNet, with the name tag-name to all the clients.
hubnet-broadcast-graphics
This broadcasts the current state of the Graphics Window in the NetLogo model to all the Computer HubNet Clients. It does nothing for Calculator HubNet.
Note: This is an experimental privitive and its behavior may change in a future version.
hubnet-send list-of-strings tag-name value
hubnet-send string tag-name value
When using Calculator HubNet this primitive acts in exactly the same manner as hubnet-broadcast. For Computer HubNet, it has the following effects: Note: Sending a message to a non-existent client, using hubnet-send, generates a hubnet-exit-message.
hubnet-send-graphics string
hubnet-send-graphics list-of-strings
For Calculator HubNet, does nothing.
For Computer HubNet, it acts as follows: Note: Sending the Graphics Window to a non-existent client, using hubnet-send-graphics, generates a hubnet-exit-message.
Note: This is an experimental privitive and its behavior may change in a future version.

For the hubnet-send and the hubnet-broadcast primitives, when using Calculator HubNet, value may be a number, a string, a list of numbers, or a matrix (a list of lists) of numbers. For Computer HubNet, you may send any kind of information with the exceptions of patches, turtles, and agentsets.

Here are some examples of using the two primitives to send various types of data that you can send:

data typehubnet-broadcast examplehubnet-send example
numberhubnet-broadcast "A" 3.14hubnet-send "jimmy" "A" 3.14
stringhubnet-broadcast "STR1" "HI THERE"hubnet-send ["12" "15"] "STR1" "HI THERE"
list of numbershubnet-broadcast "L2" [1 2 3]hubnet-send hubnet-message-source "L2" [1 2 3]
matrix of numbershubnet-broadcast "[A]" [[1 2] [3 4]]hubnet-send "suzy" "[A]" [[1 2] [3 4]]
list of strings (only for Computer HubNet)hubnet-broadcast "user-names" [["jimmy" "suzy"] ["bob" "george"]]hubnet-send "teacher" "user-names" [["jimmy" "suzy"] ["bob" "george"]]

Examples

Study the models in the "HubNet Computer Activities" and the "HubNet Calculator Activities" sections of the Models Library to see how these primitives are used in practice in the Procedures window. Disease is a good one with which to start.

Calculator HubNet Information

The calculators are able to send and receive the following data types from NetLogo:

The calculator sends and receives data by storing a set of parameters in the string Str0. Depending upon what type of data you are trying to send or receive, Str0 will have different values. For instance, if the modeler wanted to create and send a list of numbers in the list L1, it would be done as follows. Set the value of the list to some numbers (in this case, 20, A, and B where A and B are number variables that are set previously in the calculator code). Then write:

{20,A,B}->L1
"1 L1"->Str0
Asm(prgmSENDVAR) 

The length of the list of numbers that a calculator sends depends on what information you want to send to the NetLogo model. Further, how those numbers are interpreted by the model is also up to you.

You can also receive data from the NetLogo model. To do this, use the following calculator code:

"4 Str6 1"->Str0
Asm(prgmGETVAR)

Let's take a look at how the values of the string Str0 are set. The first input in the string represents the type of variable that you are trying to get. Since we are trying to get a string (Str6), we give the first input the value 4. (See below for the values of legal data types.) The second input is the variable in which you would like to save the data received. In this case, we want to save the data to the variable Str6. The third input tells how you would like to save this data into this variable. (See below for values of valid commands.) It should be noted that for sending a variable, the command defaults to 0, i.e. no command.

data typeassociated value
number0
list of numbers1
matrix of numbers2
string4

command numbercommand explanation
0No Command
1Collate (Lists into a matrix, reals into a list, append strings)
2Teacher Variable
4Append Lists

You should note that you must always save the information into the variable Str0 when you are sending or receiving information from the calculators. You can't use any other variable.

For more information on writing the calculator program portion of a HubNet Activity, please contact us.

Saving

The data sent by calculators or NetLogo is saved in the order that the server receives the data.

Computer HubNet Information

The following information is specific to Computer HubNet.

How To Make an Interface for a Client

Open a new model in NetLogo. Add any interface buttons, sliders, switches, monitors, plots, choosers, or text boxes that you want in the Interface Tab. For buttons and monitors, you only need to type a Display Name. Any code you write in the Code or Reporter sections will be ignored. The Display Name you give to the interface element is the tag that is returned by the hubnet-message-tag reporter in the NetLogo code.

For example, if in the Interface Tab of the client interface you had a button called "Move Left", a slider called "step-size", a switch called "all-in-one-step?", and a monitor called "Location:", the tags for these interface elements will be as follows:

interface elementtag
Move LeftMove Left
step-sizestep-size
all-in-one-step?all-in-one-step?
Location:Location:

Be aware that this causes the restriction that you can only have one interface element with a specific name. Having more than one interface element with the same Display Name in the client interface will cause funny things to happen. For instance, if we had a monitor called Milk Supply and a plot named Milk Supply, when we send data to the client using the tag Milk Supply, the client will just pick either the plot or the monitor to give the data to.

Be aware that if you wish to have a Graphics Window in the client for a model, the Graphics Window in the client and the one in the NetLogo model must have the same number of patches and the same patch size. If they do not, the Graphics Window on the client will not display information sent by the server.

If you wish to make a client without a Graphics Window in the client, you will have to hand edit the file after you have finished adding all the other interface elements in NetLogo. To do this, open the client file in a text editor such as Notepad on Windows, or TextEdit on Macs. You should see a file that starts with something similar to this:

; add model procedures here

@#$#@#$#@
GRAPHICS-WINDOW
321
10
636
325
17
17
9.0
1
10
0
0

CC-WINDOW
323
339
638
459
Command Center

You should remove all the text that is in the GRAPHICS-WINDOW section and then save the file. So that after you are done the beginning of the file should look similar to this:

; add model procedures here

@#$#@#$#@
CC-WINDOW
323
339
638
459
Command Center

For more examples, study the models and interface files in the "HubNet Computer Activities" section of the Models Library. Disease.nlogo and Disease client.nlogo are good ones to start with.

Graphics Window Updates on the Clients

Currently, there are two ways of sending the clients the Graphics Window. The first way is done automatically by NetLogo and HubNet when Graphics Window mirroring is enabled and the client has a Graphics Window in the interface. Whenever a patch or turtle is redrawn in the NetLogo Graphics Window, it will be redrawn on all the clients. Actually, updates are accumulated and sent out periodically (about five times a second). This means that a lot of messages can be sent to the clients if a lot of turtles or patches are being redrawn. It is possible to reduce the number of messages sent to the clients, and thus possibly speed up the model, by making the Graphics Window in the model not update. This can be done using the no-display and display primitives or by toggling the display on/off switch in the Graphics Window Control Strip.

A second way of sending the clients the Graphics Window is to use the hubnet-broadcast-graphics and hubnet-send-graphics primitives. hubnet-broadcast-graphics and hubnet-send-graphics both send the entire Graphics Window to the clients instead of just the patches that need to be redrawn. This makes them less efficient, but for some models this is feature is necessary. To send the Graphics Window to the clients using this scheme, you must use the following NetLogo code:

hubnet-broadcast-graphics

to send to all the logged in clients.

To just send the Graphics Window to a subset of all the clients use:

hubnet-send-graphics user-name-list

where user-name-list is either a single string or a list of strings of the user names of clients that you want to send it to.

It should be mentioned that if there is no Graphics Window in the clients or if the Mirror Graphics Window on Clients checkbox in the HubNet Control Center is not checked, then no graphics messages are sent to the clients.

NOTE: Since hubnet-broadcast-graphics and hubnet-send-graphics are experimental primitives, their behaviors may change in a future release.

Plot Updates on the Clients

Plots on the clients are updated in the following way. If a change occurs on a NetLogo plot and a plot with the exact same name exists on the clients, a message with that change is sent to the clients causing the client's plot to make the same change. For example, let's pretend there is a HubNet model that has a plot called Milk Supply in NetLogo and the clients. Milk Supply is the current plot in NetLogo and in the command center you type

plot 5

This will cause a message to be sent to all the clients telling them that they need to plot a point with a y value of 5 in the next position of the plot. Notice, if you are doing a lot of plotting all at once, this can generate a lot of plotting messages to be sent to the clients.

It should be mentioned that if there is no plot with the exact same name in the clients or if the Mirror Plots on Clients checkbox in the HubNet Control Center is not checked, then no plot updates are sent to the clients.

Clicking in the Graphics Window on Clients

If the Graphics Window is included in the client, it is possible for the client to send locations in the Graphics Window to NetLogo by clicking in the client's Graphics Window. The tag reported by hubnet-message-tag for client clicks is the same as what is needed to send the Graphics Window to a client, the string "Graphics Window". hubnet-message reports a two item list with the x coordinate being the first item and the y coordinate being the second item. So for example, to turn any patch that was clicked on by the client red, you would use the following NetLogo code:

if hubnet-message-tag = "Graphics Window"
[
  ask patches with [ pxcor = (round item 0 hubnet-message) and 
                     pycor = (round item 1 hubnet-message) ]
  [ set pcolor red ]
]

Text Area for Input and Display

A few models use an experimental interface element in the HubNet client that allows the modeler to display text on the client that can change throughout the run of the activity. Further, it can allow users to send text back to the server. If you are interested in using it in an activity, please contact us for further information.