2016-06-07 21:57:41 +00:00
|
|
|
.. currentmodule:: pyb
|
|
|
|
|
2014-10-31 22:21:37 +00:00
|
|
|
class USB_VCP -- USB virtual comm port
|
|
|
|
======================================
|
2014-10-31 01:37:19 +00:00
|
|
|
|
|
|
|
The USB_VCP class allows creation of an object representing the USB
|
|
|
|
virtual comm port. It can be used to read and write data over USB to
|
|
|
|
the connected host.
|
|
|
|
|
|
|
|
|
|
|
|
Constructors
|
|
|
|
------------
|
|
|
|
|
|
|
|
.. class:: pyb.USB_VCP()
|
|
|
|
|
|
|
|
Create a new USB_VCP object.
|
|
|
|
|
|
|
|
|
|
|
|
Methods
|
|
|
|
-------
|
|
|
|
|
2016-06-08 13:21:28 +00:00
|
|
|
.. method:: USB_VCP.setinterrupt(chr)
|
2014-11-29 15:23:21 +00:00
|
|
|
|
|
|
|
Set the character which interrupts running Python code. This is set
|
|
|
|
to 3 (CTRL-C) by default, and when a CTRL-C character is received over
|
|
|
|
the USB VCP port, a KeyboardInterrupt exception is raised.
|
|
|
|
|
|
|
|
Set to -1 to disable this interrupt feature. This is useful when you
|
|
|
|
want to send raw bytes over the USB VCP port.
|
|
|
|
|
2016-06-08 13:21:28 +00:00
|
|
|
.. method:: USB_VCP.isconnected()
|
2014-11-01 21:26:06 +00:00
|
|
|
|
|
|
|
Return ``True`` if USB is connected as a serial device, else ``False``.
|
|
|
|
|
2016-06-08 13:21:28 +00:00
|
|
|
.. method:: USB_VCP.any()
|
2014-10-31 01:37:19 +00:00
|
|
|
|
|
|
|
Return ``True`` if any characters waiting, else ``False``.
|
|
|
|
|
2016-06-08 13:21:28 +00:00
|
|
|
.. method:: USB_VCP.close()
|
2014-10-31 01:37:19 +00:00
|
|
|
|
2015-05-13 19:42:12 +00:00
|
|
|
This method does nothing. It exists so the USB_VCP object can act as
|
|
|
|
a file.
|
2014-10-31 01:37:19 +00:00
|
|
|
|
2016-06-08 13:21:28 +00:00
|
|
|
.. method:: USB_VCP.read([nbytes])
|
2014-10-31 01:37:19 +00:00
|
|
|
|
2015-05-13 19:42:12 +00:00
|
|
|
Read at most ``nbytes`` from the serial device and return them as a
|
2016-11-14 12:31:40 +00:00
|
|
|
bytes object. If ``nbytes`` is not specified then the method reads
|
|
|
|
all available bytes from the serial device.
|
|
|
|
USB_VCP stream implicitly works in non-blocking mode,
|
2015-10-25 10:24:29 +00:00
|
|
|
so if no pending data available, this method will return immediately
|
|
|
|
with ``None`` value.
|
2014-10-31 01:37:19 +00:00
|
|
|
|
2016-06-08 13:21:28 +00:00
|
|
|
.. method:: USB_VCP.readinto(buf, [maxlen])
|
2015-05-13 19:42:12 +00:00
|
|
|
|
|
|
|
Read bytes from the serial device and store them into ``buf``, which
|
|
|
|
should be a buffer-like object. At most ``len(buf)`` bytes are read.
|
|
|
|
If ``maxlen`` is given and then at most ``min(maxlen, len(buf))`` bytes
|
|
|
|
are read.
|
|
|
|
|
2015-10-25 10:24:29 +00:00
|
|
|
Returns the number of bytes read and stored into ``buf`` or ``None``
|
|
|
|
if no pending data available.
|
2014-10-31 01:37:19 +00:00
|
|
|
|
2016-06-08 13:21:28 +00:00
|
|
|
.. method:: USB_VCP.readline()
|
2014-10-31 01:37:19 +00:00
|
|
|
|
2015-05-13 19:42:12 +00:00
|
|
|
Read a whole line from the serial device.
|
|
|
|
|
|
|
|
Returns a bytes object containing the data, including the trailing
|
2015-10-25 10:24:29 +00:00
|
|
|
newline character or ``None`` if no pending data available.
|
2015-05-13 19:42:12 +00:00
|
|
|
|
2016-06-08 13:21:28 +00:00
|
|
|
.. method:: USB_VCP.readlines()
|
2015-05-13 19:42:12 +00:00
|
|
|
|
|
|
|
Read as much data as possible from the serial device, breaking it into
|
|
|
|
lines.
|
|
|
|
|
|
|
|
Returns a list of bytes objects, each object being one of the lines.
|
|
|
|
Each line will include the newline character.
|
|
|
|
|
2016-06-08 13:21:28 +00:00
|
|
|
.. method:: USB_VCP.write(buf)
|
2015-05-13 19:42:12 +00:00
|
|
|
|
|
|
|
Write the bytes from ``buf`` to the serial device.
|
|
|
|
|
|
|
|
Returns the number of bytes written.
|
2014-10-31 01:37:19 +00:00
|
|
|
|
2016-06-08 13:21:28 +00:00
|
|
|
.. method:: USB_VCP.recv(data, \*, timeout=5000)
|
2014-10-31 01:37:19 +00:00
|
|
|
|
|
|
|
Receive data on the bus:
|
|
|
|
|
|
|
|
- ``data`` can be an integer, which is the number of bytes to receive,
|
|
|
|
or a mutable buffer, which will be filled with received bytes.
|
|
|
|
- ``timeout`` is the timeout in milliseconds to wait for the receive.
|
|
|
|
|
|
|
|
Return value: if ``data`` is an integer then a new buffer of the bytes received,
|
|
|
|
otherwise the number of bytes read into ``data`` is returned.
|
|
|
|
|
2016-06-08 13:21:28 +00:00
|
|
|
.. method:: USB_VCP.send(data, \*, timeout=5000)
|
2014-10-31 01:37:19 +00:00
|
|
|
|
|
|
|
Send data over the USB VCP:
|
|
|
|
|
|
|
|
- ``data`` is the data to send (an integer to send, or a buffer object).
|
|
|
|
- ``timeout`` is the timeout in milliseconds to wait for the send.
|
|
|
|
|
|
|
|
Return value: number of bytes sent.
|