Package ptolemy.actor.lib.io.comm

Class SerialComm

  • All Implemented Interfaces:
    java.lang.Cloneable, Actor, Executable, FiringsRecordable, Initializable, TypedActor, Changeable, Debuggable, DebugListener, Derivable, Instantiable, ModelErrorHandler, MoMLExportable, Moveable, Nameable
    public class SerialComm
extends TypedAtomicActor
    Send and receive bytes via the serial port. The serial port and baud rate are specified by parameters.

    This actor requires that the RXTX serial port API be installed from http://mfizz.com/oss/rxtx-for-java.

    Under Windows, download the zip file, then do something like:

     cp ~/src/rxtx/mfz-rxtx-2.2-20081207-win-x64/RXTXcomm.jar c:/Program\ Files/Java/jdk1.7.0_51/jre/lib/ext/
 cp ~/src/rxtx/mfz-rxtx-2.2-20081207-win-x64/*.dll c:/Program\ Files/Java/jdk1.7.0_51/jre/bin

    And then rerun (cd $PTII;./configure)

    This actor can be used in most domains, but the parameters must be chosen carefully to match the domain semantics. This actor sets up a listener to the serial port, and when input data appears on the serial port, it calls fireAtCurrentTime() on the director. This behavior is useful in the DE domain, for example (although you will likely have to set the stopWhenQueueIsEmpty parameter of the director false).

    Some domains, however, such as SDF, ignore the fireAtCurrentTime() call. Such domains, will typically fire this actor when its outputs are needed. Consequently, for use in such domains, you will likely want to set the blocking parameter of this actor to true. When this parameter is true, the fire() method first reads data on its input port (if any) and writes it to the serial port, and then blocks until sufficient input data are available at the serial port. It then reads that data from the serial port and packages it as a byte array to produce on the output of this actor.

    The inputs and outputs of this actor are unsigned byte arrays. The minimumOutputSize parameter specifies the minimum number of bytes that are produced on the output in each firing. The maximumOutputSize parameter specifies the maximum number of bytes that are produced on the output on each firing. If these two numbers are equal, then when a firing produces data, it will always produce the same amount of data. Otherwise, the amount of data produced is nondeterministic.

    The discardOldData parameter, if true, indicates that the fire() method may discard bytes. In particular, if there are more than maximumOutputSize bytes available on the serial port, then all but the most recent maximumOutputSize will be discarded.

    For example, if you wish for this actor to produce only the most recent byte read on the serial port each time it fires, set discardOldData to true, blocking to true, and both minimumOutputSize and maximumOutputSize to 1.

    If after firing there are additional data available on the input port, then the fire() method will call fireAtCurrentTime() on the director before returning.

    Note that if there are multiple instances of this actor in a model, then unless the model designer has taken special care to ensure sequential execution of the actor, inputs from the serial port may be nondeterministically received by any of the actors.

    Since:
    Ptolemy II 2.0
    Version:
    $Id$
    Author:
    Winthrop Williams, Joern Janneck, Xiaojun Liu, Edward A. Lee (Based on my RxDatagram, and on the IRLink class written by Xiaojun Liu)
    Pt.AcceptedRating:
    red (winthrop)
    Pt.ProposedRating:
    red (winthrop)

    • Field Detail

      • baudRate

        public Parameter baudRate
        The baud rate of the serial port, such as 19200 (the default), 19200, or 115200, for the serial port. This has type integer and defaults to 19200.

      • blocking

        public Parameter blocking
        Indicator of whether fire method is blocking. If true, fire() waits until minimumOutputSize bytes have arrived. The type is boolean with default false.

      • dataToSend

        public TypedIOPort dataToSend
        The input port for data to be sent to the serial port. This port has type unsigned byte array.

      • dataReceived

        public TypedIOPort dataReceived
        The output port for data that has been received by the serial port. This port has type unsigned byte array.

      • discardOldData

        public Parameter discardOldData
        Indicator of whether to discard old data. If this is true, then the fire() method will read all available data, but produce no more than maximumOutputSize bytes on the output, discarding the rest. This is a boolean that defaults to false.

      • maximumOutputSize

        public Parameter maximumOutputSize
        The maximum number of bytes produced in each firing on the output. This is an integer that defaults to MaxInt. It is required to be at least as large as minimumOutputSize

      • minimumOutputSize

        public Parameter minimumOutputSize
        The minimum number of bytes that will be read from the serial port and produced on the output. This is required to be a strictly positive integer, and it defaults to 1.

      • serialPortName

        public StringParameter serialPortName
        Attribute giving the serial port to use. This is a string with the default being the first serial port listed by the javax.comm.CommPortIdentifier class. If there are no serial ports available (meaning probably that the javax.comm package is not installed properly), then the value of the string will be "no ports available".

    • Method Detail

      • attributeChanged

        public void attributeChanged​(Attribute attribute)
                      throws IllegalActionException
        If the parameter changed is serialPortName, then hope the model is not running and do nothing. Likewise for baudRate.
        Overrides:
        attributeChanged in class NamedObj
        Parameters:
        attribute - The attribute that changed.
        Throws:
        IllegalActionException - Not thrown in this base class.

      • fire

        public void fire()
          throws IllegalActionException
        If input data is available at the serial port, read it and produce it as a byte array at the output port of this actor; if a token is available at the input port of this actor, consume it and send the bytes contained by this token to the serial port. If blocking is true, then after writing the input data to the serial port, stall the calling thread until there are input data available at the serial port. The minimumOutputSize specifies the minimum number of bytes that must be available.

        Before returning, if data is sent to the serial port, this method calls flush(). However, the flush() method does not wait for the hardware to complete the transmission, as this might take many milliseconds (roughly 1mS for every 10 bytes at 115200 baud). Consequently, the data will not have been completely produced on the serial port when this returns.

        If data is still available on the serial port when this returns, then before returning it calls fireAtCurrentTime() on the director.

        Before this method exits, it will either call fireAtCurrentTime() on the director (if there is already enough input data on the serial port to be able to fire again and produce the requisite number of outputs), or it will start a thread that will wait until there is enough data and then call fireAtCurrentTime().

        Specified by:
        fire in interface Executable
        Overrides:
        fire in class AtomicActor<TypedIOPort>
        Throws:
        IllegalActionException - Not thrown in this base class.