HubNet Authoring Guide

Setup

To make a NetLogo model into a HubNet activity you must first initialize the network. In most HubNet activities you will use the startup procedure to initialize the network. startup is a special procedure that NetLogo runs automatically when you open any model. That makes it a good place to put code that you want to run once and only once (no matter how many times the user runs the model). For HubNet we put the command that initializes the network in startup because once the network is setup we don't need to do so again. We initialize the system using hubnet-reset, which will ask the user for a session name and open up the HubNet Control Center. Here is the startup procedure in the template model:

to startup
  hubnet-reset
end

Now that the network is all setup you don't need to worry about calling hubnet-reset again. Take a look at the setup procedure in the template model:

to setup
  cp
  cd
  clear-output
  ask turtles
  [
    set step-size 1
    hubnet-send user-id "step-size" step-size
  ]
end

For the most part it looks like most other setup procedures, however, you should notice that it does not call clear-all. In this model, and in the great majority of HubNet activities in the Models Library, we have a breed of turtles that represent the currently logged in clients. In this case we've called this breed students. Whenever a client logs in we create a student and record any information we might need later about that client in a turtle variable. Since we don't want to require users to log out and log back in every time we setup the activity we don't want to kill all the turtles, instead, we want to set all the variables back to initial values and notify the clients of any changes we make (more on that later).

Receiving messages from clients

During the activity you will be transferring data between the HubNet clients and the server. Most HubNet activities will call a procedure in the go loop that checks for new messages from clients in this case it's called listen clients:

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

As long as there are messages in the queue this loop fetches each message one at a time. hubnet-fetch-message makes the next message in the queue the current message and sets the reporters hubnet-message-source, hubnet-message-tag, and hubnet-message to the appropriate values. The clients send messages when the users login and logout any time the user manipulates one of the interface elements, that is, pushes a button, moves a slider, clicks in the view, etc. We step through each message and decide what action to take depending on the type of message (enter, exit, or other), the hubnet-message-tag (the name of the interface element), and the hubnet-message-source of the message (the name of the client the message came from).

On an enter message we create a turtle with a user-id that matches the hubnet-message-source which is the name that each user enters upon entering the activity, it is guaranteed to be unique.

to create-new-student
  create-students 1
  [
    set user-id hubnet-message-source
    set label user-id
    set step-size 1
    send-info-to-clients
  ]
end

At this point we set any other client variables to default values and send them to the clients if appropriate. We declared a students-own variable for every interface element on the client that holds state, that is, anything that would be a global variable on the server, sliders, choosers, switches and input boxes. It is important to make sure that these variables stay synchronized with the values visible on the client.

When the clients logout they send an exit message to the server which gives you a chance to clean up any information you have been storing about the client, in this case we merely have to ask the appropriate turtle to die.

to remove-student
  ask students with [user-id = hubnet-message-source]
  [ die ]
end

All other messages are interface elements identified by the hubnet-message-tag which is the name that appears in the client interface. Every time an interface element changes a message is sent to the server. Unless you store the state of the values currently displayed in the client interface will not be accessible in other parts of the model. That's why we've declared a students-own variable for every interface element that has a state (sliders, switches, etc). When we receive the message from the client we set the turtle variable to the content of the message:

if hubnet-message-tag = "step-size"
[
  ask students with [user-id = hubnet-message-source]
    [ set step-size hubnet-message ]
]

Since buttons don't have any associated data there is generally no associated turtle variable, instead they indicate an action taken by the client, just as with a regular button there is often procedure associated with each button that you call whenever you receive a message indicating the button has been pressed. Though it is certainly not required, the procedure is often a turtle procedure, that is, something that the student turtle associated with the message source can execute:

if command = "move left"
[ set heading 270
  fd 1 ]

Sending messages to clients

As mentioned earlier you can also send values to any interface elements that display information: monitors, sliders, switches, choosers, and input boxes (note that plots and the view are special cases that have their own sections).

There are two primitives that allow you to send information hubnet-send and hubnet-broadcast. Broadcast sends the information to all the clients; send sends to one client, or a selected group.

As suggested earlier, nothing on the client updates automatically. If a value changes on the server, it is your responsibility as the activity author to update monitors on the client.

For example, say you have a slider on the client called step-size and a monitor called Step Size (note that the names must be different) you might write updating code like this:

if hubnet-message-tag = "step-size"
[
  ask student with [ user-id = hubnet-message-source ]
  [
    set step-size hubnet-message
    hubnet-send user-id "Step Size" step-size
  ]
]

You can send any type of data you want, numbers, strings, lists, lists of lists, lists of strings, however, if the data is not appropriate for the receiving interface element (say, if you were to send a string to a slider) the message will be ignored. Here are a few code examples for different types of data:

Examples

Study the models in the "HubNet Activities" section of the Models Library to see how these primitives are used in practice in the Code tab. Disease is a good one to start with.