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.
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.
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 "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
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.
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:
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.
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
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:
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 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 "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"]] |
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 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.
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 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.
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.
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.
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 ]
]
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.