pyb.USB_VCP.rst 3.06 KB
Newer Older
1
2
.. currentmodule:: pyb

3
4
class USB_VCP -- USB virtual comm port
======================================
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21

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
-------

22
.. method:: USB_VCP.setinterrupt(chr)
23
24
25
26
27
28
29
30

   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.

31
.. method:: USB_VCP.isconnected()
32
33
34

   Return ``True`` if USB is connected as a serial device, else ``False``.

35
.. method:: USB_VCP.any()
36
37
38

   Return ``True`` if any characters waiting, else ``False``.

39
.. method:: USB_VCP.close()
40

41
42
   This method does nothing.  It exists so the USB_VCP object can act as
   a file.
43

44
.. method:: USB_VCP.read([nbytes])
45

46
   Read at most ``nbytes`` from the serial device and return them as a
47
48
49
   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,
50
51
   so if no pending data available, this method will return immediately
   with ``None`` value.
52

53
.. method:: USB_VCP.readinto(buf, [maxlen])
54
55
56
57
58
59

   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.

60
61
   Returns the number of bytes read and stored into ``buf`` or ``None``
   if no pending data available.
62

63
.. method:: USB_VCP.readline()
64

65
66
67
   Read a whole line from the serial device.

   Returns a bytes object containing the data, including the trailing
68
   newline character or ``None`` if no pending data available.
69

70
.. method:: USB_VCP.readlines()
71
72
73
74
75
76
77

   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.

78
.. method:: USB_VCP.write(buf)
79
80
81
82

   Write the bytes from ``buf`` to the serial device.

   Returns the number of bytes written.
83

84
.. method:: USB_VCP.recv(data, \*, timeout=5000)
85
86
87
88
89
90
91
92
93
94

   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.

95
.. method:: USB_VCP.send(data, \*, timeout=5000)
96
97
98
99
100
101
102

   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.