diff options
Diffstat (limited to 'flow-main/src/main/scala/com/github/jodersky/flow/Serial.scala')
| -rw-r--r-- | flow-main/src/main/scala/com/github/jodersky/flow/Serial.scala | 26 |
1 files changed, 15 insertions, 11 deletions
diff --git a/flow-main/src/main/scala/com/github/jodersky/flow/Serial.scala b/flow-main/src/main/scala/com/github/jodersky/flow/Serial.scala index adcfb06..5c34487 100644 --- a/flow-main/src/main/scala/com/github/jodersky/flow/Serial.scala +++ b/flow-main/src/main/scala/com/github/jodersky/flow/Serial.scala @@ -4,18 +4,22 @@ import akka.actor.ActorRef import akka.actor.ExtensionKey import akka.util.ByteString -/** Defines messages used by serial IO layer. */ +/** Defines messages used by flow's serial IO layer. */ object Serial extends ExtensionKey[SerialExt] { - /** A message extending this trait is to be viewed as a command, that is an outbound message. */ + /** A message extending this trait is to be viewed as a command, that is an out-bound message. */ trait Command - /** A message extending this trait is to be viewed as an event, that is an inbound message. */ + /** A message extending this trait is to be viewed as an event, that is an in-bound message. */ trait Event /** - * Open a new serial port. Send this command to the serial manager to request the opening of a new port. - * @param handler actor that will receive events from the specified serial port + * Open a new serial port. Send this command to the serial manager to request the opening of a serial port. The manager will + * attempt to open a serial port with the specified parameters and, if successful, create a `SerialOperator` actor associated to the port. + * The operator actor acts as an intermediate to the underlying native serial port, dealing with threading issues and the such. It will send any events + * to the given `handler` actorref. + * The manager will respond with an `Opened` in case the port was successfully opened, or `OpenFailed` in case of failure. + * @param handler actor that will receive events from the specified serial port (via an operator) * @param port name of serial port * @param baud baud rate to use with serial port * @param characterSize size of a character of the data sent through the serial port @@ -25,7 +29,7 @@ object Serial extends ExtensionKey[SerialExt] { case class Open(handler: ActorRef, port: String, baud: Int, characterSize: Int = 8, twoStopBits: Boolean = false, parity: Parity.Parity = Parity.None) extends Command /** - * Event sent from a port operator, indicating that a serial port was successfully opened. + * Event sent from a port operator, indicating that a serial port was successfully opened. The sender of this message is the operator associated to the given serial port. * @param port name of serial port * @param baud baud rate to use with serial port * @param characterSize size of a character of the data sent through the serial port @@ -35,7 +39,7 @@ object Serial extends ExtensionKey[SerialExt] { case class Opened(port: String, baud: Int, characterSize: Int, twoStopBits: Boolean, parity: Parity.Parity) extends Event /** - * Event sent from manager, indicating that a serial port could not be opened. + * Event sent from the serial manager, indicating that a serial port could not be opened. * @param reason throwable containing reason to why the requested port could not be opened * @param port name of serial port * @param baud baud rate to use with serial port @@ -52,7 +56,7 @@ object Serial extends ExtensionKey[SerialExt] { case class Received(data: ByteString) extends Event /** - * Command sent to operator, requesting the writing of data to the operator's serial port. Optionally request acknowledgment when data is written. + * Write data to serial port. Send this command to an operator to write the given data to its associated serial port. * @param data data to be written to port * @param ack set to true to receive acknowledgment on successful write * @see Wrote @@ -61,16 +65,16 @@ object Serial extends ExtensionKey[SerialExt] { /** * Event sent by operator, acknowledging that data was written to its serial port. Note that such an acknowledgment only guarantees that data has been written - * to the serial port's output buffer (managed by the operating system), the actual reception of the data on the remote device is not guaranteed. + * to the serial port's output buffer (managed by the operating system), the actual sending of the data to the remote device is not guaranteed. * @param data the data that has been written */ case class Wrote(data: ByteString) extends Event - /** Command sent to operator to request the closing of its serial port. */ + /** Request closing of port. Send this command to an operator to close its associated port. */ case object Close extends Command /** - * Event sent from operator, indicating that its port has been closed. An optional reason explains the error that caused the closing of the port. + * Event sent from operator, indicating that its port has been closed. An optional reason explains the error (if any) that caused the closing of the port. * @param reason Some(exception) explaining the exception that caused the closing, None if the port was closed by sending a `Close` message. */ case class Closed(reason: Option[Exception]) extends Event |