Derived from Solid.

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.17.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 supervisor. Please note that an emitter can send data but cannot receive it; in order to achieve bidirectional communication, a robot needs to have both an Emitter and a Receiver on board.

3.17.2 Field Summary

• type: type of signals: "radio", "serial" or "infra-red". Signals of type "radio" (the default) and "serial" are transmitted without taking obstacles into account. Signals of type "infra-red," however, do take potential obstacles between the emitter and the receiver into account. Any solid object (solid, robots, etc ...) with a defined bounding object is a potential obstacle to an "infra-red" communication. The structure of the emitting or receiving robot itself will not block an "infra-red" transmission. Currently, there is no implementation difference between the "radio" and "serial" types.

• range: radius of the emission sphere of the emitter (in meters). A receiver can only receive a message if it is located within the emission sphere. A value of -1 (the default) for range is considered to be an infinite range.

• maxRange: defines the maximum value allowed for range. This field defines the maximum value that can be set using emitter_set_range(). A value of -1 (the default) for maxRange is considered to be infinite.

• aperture: for "infra-red" only: opening angle of the emission cone (in radians). The cone's apex is located at the origin ([0 0 0]) of the emitter's coordinate system and the cone's axis coincides with the z-axis of the emitter coordinate system. An "infra-red" emitter can only send data to receivers currently located within its emission cone. An aperture of -1 (the default) is considered to be infinite, meaning that the emitted signals are omnidirectional. For "radio" and "serial" emitters, this field is ignored. See figure 3.10 for an illustration of range and aperture.

  

  Figure 3.10: Illustration of aperture and range for "infra-red" Emitter/Receiver

• channel: transmission channel. This is an identification number for an "infra-red" emitter or a frequency for a "radio" emitter. Normally a receiver must use the same channel as an emitter to receive the emitted data. However, the special channel -1 allows broadcasting messages on all channels. Channel 0 (the default) is reserved for communicating with a physics plugin. For inter-robot communication, please use positive channel numbers.

• baudRate: the baud rate is the communication speed expressed in number of bits per second. A baudRate of -1 (the default) is regarded as infinite and causes the data to be transmitted immediately (within one control step) from emitter to receiver.

• byteSize: the byte size is the number of bits required to transmit one byte of information. This is usually 8 (the default), but can be more if control bits are used.

• bufferSize: specifies the size (in bytes) of the transmission buffer. The total number of bytes in the packets enqueued in the emitter cannot exceed this number.

Note: 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.17.3 Emitter Functions

NAME

C SYNOPSIS

C++ SYNOPSIS

JAVA SYNOPSIS

PYTHON SYNOPSIS

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. On success this function returns 1. If the queue is currently full, 0 is returned and the packet will not be enqueued. The queue is considered to be full when the sum of bytes of all the enqueued packets exceeds the buffer size specified by the bufferSize field. Note that a packet cannot be smaller than 1 byte. See the following usage example:

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

Note that the above example sends packets in the form of null-terminated strings. The Emitter/Receiver API does not put any restriction on the type of data that can be transmitted. Any user chosen format is suitable, as long as emitters and receivers agree.

Note: The Python send() function sends a string. For sending primitive data types into this string, the Python 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,len(message))   ...

NAME

C SYNOPSIS

C++ SYNOPSIS

JAVA SYNOPSIS

PYTHON SYNOPSIS

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.

Note: In the oriented-object APIs, the WB_CHANNEL_BROADCAST constant is available as static integer of the Emitter class (Emitter::CHANNEL_BROADCAST).

NAME

C SYNOPSIS

C++ SYNOPSIS

JAVA SYNOPSIS

PYTHON SYNOPSIS

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

C SYNOPSIS

C++ SYNOPSIS

JAVA SYNOPSIS

PYTHON SYNOPSIS

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_packet() will fail and return 0.

^ page top ^