From: Matthias Heidbrink <redacted>
Date: Fri, 3 Jan 2014 13:37:39 +0000 (+0100)
Subject: serial: Improved docs.
X-Git-Tag: libsigrok-0.3.0~336
X-Git-Url: http://sigrok.org/gitweb/?p=libsigrok.git;a=commitdiff_plain;h=48d3238e66bac0958fbec316db837aa3a8a1075a

serial: Improved docs.
---

diff --git a/README.devices b/README.devices
index da1e291d..6dd42dde 100644
--- a/README.devices
+++ b/README.devices
@@ -51,6 +51,7 @@ The following drivers/devices do not need any firmware upload:
 
  - agilent-dmm
  - alsa
+ - bbcgm-m2110
  - brymen-dmm
  - cem-dt-885x
  - center-3xx
@@ -58,6 +59,7 @@ The following drivers/devices do not need any firmware upload:
  - colead-slm
  - demo
  - fluke-dmm
+ - gmc-mh-1x-2x-rs232
  - ikalogic-scanalogic2
  - ikalogic-scanaplus
  - kecheng-kc-330b
@@ -93,11 +95,13 @@ Example:
 The following drivers/devices require a serial port specification:
 
  - agilent-dmm
+ - bbcgm-m2110
  - brymen-dmm
  - cem-dt-885x
  - center-3xx
  - colead-slm
  - fluke-dmm
+ - gmc-mh-1x-2x-rs232
  - link-mso19
  - mic-985xx
  - norma-dmm
@@ -126,6 +130,20 @@ The following drivers/devices do not require a serial port specification:
  - zeroplus-logic-cube
 
 
+Specifiying serial port parameters
+----------------------------------
+
+Every serial device's driver has default serial port parameters like baud
+rate, number of data bits, stop bits and handshake status. If a device requires
+different parameters, pass them as option "serialcomm" with the driver name.
+See libsigrok, docs for function serial_set_paramstr() for complete specs.
+
+Example:
+
+ $ sigrok-cli --driver <somedriver>:conn=<someconn>:serialcomm=9600/7n1/dtr=1
+
+
+
 Permissions of serial port based devices
 ----------------------------------------
 
@@ -264,7 +282,12 @@ unless a certain action has been performed by the user beforehand. This is
 usually mentioned in the vendor manual of the respective device, but here's
 a short list for convenience:
 
+ - bbcgm-m2110: Press button "Start/Reset" on interface panel on top.
  - Digitek DT4000ZC: Briefly press the "RS232" button.
+ - gmc-mh-1x-2x-rs232: Switch on device with buttons "DATA" pressed.
+   Additionally Metrahit 2x devices must be configured for interface "RS232".
+ - norma-dmm: If the interface does not work (e.g. USB-RS232 converter), switch
+   on device with "FUNC" button pressed to power interface from multimeter.
  - PCE PCE-DM32: Briefly press the "RS232" button.
  - RadioShack 22-812: Press and hold "SELECT" and "RANGE" together.
  - TekPower TP4000ZC: Briefly press the "RS232" button.
diff --git a/hardware/common/serial.c b/hardware/common/serial.c
index d08f22bd..a267d6fb 100644
--- a/hardware/common/serial.c
+++ b/hardware/common/serial.c
@@ -374,21 +374,30 @@ SR_PRIV int serial_set_params(struct sr_serial_dev_inst *serial, int baudrate,
 }
 
 /**
- * Set serial parameters for the specified serial port.
+ * Set serial parameters for the specified serial port from parameter string.
  *
  * @param serial Previously initialized serial port structure.
- * @param[in] paramstr A serial communication parameters string, in the form
- * of \<speed\>/\<data bits\>\<parity\>\<stopbits\>\<flow\>, for example
- * "9600/8n1" or "600/7o2" or "460800/8n1/flow=2" where flow is 0 for none,
- * 1 for rts/cts and 2 for xon/xoff.
- *
+ * @param[in] paramstr A serial communication parameters string of the form
+ * "<baudrate>/<bits><parity><stopbits>{/<option>}".\n
+ *  Examples: "9600/8n1", "600/7o2/dtr=1/rts=0" or "460800/8n1/flow=2".\n
+ * \<baudrate\>=integer Baud rate.\n
+ * \<bits\>=5|6|7|8 Number of data bits.\n
+ * \<parity\>=n|e|o None, even, odd.\n
+ * \<stopbits\>=1|2 One or two stop bits.\n
+ * Options:\n
+ * dtr=0|1 Set DTR off resp. on.\n
+ * flow=0|1|2 Flow control. 0 for none, 1 for RTS/CTS, 2 for XON/XOFF.\n
+ * rts=0|1 Set RTS off resp. on.\n
+ * Please note that values and combinations of these parameters must be
+ * supported by the concrete serial interface hardware and the drivers for it.
  * @retval SR_OK Success.
  * @retval SR_ERR Failure.
  */
-#define SERIAL_COMM_SPEC "^(\\d+)/([5678])([neo])([12])(.*)$"
 SR_PRIV int serial_set_paramstr(struct sr_serial_dev_inst *serial,
 		const char *paramstr)
 {
+#define SERIAL_COMM_SPEC "^(\\d+)/([5678])([neo])([12])(.*)$"
+
 	GRegex *reg;
 	GMatchInfo *match;
 	int speed, databits, parity, stopbits, flow, rts, dtr, i;