Documentation Tutorials Download Contribute



[//]: # (keyword concept_network)
[//]: # (startConcept network)

Using network

Introduction

GAMA provides features to allow agents to communicate with other agents (and other applications) through network and to exchange messages of various types (from simple number to agents). To this purpose, the network skill should be used on agents intending to use these capabilities.

Notice that in this communication, roles are asymetric: the simulations should contain a server and some clients to communicate. Message exchanges are made between agents through this server. 3 protocols are supported (TCP, UDP and MQTT):

  • when TCP or UDP protocols are used: one agent of the simulation is the server and the other ones are the clients.
  • when the MQTT protocol is used: all the agents are clients and the server is an external software. A free solution (ActiveMQ) can be freely downloaded from: http://activemq.apache.org.

Which protocol to use ?

In the GAMA network, 3 kinds of protocol can be used. Each of them has a particular purpose.

  • MQTT: this is the default protocol that should be used to make agents of various GAMA instances to communicate through a MQTT server (that should be run as an external application, e.g. ActiveMQ that can be downloaded from: http://activemq.apache.org/),
  • UDP: this protocol should be limited to fast (and unsecured) exchanges of small pieces of data from GAMA to an external application (for example, mouse location from a Processing application to GAMA, c.f. model library),
  • TCP: this protocol can be used both to communicate between GAMA applications or between GAMA and an external application.

Disclaimer

In all the models using any network communication, the server should be launched before the clients. As a consequence, when TCP or UDP protocols are used, a model creating a server agent should always be run first. Using MQTT protocol, the external software server should be launched before running any model using it.

Declaring a network species

To create agents able to communicate through a network, their species should have the skill network:

species Networking_Client skills: [network] {
   ...
}

A list exhaustive of the additional attributes and available actions provided by this skill are described here: network skill preference page.

Creation of a network agent

The network agents are created as any other agents, but (in general) at the creation of the agents, the connection is also created, using the connect built-in action:

create Networking_Client {
    do connect to: "localhost" protocol: "tcp_client" port: 3001 with_name: "Client";
}

Each protocol has its specificities regarding the connection:

  • TCP:
    • protocol: the 2 possibles keywords are tcp_server or tcp_client, depending on the wanted role of the agent in the communication.
    • port: traditionally the port 3001 is used.
  • UDP:
    • protocol: the 2 possibles keywords are udp_server or udp_emitter, depending on the wanted role of the agent in the communication.
    • port: traditionally the port 9876 is used.
  • MQTT:
    • protocol: MQTT is the default protocol value (if no value is given, MQTT will be used)

Sending messages

To send any message, the agent has to use the send action:

    do send to: "send" contents: name + " " + cycle + " sent to server";

Receiving messages

The messages sent by other agents are received in the mailbox attribute of each agent. So to get its new message, the agent has simply to check whether it has new messages (with action has_more_message() ) and fetch it (that is get it and remove it from the mailing box) with the action fetch_message().

reflex fetch when: has_more_message() {	
    message mess <- fetch_message();
    write name + " fecth this message: " + mess.contents;	
}

Alternatively, the mailbox attribute can be directly accessed (notice that the mailbox is a list of messages):

reflex receive {  
    if (length(mailbox) > 0) {
        write mailbox;
    }
}

Broadcasting a message to all the agents members of a given group

Each time an agent create a connection to another agent as a client, a way to communicate with it is stored in the network_groups attribute. So an agent can use this attribute to broadcast messages to all the agents with whose it can communicate:

reflex broad {
    loop id over: network_groups {
        do send to: id contents: "I am Server " + name + " I give order to " + id;
    }
}

To go further: