This explains how to use NetLogo to modify the existing HubNet activities or build your own, new HubNet activities.
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.
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.
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:
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.
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
These primitives are usually best called from the startup procedure of the NetLogo model since they should only be called once in a model.
The data extraction primitives are:
There are two additional data extraction primitives that are only used in Computer HubNet models.
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.
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:
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 type | hubnet-broadcast example | hubnet-send example |
|---|---|---|
| number | hubnet-broadcast "A" 3.14 | hubnet-send "jimmy" "A" 3.14 |
| string | hubnet-broadcast "STR1" "HI THERE" | hubnet-send ["12" "15"] "STR1" "HI THERE" |
| list of numbers | hubnet-broadcast "L2" [1 2 3] | hubnet-send hubnet-message-source "L2" [1 2 3] |
| matrix of numbers | hubnet-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"]] |
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.
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 type | associated value |
|---|---|
| number | 0 |
| list of numbers | 1 |
| matrix of numbers | 2 |
| string | 4 |
| command number | command explanation |
|---|---|
| 0 | No Command |
| 1 | Collate (Lists into a matrix, reals into a list, append strings) |
| 2 | Teacher Variable |
| 4 | Append 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.
The data sent by calculators or NetLogo is saved in the order that the server receives the data.
The following information is specific to Computer HubNet.
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 element | tag |
|---|---|
| Move Left | Move Left |
| step-size | step-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.
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.
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.
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 ]
]
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.