Merge #558

558: docs: add documentation for the default baud_rate and how to change it r=MatthieuDartiailh a=hkennyv

added blurb to communication.rst and updated docstring for
resources.serial.SerialInstrument

<!--

Thanks for wanting to contribute to PyVISA :)

Here's some guidelines to help the review process go smoothly.

1. Please write a description in this text box of the changes that are being
   made.

2. Please ensure that the code is properly formatted and typed by running
   black, isort, flake8 and mypy. You can also use pre-commit hooks (see the
   developer documentation for detailed instructions)

3. Please ensure that you have written units tests for the changes made/features
   added.

4. If you are closing an issue please use one of the automatic closing words as
   noted here: https://help.github.com/articles/closing-issues-using-keywords/

5. Once review has taken place please do not add features or make changes out of
   the scope of those requested by the reviewer (doing this just add delays as
   already reviewed code ends up having to be re-reviewed/it is hard to tell
   what is new etc!).

Many thanks in advance for your cooperation!

-->

- [x] Closes #556
- [x] Executed ``black . && isort -c . && flake8`` with no errors (i executed this, and there are some errors in files unrelated to this PR)

output:
```
(venv) khuynh@kmac:github/pyvisa ‹docs/default-baud-rate›$ black . && isort -c . && flake8
All done! ✨ 🍰 ✨
55 files left unchanged.
ERROR: /Users/khuynh/me/develop/github/pyvisa/visa.py Imports are incorrectly sorted and/or formatted.
ERROR: /Users/khuynh/me/develop/github/pyvisa/examples/itc4.py Imports are incorrectly sorted and/or formatted.
ERROR: /Users/khuynh/me/develop/github/pyvisa/examples/keithley2000.py Imports are incorrectly sorted and/or formatted.
Skipped 2 files
(venv) khuynh@kmac:github/pyvisa ‹docs/default-baud-rate›$ flake8
./examples/keithley2000.py:40:64: F821 undefined name 'VI_INTF_GPIB'
```

- [x] The change is fully covered by automated unit tests
- [x] Documented in docs/ as appropriate
- [x] Added an entry to the CHANGES file


Co-authored-by: Kenny Huynh <hkennyv@gmail.com>

CHANGES

@@ -20,6 +20,7 @@ PyVISA Changelog
 - allow a None value for the board value of a ResourceInfo PR #547
   This allows for funky resource name such ASRL/dev/tty0::INSTR which are common
   in pyvisa-py and avoid returning a completely generic resource in those cases.
+- documentation improvements for pyvisa.resources.SerialInstrument PR #558
 
 1.11 (16-09-2020)
 -----------------

docs/source/introduction/communication.rst

@@ -116,6 +116,19 @@ start communicating as follows::
 Here we use `'\n'` known as 'line feed'. This is a common value, another one is
 `'\r'` i.e. 'carriage return', and in some cases the null byte '\0' is used.
 
+.. note::
+
+    For instruments that communicate over serial, you need to ensure you configure
+    the correct baud rate. The default baud rate is set to 9600, but you should
+    check your instrument's manual to verify the correct value for your use case.
+    If you wish to configure other serial instrument parameters, see
+    :ref:`api_resources` for a full list of attributes.
+
+You can configure PyVISA to communicate to your instrument using a different
+baud rate as follows:
+
+    >>> my_instrument.baud_rate = 57600
+
 In an ideal world, this will work and you will be able to get an answer from
 your instrument. If it does not, it means the settings are likely wrong (the
 documentation does not always shine by its clarity). In the following we will
@@ -189,7 +202,7 @@ up a couple of paragraph).
 
 .. note::
 
-    It is possible to disable the use of teh termination character to detect
+    It is possible to disable the use of the termination character to detect
     the end of an input message by setting |read_termination| to ``""``. Care
     has to be taken for the case of serial instrument for which the method used
     to determine the end of input is controlled by the |end_input| attribute

pyvisa/attributes.py

@@ -1623,7 +1623,7 @@ class AttrVI_ATTR_ASRL_FLOW_CNTRL(EnumAttribute):
 
     visa_type = "ViUInt16"
 
-    default = constants.VI_ASRL_FLOW_NONE
+    default = constants.ControlFlow.none
 
     read, write, local = True, True, False
 

pyvisa/resources/serial.py

@@ -21,55 +21,65 @@ class SerialInstrument(MessageBasedResource):
 
     """
 
-    #: Baud rate of the interface.
+    #: Baud rate of the interface. The default value is 9600.
     baud_rate: Attribute[int] = attributes.AttrVI_ATTR_ASRL_BAUD()
 
-    #: Number of data bits contained in each frame (from 5 to 8).
+    #: Number of data bits contained in each frame (from 5 to 8). The default value is 8.
     data_bits: Attribute[int] = attributes.AttrVI_ATTR_ASRL_DATA_BITS()
 
-    #: Parity used with every frame transmitted and received.
+    #: Parity used with every frame transmitted and received. The default value is
+    #: `constants.Parity.none` (VI_ASRL_PAR_NONE).
     parity: Attribute[constants.Parity] = attributes.AttrVI_ATTR_ASRL_PARITY()
 
-    #: Number of stop bits used to indicate the end of a frame.
+    #: Number of stop bits used to indicate the end of a frame. The default value is
+    #: `constants.StopBits.one` (VI_ASRL_STOP_ONE).
     stop_bits: Attribute[constants.StopBits] = attributes.AttrVI_ATTR_ASRL_STOP_BITS()
 
-    #: Indicates the type of flow control used by the transfer mechanism.
+    #: Indicates the type of flow control used by the transfer mechanism. The default value
+    #: is `constants.ControlFlow.none` (VI_ASRL_FLOW_NONE).
     flow_control: Attribute[
         constants.ControlFlow
     ] = attributes.AttrVI_ATTR_ASRL_FLOW_CNTRL()
 
     #: Number of bytes available in the low- level I/O receive buffer.
     bytes_in_buffer: Attribute[int] = attributes.AttrVI_ATTR_ASRL_AVAIL_NUM()
 
-    #: If set to True, NUL characters are discarded.
+    #: If set to True, NUL characters are discarded. The default is False.
     discard_null: Attribute[bool] = attributes.AttrVI_ATTR_ASRL_DISCARD_NULL()
 
-    #: Manually control transmission.
+    #: Manually control transmission. The default value is True.
     allow_transmit: Attribute[bool] = attributes.AttrVI_ATTR_ASRL_ALLOW_TRANSMIT()
 
-    #: Method used to terminate read operations.
+    #: Method used to terminate read operations. The default value is
+    #: `constants.SerialTermination.termination_char` (VI_ASRL_END_TERMCHAR).
     end_input: Attribute[
         constants.SerialTermination
     ] = attributes.AttrVI_ATTR_ASRL_END_IN()
 
-    #: Method used to terminate write operations.
+    #: Method used to terminate write operations. The default value is
+    #: `constants.SerialTermination.none` (VI_ASRL_END_NONE) and terminates
+    #: when all requested data is transferred or when an error occurs.
     end_output: Attribute[
         constants.SerialTermination
     ] = attributes.AttrVI_ATTR_ASRL_END_OUT()
 
-    #: Duration (in milliseconds) of the break signal.
+    #: Duration (in milliseconds) of the break signal. The default value is 250.
     break_length: Attribute[int] = attributes.AttrVI_ATTR_ASRL_BREAK_LEN()
 
-    #: Manually control the assertion state of the break signal.
+    #: Manually control the assertion state of the break signal. The default state is
+    #: `constants.LineState.unasserted` (VI_STATE_UNASSERTED).
     break_state: Attribute[
         constants.LineState
     ] = attributes.AttrVI_ATTR_ASRL_BREAK_STATE()
 
     #: Character to be used to replace incoming characters that arrive with errors.
+    #: The default character is '\0'.
     replace_char: Attribute[str] = attributes.AttrVI_ATTR_ASRL_REPLACE_CHAR()
 
     #: XOFF character used for XON/XOFF flow control (both directions).
+    #: The default character is '0x13'.
     xoff_char: Attribute[str] = attributes.AttrVI_ATTR_ASRL_XOFF_CHAR()
 
     #: XON character used for XON/XOFF flow control (both directions).
+    #: The default character is '0x11'.
     xon_char: Attribute[str] = attributes.AttrVI_ATTR_ASRL_XON_CHAR()