Package ptolemy.domains.wireless.lib

Class CollisionDetector

  • All Implemented Interfaces:
    java.lang.Cloneable, Actor, Executable, FiringsRecordable, Initializable, TypedActor, Changeable, Debuggable, DebugListener, Derivable, Instantiable, ModelErrorHandler, MoMLExportable, Moveable, Nameable
    public class CollisionDetector
extends TypedAtomicActor
    This actor models a typical physical layer front end of a wireless receiver. It models a receiver where messages have a non-zero duration and messages can collide with one another, causing a failure to receive. A message is provided to this actor at the time corresponding to the start of its transmission. Along with the message (an arbitrary token), the inputs must provide the duration of the message and its power. The message spans an interval of time starting when it is provided to this actor and ending at that time plus the duration. If another message overlaps with a given message and has sufficient power, then the given message will be sent to the collided output. Otherwise it is sent to the received output. In both cases, the message appears at the corresponding output at the time it is received plus the duration (i.e. the time at which the message has been completed).

    The inputs are:

    • message: The message carried by each transmission.
    • power: The power of the received signal at the location of this receiver.
    • duration: The time duration of the transmission.
    The power and duration are typically delivered by the channel in the "properties" field of the transmission. The power is usually given as a power density (per unit area) so that a receiver can multiply it by its antenna area to determine the received power. It is in a linear scale (vs. DB), typically with units such as watts per square meter. The duration is a non-negative double, and the message is an arbitrary token.

    The outputs are:

    • received: The message received. This port produces an output only if the received power is sufficient and there are no collisions. The output is produced at a time equal to the time this actor receives the message plus the value received on the duration input.
    • collided: The message discarded. This port produces an output only if the received message collides with another message of sufficient power. The output is produced at a time equal to the time this actor receives the message plus the value received on the duration input. The value of the output is the message that cannot be received.

    This actor is typically used with a channel that delivers a properties record token that contains power and duration fields. These fields can be extracted by using a GetProperties actor followed by a RecordDisassembler. The PowerLossChannel, for example, can be used. However, in order for the type constraints to be satisfied, the PowerLossChannel's defaultProperties parameter must be augmented with a default value for the duration. Each transmitter can override that default with its own message duration and transmit power.

    Any message whose power (as specified at the power input) is less than the value of the powerThreshold parameter is ignored. It will not cause collisions and is not produced at the collided output. The powerThreshold parameter thus specifies the power level at which the receiver simply fails to detect the signal. It is given in a linear scale (vs. DB) with the same units as the power input. The default value is zero, i.e. by default it won't ignore any received signal.

    Any message whose power exceeds powerThreshold has the potential of being successfully received, of failing to be received due to a collision, and of causing a collision. A message is successfully received if throughout its duration, its power exceeds the sum of all other message powers by at least SNRThresholdInDB (which as the name suggests, is given in decibels, rather than in a linear scale, as is customary for power ratios). Formally, let the message power for the i-th message be pi(t) at time t. Before the message is received and after its duration expires, this power is zero. The i-th message is successfully received if

    pi(t) ≥ P Σ(j != i) pj(t)
    for all t where pi(t) > 0, where
    P = 10^(SNRThresholdInDB/10)
    which is the signal to interference ratio in a linear scale.

    The way this actor works is that each input that has sufficient power is recorded in a hash table indexed by the time at which its duration expires. In addition, the director is requested to fire this actor at that time. Any time a message arrives, the actor checks for collisions, and marks any message subjected to a collision by this arrival. When the duration expires, the message is produced on one of the two outputs depending on whether it is marked as having encountered a collision, and it is removed from the hash table.

    NOTE: This actor assumes that the duration of messages is short relative to the rate at which the actors move. That is, the received power (and whether a receiver is in range) is determined once, at the time the message starts, and remains constant throughout the transmission. It also requires that all three inputs have tokens when fired.

    Since:
    Ptolemy II 4.0
    Version:
    $Id$
    Author:
    Yang Zhao, Xiaojun Liu, Edward Lee
    See Also:
    PowerLossChannel, GetProperties, RecordDisassembler
    Pt.AcceptedRating:
    Yellow (cxh)
    Pt.ProposedRating:
    Green (cxh)

    • Field Detail

      • message

        public TypedIOPort message
        The input port for the message. This has undeclared type.

      • power

        public TypedIOPort power
        The input port for power. This has type double, and is typically a power density, in units such as watts per square meter.

      • duration

        public TypedIOPort duration
        The input port for the time that a message transmission takes. This has type double.

      • received

        public TypedIOPort received
        The output port that produces messages that are successfully received. This has the same type as the message input.

      • collided

        public TypedIOPort collided
        The output port that produces messages that cannot be received because of a collision. This has the same type as the message input.

      • SNRThresholdInDB

        public Parameter SNRThresholdInDB
        The threshold for the signal to be recognized from interference. It is specified in decibels (10 * log10(r), where r is the power ratio. This is a double that defaults to Infinity, which indicates that all overlapping messages are lost to collisions.

      • powerThreshold

        public Parameter powerThreshold
        The power threshold above which the signal can be detected at the receiver. Any message with a received power below this number is ignored. This has type double and defaults to 0.0, which indicates that all messages (with nonzero power) will be received.

    • Constructor Detail

      • CollisionDetector

        public CollisionDetector​(CompositeEntity container,
                         java.lang.String name)
                  throws IllegalActionException,
                         NameDuplicationException
        Construct an actor with the specified name and container. The container argument must not be null, or a NullPointerException will be thrown. If the name argument is null, then the name is set to the empty string. This constructor write-synchronizes on the workspace.
        Parameters:
        container - The container.
        name - The name of the actor.
        Throws:
        IllegalActionException - If the container is incompatible with this actor.
        NameDuplicationException - If the name coincides with an actor already in the container.

    • Method Detail

      • attributeChanged

        public void attributeChanged​(Attribute attribute)
                      throws IllegalActionException
        If the specified attribute is SNRThresholdInDB, or powerThreshold then check that a non-negative number is given. Otherwise, defer to the base class.
        Overrides:
        attributeChanged in class NamedObj
        Parameters:
        attribute - The attribute that changed.
        Throws:
        IllegalActionException - If the change is not acceptable to this container.

      • clone

        public java.lang.Object clone​(Workspace workspace)
                       throws java.lang.CloneNotSupportedException
        Clone the object into the specified workspace. The new object is not added to the directory of that workspace (you must do this yourself if you want it there). The result is an object with no container.
        Overrides:
        clone in class TypedAtomicActor
        Parameters:
        workspace - The workspace for the cloned object.
        Returns:
        The new Attribute.
        Throws:
        java.lang.CloneNotSupportedException - Not thrown in this base class
        See Also:
        NamedObj.exportMoML(Writer, int, String), NamedObj.setDeferringChangeRequests(boolean)

      • fire

        public void fire()
          throws IllegalActionException
        If a new message is available at the inputs, record it in the list indexed with the time that the message shall be completed, and loop through the list to check whether there is collision. If the current time matches one of the times that we have previously recorded as the completion time for a transmission, then output the received message to the received output port if it is not lost to a collision; otherwise, output it to the collided output port.
        Specified by:
        fire in interface Executable
        Overrides:
        fire in class AtomicActor<TypedIOPort>
        Throws:
        IllegalActionException - If an error occurs reading or writing inputs or outputs.