JeVois  1.18
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 
20 #include <jevois/Core/UserInterface.H>
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  //! Parameter \relates jevois::Serial
56  JEVOIS_DECLARE_PARAMETER(drop, bool, "Silently drop write data when write buffer is full. Useful to "
57  "avoid blocking when writing messages to serial-over-USB port and the host is "
58  "not listening to it. Note that even when drop is false, we will still drop "
59  "data after repeated attempts to send it, and will report an error (as opposed to "
60  "silently dropping when drop is true).",
61  true, ParamCateg);
62 
63  //! Enum for Parameter \relates jevois::Serial
64  JEVOIS_DEFINE_ENUM_CLASS(LineStyle, (LF) (CR) (CRLF) (Zero) (Sloppy) );
65 
66  //! Parameter \relates jevois::Serial
67  JEVOIS_DECLARE_PARAMETER(linestyle, LineStyle, "End of line style: LF is for 0x0a [\\n]; CR is for 0x0d [\\r]; "
68  "CRLF is for 0x0d 0x0a [\\r\\n]; Zero is for 0x00 [\\0]; Sloppy accepts any of "
69  "CR, LF, CRLF, 0xd0 (issued by some keyboards instead of Return), and Zero as input "
70  "and issues CRLF in outputs.",
71  LineStyle::Sloppy, LineStyle_Values, ParamCateg);
72 
73  //! Enum for Parameter \relates jevois::Serial
74  JEVOIS_DEFINE_ENUM_CLASS(TerminalMode, (Plain) (VT100) );
75 
76  //! Parameter \relates jevois::Serial
77  JEVOIS_DECLARE_PARAMETER(mode, TerminalMode, "Terminal emulation mode for input",
78  TerminalMode::Plain, TerminalMode_Values, ParamCateg);
79  } // namespace serial
80 
81  //! Interface to a serial port
82  /*! This class is thread-safe. Concurrent read and write (which do not seem to be supported by the O.S. or hardware)
83  are serialized through the use of a mutex in the Serial class. \ingroup core */
84  class Serial : public UserInterface,
85  public Parameter<serial::devname, serial::baudrate, serial::format, serial::flowsoft,
86  serial::flowhard, serial::drop, serial::linestyle, serial::mode>
87  {
88  public:
89  //! Constructor
90  Serial(std::string const & instance, UserInterface::Type type);
91 
92  //! destructor
93  virtual ~Serial();
94 
95  //! Set the access to blocking or not
96  /*! Default is non-blocking. If blocking, can also specify a timeout (rounded to tenth of seconds) */
97  void setBlocking(bool blocking, std::chrono::milliseconds const & timeout);
98 
99  //! Set the DTR mode off momentarily.
100  void toggleDTR(std::chrono::milliseconds const & dur);
101 
102  //! transmit continuous stream of zero-valued bits for specific duration.
103  void sendBreak(void);
104 
105  //! Read some bytes if available, and return true and a string when one is complete
106  /*! This would usually only make sense to use in non-blocking mode. */
107  bool readSome(std::string & str) override;
108 
109  //! Read a string, using the line termination convention of serial::linestyle
110  /*! No line terminator is included in the read string that is returned. This would normally only make sense to use
111  when the port is in blocking mode, as it throws if trying to chars until the end of line marker but none is
112  available. */
113  std::string readString();
114 
115  //! Write a string, using the line termination convention of serial::linestyle
116  /*! No line terminator should be included in the string, writeString() will add one. */
117  void writeString(std::string const & str) override;
118 
119  //! Attempt to read up to nbytes from serial port into the buffer
120  /*! @param buffer holds bytes after read
121  @param nbytes number of bytes to attempt to read
122  @return 0 on a timeout, -1 on error, number of bytes actually read on a success */
123  int read(void * buffer, const int nbytes);
124 
125  //! Attempt to read up to nbytes from serial port into the buffer
126  /*! @param buffer holds bytes after read
127  @param nbytes number of bytes to attempt to read
128  @return 0 on a timeout, 0 on no new characters, -1 on error, number of bytes actually read on a success */
129  int read2(void * buffer, const int nbytes);
130 
131  //! Write bytes to the port
132  /*! @param buffer begin writing from the location buffer.
133  @param nbytes number of bytes to write */
134  void write(void const * buffer, const int nbytes);
135 
136  //! Write bytes to the port - does not wait for buffer to be emptied
137  /*! @param buffer begin writing from the location buffer.
138  @param nbytes number of bytes to write */
139  void writeNoCheck(void const * buffer, const int nbytes);
140 
141  //! Send a file from the local microSD to the host computer
142  /*! abspath should be the full absolute path of the file. The port will be locked during the entire
143  transaction. */
144  void fileGet(std::string const & abspath);
145 
146  //! Receive a file from the host and write it to the local microSD
147  /*! abspath should be the full absolute path of the file. The port will be locked during the entire
148  transaction. */
149  void filePut(std::string const & abspath);
150 
151  //! Flush all inputs
152  void flush(void);
153 
154  //! Return our port type, here Hard or USB
155  UserInterface::Type type() const override;
156 
157  protected:
158  void postInit() override;
159  void postUninit() override;
160 
161  private:
162  void writeInternal(void const * buffer, const int nbytes, bool nodrop = false); // Like write() but already locked
163  std::string readStringInternal(); // Like readString(0 but already locked
164  int itsDev; // descriptor associated with the device file
165  termios itsSavedState; // saved state to restore in the destructor
166  std::string itsPartialString;
167  std::mutex itsMtx;
168  int itsWriteOverflowCounter; // counter so we do not send too many write overflow errors
169  jevois::UserInterface::Type itsType;
170  };
171 } // namespace jevois
jevois::Serial::setBlocking
void setBlocking(bool blocking, std::chrono::milliseconds const &timeout)
Set the access to blocking or not.
Definition: Serial.C:169
jevois::Serial
Interface to a serial port.
Definition: Serial.H:84
jevois::Serial::sendBreak
void sendBreak(void)
transmit continuous stream of zero-valued bits for specific duration.
Definition: Serial.C:209
jevois::imu::mode
Magnetometer sampling or Off to disable or Once to only get one measurement You can repeatedly set this parameter to Once to obtain repeated measurements at your own pace In JeVois you need to alternate between Off and Once In FIFO mode
Definition: ICM20948.H:115
JEVOIS_DECLARE_PARAMETER
JEVOIS_DECLARE_PARAMETER(thresh1, double, "First threshold for hysteresis", 50.0, ParamCateg)
jevois::Serial::Serial
Serial(std::string const &instance, UserInterface::Type type)
Constructor.
Definition: Serial.C:28
jevois::Serial::readSome
bool readSome(std::string &str) override
Read some bytes if available, and return true and a string when one is complete.
Definition: Serial.C:249
jevois::UserInterface
Abstract base class for a string-based user interface.
Definition: UserInterface.H:32
jevois::Serial::postInit
void postInit() override
Called after all sub-Components are init()ed.
Definition: Serial.C:33
jevois::Serial::readString
std::string readString()
Read a string, using the line termination convention of serial::linestyle.
Definition: Serial.C:302
UserInterface.H
jevois::ParameterCategory
A category to which multiple ParameterDef definitions can belong.
Definition: ParameterDef.H:33
jevois::Serial::filePut
void filePut(std::string const &abspath)
Receive a file from the host and write it to the local microSD.
Definition: Serial.C:497
jevois::Serial::toggleDTR
void toggleDTR(std::chrono::milliseconds const &dur)
Set the DTR mode off momentarily.
Definition: Serial.C:190
jevois
Definition: Concepts.dox:1
jevois::JEVOIS_DEFINE_ENUM_CLASS
JEVOIS_DEFINE_ENUM_CLASS(CameraSensor,(any)(ov9650)(ov2640)(ov7725)(ar0135)(imx290)(os08a10))
Enum for different sensor models.
jevois::Serial::read2
int read2(void *buffer, const int nbytes)
Attempt to read up to nbytes from serial port into the buffer.
Definition: Serial.C:231
jevois::Serial::writeString
void writeString(std::string const &str) override
Write a string, using the line termination convention of serial::linestyle.
Definition: Serial.C:346
jevois::Serial::flush
void flush(void)
Flush all inputs.
Definition: Serial.C:455
jevois::Serial::~Serial
virtual ~Serial()
destructor
Definition: Serial.C:465
jevois::UserInterface::Type
Type
Enum for the interface type.
Definition: UserInterface.H:59
jevois::Serial::write
void write(void const *buffer, const int nbytes)
Write bytes to the port.
Definition: Serial.C:363
jevois::Serial::postUninit
void postUninit() override
Called after all sub-Components are uninit()ed.
Definition: Serial.C:157
jevois::Serial::type
UserInterface::Type type() const override
Return our port type, here Hard or USB.
Definition: Serial.C:469
jevois::Serial::fileGet
void fileGet(std::string const &abspath)
Send a file from the local microSD to the host computer.
Definition: Serial.C:473
jevois::Serial::writeNoCheck
void writeNoCheck(void const *buffer, const int nbytes)
Write bytes to the port - does not wait for buffer to be emptied.
Definition: Serial.C:435
Enum.H
jevois::Serial::read
int read(void *buffer, const int nbytes)
Attempt to read up to nbytes from serial port into the buffer.
Definition: Serial.C:218