Webots Reference Manual - chapter 3 - section 23

Webots Reference Manual


3.23 Emitter

Derived from Device.

Emitter {
  SFString   type         "radio"  # or "serial" or "infra-red"
  SFFloat    range        -1       # -1 or positive
  SFFloat    maxRange     -1       # -1 or positive
  SFFloat    aperture     -1       # -1 or between 0 and 2*pi
  SFInt32    channel      0
  SFInt32    baudRate     -1       # -1 or positive
  SFInt32    byteSize     8        # 8 or more
  SFInt32    bufferSize   4096     # positive
}

3.23.1 Description

The Emitter node is used to model radio, serial or infra-red emitters. An Emitter node must be added to the children of a robot or a supervisor. Please note that an emitter can send data but it cannot receive data. In order to simulate a unidirectional communication between two robots, one robot must have an Emitter while the other robot must have a Receiver. To simulate a bidirectional communication between two robots, each robot needs to have both an Emitter and a Receiver. Note that messages are never transmitted from one robot to itself.

3.23.2 Field Summary

Emitter nodes can also be used to communicate with the physics plugin (see chapter 6). In this case the channel must be set to 0 (the default). In addition it is highly recommended to choose -1 for the baudRate, in order to enable the fastest possible communication; the type, range and aperture will be ignored.

3.23.3 Emitter Functions



NAME

   wb_emitter_send - send a data packet to potential receivers

SYNOPSIS [C++] [Java] [Python] [Matlab]

  #include <webots/emitter.h>

  int wb_emitter_send(WbDeviceTag tag, const void *data, int size);

DESCRIPTION

The wb_emitter_send() function adds to the emitters's queue a packet of size bytes located at the address indicated by data. The enqueued data packets will then be sent to potential receivers (and removed from the emitter's queue) at the rate specified by the baudRate field of the Emitter node. Note that a packet will not be sent to its emitter robot. This function returns 1 if the message was placed in the sending queue, 0 if the sending queue was full. The queue is considered to be full when the sum of bytes of all the currently enqueued packets exceeds the buffer size specified by the bufferSize field. Note that a packet must have at least 1 byte.

The Emitter/Receiver API does not impose any particular format on the data being transmitted. Any user chosen format is suitable, as long as the emitter and receiver codes agree. The following example shows how to send a null-terminated ascii string using the C API:

language: C

char message[128];
sprintf(message, "hello%d", i);
wb_emitter_send(tag, message, strlen(message) + 1);

And here an example on how to send binary data with the C API:

language: C

double array[5] = { 3.0, x, y, -1/z, -5.5 };
wb_emitter_send(tag, array, 5 * sizeof(double));

language: Python
The send() function sends a string. For sending primitive data types into this string, the struct module can be used. This module performs conversions between Python values and C structs represented as Python strings. Here is an example:

import struct
#...
message = struct.pack("chd","a",45,120.08)
emitter.send(message)

language: Java
The Java send() method does not have a size argument because the size is implicitly passed with the data argument. Here is an example of sending a Java string in a way that is compatible with a C string, so that it can be received in a C/C++ controller.

String request = "You are number " + num + "\0";
try {
  emitter.send(request.getBytes("US-ASCII"));
}
catch (java.io.UnsupportedEncodingException e) {
  System.out.println(e);
}



NAME

   wb_emitter_set_channel, wb_emitter_get_channel - set and get the emitter's channel.

SYNOPSIS [C++] [Java] [Python] [Matlab]

  #include <webots/emitter.h>

  void wb_emitter_set_channel(WbDeviceTag tag, int channel);
  int wb_emitter_get_channel(WbDeviceTag tag);

DESCRIPTION

The wb_emitter_set_channel() function allows the controller to change the transmission channel. This modifies the channel field of the corresponding Emitter node. Normally, an emitter can send data only to receivers that use the same channel. However, the special WB_CHANNEL_BROADCAST value can be used for broadcasting to all channels. By switching the channel number an emitter can selectively send data to different receivers. The wb_emitter_get_channel() function returns the current channel number of the emitter.

language: C++, Java, Python
In the oriented-object APIs, the WB_CHANNEL_BROADCAST constant is available as static integer of the Emitter class (Emitter::CHANNEL_BROADCAST).


NAME

   wb_emitter_set_range, wb_emitter_get_range - set and get the emitter's range.

SYNOPSIS [C++] [Java] [Python] [Matlab]

  #include <webots/emitter.h>

  void wb_emitter_set_range(WbDeviceTag tag, double range);
  double wb_emitter_get_range(WbDeviceTag tag);

DESCRIPTION

The wb_emitter_set_range() function allows the controller to change the transmission range at run-time. Data packets can only reach receivers located within the emitter's range. This function modifies the range field of the corresponding Emitter node. If the specified range argument is larger than the maxRange field of the Emitter node then the current range will be set to maxRange. The wb_emitter_get_range() function returns the current emitter's range. For both the wb_emitter_set_range() and emitter_get_range() functions, a value of -1 indicates an infinite range.



NAME

   wb_emitter_get_buffer_size - get the transmission buffer size

SYNOPSIS [C++] [Java] [Python] [Matlab]

  #include <webots/emitter.h>

  int wb_emitter_get_buffer_size(WbDeviceTag tag);

DESCRIPTION

The wb_emitter_get_buffer_size() function returns the size (in bytes) of the transmission buffer. This corresponds to the value specified by the bufferSize field of the Emitter node. The buffer size indicates the maximum number of data bytes that the emitter's queue can hold in total. When the buffer is full, calls to wb_emitter_send() will fail and return 0.

release 7.0.2
Copyright © 2012 Cyberbotics Ltd. All right reserved.