JeVois  1.3
JeVois Smart Embedded Machine Vision Toolkit
Share this page:
Serial.H
Go to the documentation of this file.
1 // ///////////////////////////////////////////////////////////////////////////////////////////////////////////////////
2 //
3 // JeVois Smart Embedded Machine Vision Toolkit - Copyright (C) 2016 by Laurent Itti, the University of Southern
4 // California (USC), and iLab at USC. See http://iLab.usc.edu and http://jevois.org for information about this project.
5 //
6 // This file is part of the JeVois Smart Embedded Machine Vision Toolkit. This program is free software; you can
7 // redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software
8 // Foundation, version 2. This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY;
9 // without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public
10 // License for more details. You should have received a copy of the GNU General Public License along with this program;
11 // if not, write to the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
12 //
13 // Contact information: Laurent Itti - 3641 Watt Way, HNB-07A - Los Angeles, CA 90089-2520 - USA.
14 // Tel: +1 213 740 3527 - itti@pollux.usc.edu - http://iLab.usc.edu - http://jevois.org
15 // ///////////////////////////////////////////////////////////////////////////////////////////////////////////////////
16 /*! \file */
17 
18 #pragma once
19 
21 #include <jevois/Types/Enum.H>
22 #include <chrono>
23 #include <termios.h>
24 #include <unistd.h>
25 #include <mutex>
26 
27 namespace jevois
28 {
29  namespace serial
30  {
31  static ParameterCategory const ParamCateg("Serial Port Options");
32 
33  //! Parameter \relates jevois::Serial
34  JEVOIS_DECLARE_PARAMETER(devname, std::string, "Device file name",
35  "", ParamCateg);
36 
37  //! Parameter \relates jevois::Serial
38  JEVOIS_DECLARE_PARAMETER(baudrate, unsigned int, "Baudrate",
39  115200, { 110, 300, 600, 1200, 2400, 4800, 9600, 14400, 19200, 38400, 57600, 115200,
40  230400, 460800, 921600, 1000000, 1152000, 1500000, 2000000,
41  2500000, 3000000, 3500000, 4000000 }, ParamCateg);
42 
43  //! Parameter \relates jevois::Serial
44  JEVOIS_DECLARE_PARAMETER(format, std::string, "Data format",
45  "8N1", boost::regex("^[5-8][NEO][12]$"), ParamCateg);
46 
47  //! Parameter \relates jevois::Serial
48  JEVOIS_DECLARE_PARAMETER(flowsoft, bool, "Use soft (XON/XOFF) flow control",
49  false, ParamCateg);
50 
51  //! Parameter \relates jevois::Serial
52  JEVOIS_DECLARE_PARAMETER(flowhard, bool, "Use hard (RTS/CTS) flow control",
53  false, ParamCateg);
54 
55  //! Enum for Parameter \relates jevois::Serial
56  JEVOIS_DEFINE_ENUM_CLASS(LineStyle, (LF) (CR) (CRLF) (Zero) (Sloppy) );
57 
58  //! Parameter \relates jevois::Serial
59  JEVOIS_DECLARE_PARAMETER(linestyle, LineStyle, "End of line style: LF is for 0x0a [\\n]; CR is for 0x0d [\\r]; "
60  "CRLF is for 0x0d 0x0a [\\r\\n]; Zero is for 0x00 [\\0]; Sloppy accepts any of "
61  "CR, LF, CRLF, 0xd0 (issued by some keyboards instead of Return), and Zero as input "
62  "and issues CRLF in outputs.",
63  LineStyle::Sloppy, LineStyle_Values, ParamCateg);
64 
65  //! Enum for Parameter \relates jevois::Serial
66  JEVOIS_DEFINE_ENUM_CLASS(TerminalMode, (Plain) (VT100) );
67 
68  //! Parameter \relates jevois::Serial
69  JEVOIS_DECLARE_PARAMETER(mode, TerminalMode, "Terminal emulation mode for input",
70  TerminalMode::Plain, TerminalMode_Values, ParamCateg);
71  } // namespace serial
72 
73  //! Interface to a serial port
74  /*! This class is thread-safe. Concurrent read and write (which do not seem to be supported by the O.S. or hardware)
75  are serialized through the use of a mutex in the Serial class. \ingroup core */
76  class Serial : public UserInterface,
77  public Parameter<serial::devname, serial::baudrate, serial::format, serial::flowsoft,
78  serial::flowhard, serial::linestyle, serial::mode>
79  {
80  public:
81  //! Constructor
82  Serial(std::string const & instance, UserInterface::Type type);
83 
84  //! destructor
85  virtual ~Serial();
86 
87  //! Set the access to blocking or not
88  /*! Default is non-blocking. If blocking, can also specify a timeout (rounded to tenth of seconds) */
89  void setBlocking(bool blocking, std::chrono::milliseconds const & timeout);
90 
91  //! Set the DTR mode off momentarily.
92  void toggleDTR(std::chrono::milliseconds const & dur);
93 
94  //! transmit continuous stream of zero-valued bits for specific duration.
95  void sendBreak(void);
96 
97  //! Read some bytes if available, and return true and a string when one is complete
98  /*! This would usually only make sense to use in non-blocking mode. */
99  bool readSome(std::string & str) override;
100 
101  //! Read a string, using the line termination convention of serial::linestyle
102  /*! No line terminator is included in the read string that is returned. This would normally only make sense to use
103  when the port is in blocking mode, as it throws if trying to chars until the end of line marker but none is
104  available. */
105  std::string readString();
106 
107  //! Write a string, using the line termination convention of serial::linestyle
108  /*! No line terminator should be included in the string, writeString() will add one. */
109  void writeString(std::string const & str) override;
110 
111  //! Attempt to read up to nbytes from serial port into the buffer
112  /*! @param buffer holds bytes after read
113  @param nbytes number of bytes to attempt to read
114  @return 0 on a timeout, -1 on error, number of bytes actually read on a success */
115  int read(void * buffer, const int nbytes);
116 
117  //! Attempt to read up to nbytes from serial port into the buffer
118  /*! @param buffer holds bytes after read
119  @param nbytes number of bytes to attempt to read
120  @return 0 on a timeout, 0 on no new characters, -1 on error, number of bytes actually read on a success */
121  int read2(void * buffer, const int nbytes);
122 
123  //! Write bytes to the port
124  /*! @param buffer begin writing from the location buffer.
125  @param nbytes number of bytes to write */
126  void write(void const * buffer, const int nbytes);
127 
128  //! Write bytes to the port - does not wait for buffer to be emptied
129  /*! @param buffer begin writing from the location buffer.
130  @param nbytes number of bytes to write */
131  void writeNoCheck(void const * buffer, const int nbytes);
132 
133  //! Flush all inputs
134  void flush(void);
135 
136  //! Return our port type, here Hard or USB
137  UserInterface::Type type() const override;
138 
139  protected:
140  void postInit() override;
141  void postUninit() override;
142 
143  private:
144  int itsDev; // descriptor associated with the device file
145  termios itsSavedState; // saved state to restore in the destructor
146  std::string itsPartialString;
147  std::mutex itsMtx;
148  int itsWriteOverflowCounter; // counter so we do not send too many write overflow errors
150  };
151 } // namespace jevois
void write(void const *buffer, const int nbytes)
Write bytes to the port.
Definition: Serial.C:356
void writeNoCheck(void const *buffer, const int nbytes)
Write bytes to the port - does not wait for buffer to be emptied.
Definition: Serial.C:390
Generic variadic template class template definition for Component Parameters.
JEVOIS_DECLARE_PARAMETER(thresh1, double,"First threshold for hysteresis", 50.0, ParamCateg)
A category to which multiple ParameterDef definitions can belong.
Definition: ParameterDef.H:33
std::string readString()
Read a string, using the line termination convention of serial::linestyle.
Definition: Serial.C:300
Interface to a serial port.
Definition: Serial.H:76
void postInit() override
Called after all sub-Components are init()ed.
Definition: Serial.C:31
bool readSome(std::string &str) override
Read some bytes if available, and return true and a string when one is complete.
Definition: Serial.C:247
void toggleDTR(std::chrono::milliseconds const &dur)
Set the DTR mode off momentarily.
Definition: Serial.C:188
void flush(void)
Flush all inputs.
Definition: Serial.C:411
Type
Enum for the interface type.
Definition: UserInterface.H:53
int read2(void *buffer, const int nbytes)
Attempt to read up to nbytes from serial port into the buffer.
Definition: Serial.C:229
Abstract base class for a string-based user interface.
Definition: UserInterface.H:32
void writeString(std::string const &str) override
Write a string, using the line termination convention of serial::linestyle.
Definition: Serial.C:339
UserInterface::Type type() const override
Return our port type, here Hard or USB.
Definition: Serial.C:425
void postUninit() override
Called after all sub-Components are uninit()ed.
Definition: Serial.C:155
virtual ~Serial()
destructor
Definition: Serial.C:421
Serial(std::string const &instance, UserInterface::Type type)
Constructor.
Definition: Serial.C:26
void sendBreak(void)
transmit continuous stream of zero-valued bits for specific duration.
Definition: Serial.C:207
void setBlocking(bool blocking, std::chrono::milliseconds const &timeout)
Set the access to blocking or not.
Definition: Serial.C:167
int read(void *buffer, const int nbytes)
Attempt to read up to nbytes from serial port into the buffer.
Definition: Serial.C:216