HubNet Authoring Guide

NetLogo 3.1.5 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

This section will introduce the set of primitives used to turn a NetLogo Model into a HubNet Activity. These commands allow you to send data to and receive data from the clients.

Setup

In order to make a NetLogo model into a HubNet Activity, it is necessary to first indicate whether the clients are computers or calculators and then establish a connection between the server (your computer) and the clients (the students' calculators or computers) using the following primitives:

hubnet-set-client-interface client-type client-info
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 "COMPUTER" [ "clients/Disease client.nlogo" ]
			;; when clients log in, they 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 use any other HubNet primitives including hubnet-reset so NetLogo knows which type of HubNet you are going to be using.
hubnet-reset
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 you are using Computer HubNet, you will be prompted for a session name. This is an identifier to make servers discovered by the client uniquely identifiable.

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

Data extraction

During the activity you will be transferring data between the HubNet clients and the server. The following primitives allow you to extract data from the clients:

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.

Generally part of your go procedure will include checking for waiting messages and handling them.

to listen-clients
  while [ hubnet-message-waiting? ]
  [
    hubnet-fetch-message
    ifelse hubnet-enter-message?
    [ create-new-student ]
    [
      ifelse hubnet-exit-message?
      [ remove-student ]
      [ execute-command hubnet-message-tag ]
    ]
  ]
end

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.

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-view
This broadcasts the current state of the 2D View in the NetLogo model to all the Computer HubNet Clients. It does nothing for Calculator HubNet.
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-view string
hubnet-send-view list-of-strings
For Calculator HubNet, does nothing.
For Computer HubNet, it acts as follows: Note: Sending the View to a non-existent client, using hubnet-send-view, generates a hubnet-exit-message.

When using Calculator HubNet the hubnet-send and the hubnet-broadcast primitives, take a number, a string, a list of numbers, or a matrix (a list of lists) of numbers as the value input. When using 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 "susie" "[A]" [[1 2] [3 4]]
list of strings (only for Computer HubNet)hubnet-broadcast "user-names" [["jimmy" "susie"] ["bob" "george"]]hubnet-send "teacher" "user-names" [["jimmy" "susie"] ["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 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.

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 unpredictable behavior. 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.

If you wish to have a View in the client for a model, the view 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 view on the client will not display information sent by the server.

If you wish to make a client without a view 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.

View Updates on the Clients

Currently, there are two ways of sending the clients the View. The first way is done automatically by NetLogo and HubNet when 2D View mirroring is enabled and the client has a View in the interface. Whenever a patch or turtle is redrawn in the NetLogo View, 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 View 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 View Control Strip.

A second way of sending the clients the View is to use the hubnet-broadcast-view and hubnet-send-view primitives. hubnet-broadcast-view and hubnet-send-view both send the entire View 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 View to the clients using this scheme, you must use the following NetLogo code:

hubnet-broadcast-view

to send to all the logged in clients.

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

hubnet-send-view 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.

If there is no View in the clients or if the Mirror View on Clients checkbox in the HubNet Control Center is not checked, then no view messages are sent to the clients.

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

Note: Some of the View features in NetLogo are not yet implemented on the HubNet clients such as View Wrapping and Observer Perspectives.

Plot Updates on the Clients

When a plot in the NetLogo model changes 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.

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 View on Clients

If the View is included in the client, it is possible for the client to send locations in the View to NetLogo by clicking in the client's View. The tag reported by hubnet-message-tag for client clicks is the same as what is needed to send the View to a client, the string "View". 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 = "View"
[
  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.