]>
Commit | Line | Data |
---|---|---|
f92f1f0c | 1 | ------------------------------------------------------------------------------- |
0a16d4de | 2 | libserialport: cross-platform library for accessing serial ports |
f92f1f0c | 3 | ------------------------------------------------------------------------------- |
0a16d4de ML |
4 | |
5 | libserialport is a minimal library written in C that is intended to take care | |
6 | of the OS-specific details when writing software that uses serial ports. | |
7 | ||
8 | By writing your serial code to use libserialport, you enable it to work | |
9 | transparently on any platform supported by the library. | |
10 | ||
11 | The operations that are supported are: | |
12 | ||
13 | - Port enumeration (obtaining a list of serial ports on the system). | |
14 | - Opening and closing ports. | |
15 | - Setting port parameters (baud rate, parity, etc). | |
16 | - Reading, writing and flushing data. | |
17 | - Obtaining error information. | |
18 | ||
19 | libserialport is an open source project released under the LGPL3+ license. | |
20 | ||
21 | Status | |
22 | ====== | |
23 | ||
24 | The library should build and work on any Windows or Unix-based system. If it | |
25 | does not, please submit a bug. | |
26 | ||
27 | Enumeration is currently only implemented on Windows, Mac OS X and Linux. On | |
28 | other systems enumeration will return no results, but ports can still be opened | |
29 | by name and then used. | |
30 | ||
31 | If you know how to enumerate available ports on another OS, please submit a bug | |
32 | with this information, or better still a patch implementing it. | |
33 | ||
34 | Future | |
35 | ====== | |
36 | ||
37 | Future versions will add additional API calls for obtaining metadata about a | |
38 | port, e.g. for USB devices the USB VID and PID of the underlying device. | |
39 | ||
40 | Dependencies | |
41 | ============ | |
42 | ||
43 | On Linux, libudev is required. On other systems no other libraries are required. | |
44 | ||
45 | The libudev dependency could be eliminated in favour of direct sysfs queries at | |
46 | the cost of some brevity. This is not currently a priority but if you feel like | |
47 | doing this feel free to submit a patch. | |
48 | ||
49 | Building | |
50 | ======== | |
51 | ||
52 | The package uses a GNU style build system and requires a Unix style shell. | |
53 | On Windows it can be built with the MinGW toolchain and MSYS environment. | |
54 | ||
55 | Run "./autogen.sh" to generate the build system, "./configure" to setup, then | |
56 | "make" to build the library and "make install" to install it. | |
57 | ||
58 | API | |
59 | === | |
60 | ||
61 | The API is simple, and designed to be a minimal wrapper around the serial port | |
62 | support in each OS. | |
63 | ||
c45eb4be ML |
64 | Most functions take a pointer to a struct sp_port, which represents a serial |
65 | port. These structures are always allocated and freed by the library, using the | |
66 | functions in the 'Enumeration' section below. | |
0a16d4de | 67 | |
e9a2f9c9 | 68 | All functions can return only three possible error values. SP_ERR_ARG indicates |
0a16d4de | 69 | the function was called with invalid arguments. SP_ERR_FAIL indicates that the |
e9a2f9c9 | 70 | OS reported a failure. SP_ERR_MEM indicates that a memory allocation failed. |
01619328 | 71 | All of these error values are negative. |
0a16d4de ML |
72 | |
73 | When SP_ERR_FAIL is returned, an error code or string description of the error | |
74 | can be obtained by calling sp_last_error_code() or sp_last_error_message(). The | |
75 | error code or message is that provided by the OS; libserialport does not define | |
76 | any error codes or messages of its own. | |
77 | ||
f92f1f0c | 78 | Function calls that succeed return SP_OK, which is equal to zero, or where |
0a16d4de ML |
79 | otherwise documented a positive value. |
80 | ||
81 | The available functions are as follows: | |
82 | ||
83 | Enumeration | |
84 | ----------- | |
85 | ||
01619328 | 86 | int sp_get_port_by_name(const char *portname, struct sp_port **port_ptr); |
0a16d4de | 87 | |
01619328 ML |
88 | Obtains a pointer to a new sp_port structure representing the named port. The |
89 | user should allocate a variable of type "struct sp_port *" and pass a pointer | |
90 | to this to receive the result. | |
b9a462bb ML |
91 | |
92 | The result should be freed after use by calling sp_free_port(). | |
01619328 | 93 | |
b9a462bb ML |
94 | Returns: SP_OK on success, SP_ERR_FAIL on failure, SP_ERR_MEM on allocation |
95 | failure, or SP_ERR_ARG if an invalid pointer is passed. If any error | |
96 | is returned, the variable pointed to by port_ptr will be set to NULL. | |
97 | Otherwise, it will be set to point to the newly allocated port. | |
01619328 ML |
98 | |
99 | void sp_free_port(struct sp_port *port); | |
100 | ||
101 | Frees a port structure obtained from sp_get_port_by_name(). | |
102 | ||
103 | int sp_list_ports(struct sp_port ***list_ptr); | |
104 | ||
105 | Lists the serial ports available on the system. The result obtained is an | |
106 | array of pointers to sp_port structures, terminated by a NULL. The user should | |
107 | allocate a variable of type "struct sp_port **" and pass a pointer to this to | |
108 | receive the result. | |
109 | ||
32b5ac05 ML |
110 | The result should be freed after use by calling sp_free_port_list(). If a port |
111 | from the list is to be used after freeing the list, it must be copied first | |
112 | using sp_copy_port(). | |
01619328 | 113 | |
b9a462bb ML |
114 | Returns: SP_OK on success, SP_ERR_FAIL on failure, SP_ERR_MEM on allocation |
115 | failure, or SP_ERR_ARG if an invalid pointer is passed. If any error | |
116 | is returned, the variable pointed to by list_ptr will be set to NULL. | |
117 | Otherwise, it will be set to point to the newly allocated array. | |
0a16d4de | 118 | |
32b5ac05 ML |
119 | int sp_copy_port(const struct sp_port *port, struct sp_port **copy_ptr); |
120 | ||
121 | Makes a new copy of a sp_port structure. The user should allocate a variable | |
122 | of type "struct sp_port *" and pass a pointer to this to receive the result. | |
123 | ||
124 | The copy should be freed after use by calling sp_free_port(). | |
125 | ||
126 | Returns: SP_OK on success, SP_ERR_MEM on allocation failure, or SP_ERR_ARG | |
127 | if an invalid port or pointer is passed. If any error is returned, | |
128 | the variable pointed to by copy_ptr will be set to NULL. Otherwise, | |
129 | it will be set to point to the newly allocated copy. | |
130 | ||
d54e9004 | 131 | void sp_free_port_list(struct sp_port **list); |
0a16d4de | 132 | |
32b5ac05 ML |
133 | Frees a port list obtained from sp_list_ports(). This will also free all |
134 | the sp_port structures referred to from the list; any that are to be retained | |
135 | must be copied first using sp_copy_port(). | |
0a16d4de ML |
136 | |
137 | Opening and closing ports | |
138 | ------------------------- | |
139 | ||
d54e9004 | 140 | int sp_open(struct sp_port *port, int flags); |
0a16d4de ML |
141 | |
142 | Opens the specified serial port. | |
143 | ||
144 | Parameters: | |
145 | ||
d54e9004 | 146 | port: Pointer to port structure. |
0a16d4de ML |
147 | flags: Flags to use when opening the serial port. Possible |
148 | flags are: SP_MODE_RDWR, SP_MODE_RDONLY, and SP_MODE_NONBLOCK. | |
149 | ||
99945a1f ML |
150 | Returns: SP_OK on success, SP_ERR_FAIL on failure, SP_ERR_MEM on allocation |
151 | failure, or SP_ERR_ARG if an invalid port is passed. | |
0a16d4de ML |
152 | |
153 | int sp_close(struct sp_port *port); | |
154 | ||
155 | Closes the specified serial port. | |
156 | ||
157 | Returns: SP_OK on success, SP_ERR_FAIL on failure, or SP_ERR_ARG | |
158 | if an invalid port is passed. | |
159 | ||
160 | Setting port parameters | |
161 | ----------------------- | |
162 | ||
7e6fb015 | 163 | int sp_set_baudrate(struct sp_port *port, int baudrate) |
0a16d4de | 164 | |
7e6fb015 ML |
165 | Sets the baud rate for the specified serial port. |
166 | ||
167 | Parameters: | |
168 | ||
169 | port: Pointer to port structure. | |
170 | baud: Baud rate in bits per second. | |
171 | ||
172 | Returns: SP_OK on success, SP_ERR_FAIL on failure, or SP_ERR_ARG | |
173 | for invalid arguments. | |
174 | ||
175 | int sp_set_bits(struct sp_port *port, int bits) | |
176 | ||
177 | Sets the number of data bits for the specified serial port. | |
178 | ||
179 | Parameters: | |
180 | ||
181 | port: Pointer to port structure. | |
182 | bits: Number of data bits to use. Valid values are 5 to 8. | |
183 | ||
184 | Returns: SP_OK on success, SP_ERR_FAIL on failure, or SP_ERR_ARG | |
185 | for invalid arguments. | |
186 | ||
187 | int sp_set_parity(struct sp_port *port, int parity) | |
188 | ||
189 | Sets the parity for the specified serial port. | |
190 | ||
191 | Parameters: | |
192 | ||
193 | port: Pointer to port structure. | |
194 | parity: Parity setting to use. | |
195 | (SP_PARITY_NONE, SP_PARITY_EVEN or SP_PARITY_ODD) | |
196 | ||
197 | Returns: SP_OK on success, SP_ERR_FAIL on failure, or SP_ERR_ARG | |
198 | for invalid arguments. | |
199 | ||
200 | int sp_set_stopbits(struct sp_port *port, int stopbits) | |
201 | ||
202 | Sets the number of stop bits for the specified port. | |
203 | ||
204 | Parameters: | |
205 | ||
206 | port: Pointer to port structure. | |
207 | stopbits: Number of stop bits to use (1 or 2). | |
208 | ||
209 | Returns: SP_OK on success, SP_ERR_FAIL on failure, or SP_ERR_ARG | |
210 | for invalid arguments. | |
211 | ||
212 | int sp_set_flowcontrol(struct sp_port *port, int flowcontrol) | |
213 | ||
214 | Sets the flow control type for the specified serial port. | |
215 | ||
216 | This function is a wrapper that sets the RTS, CTS, DTR, DSR and | |
217 | XON/XOFF settings as necessary for the specified flow control | |
218 | type. For more fine-grained control of these settings, use their | |
219 | individual configuration functions or the sp_set_config() function. | |
0a16d4de ML |
220 | |
221 | Parameters: | |
222 | ||
223 | port: Pointer to port structure. | |
7e6fb015 ML |
224 | flowcontrol: Flow control setting to use. Valid settings are: |
225 | ||
226 | SP_FLOWCONTROL_NONE: No flow control. | |
227 | SP_FLOWCONTROL_XONXOFF: Software flow control using XON/XOFF characters. | |
228 | SP_FLOWCONTROL_RTSCTS: Hardware flow control using RTS/CTS signals. | |
229 | SP_FLOWCONTROL_DTRDSR: Hardware flow control using DTR/DSR signals. | |
230 | ||
231 | Returns: SP_OK on success, SP_ERR_FAIL on failure, or SP_ERR_ARG | |
232 | for invalid arguments. | |
233 | ||
234 | int sp_set_config(struct sp_port *port, struct sp_port_config *config) | |
235 | ||
236 | Sets all parameters for the specified serial port. | |
237 | ||
238 | The user should populate a struct sp_port_config, then pass a pointer to it | |
239 | as the config parameter. | |
240 | ||
241 | The fields of sp_port_config are: | |
242 | ||
243 | int baudrate: Baud rate in bits per second. | |
244 | int bits: Number of data bits to use. Valid values are 5 to 8. | |
245 | int parity: Parity setting to use. | |
246 | (SP_PARITY_NONE, SP_PARITY_EVEN or SP_PARITY_ODD) | |
247 | int stopbits: Number of stop bits to use (1 or 2). | |
248 | int rts: RTS pin mode. | |
249 | (SP_RTS_ON, SP_RTS_OFF or SP_RTS_FLOW_CONTROL) | |
250 | int cts: CTS pin mode. | |
251 | (SP_CTS_IGNORE or SP_CTS_FLOW_CONTROL) | |
252 | int dtr: DTR pin mode. | |
253 | (SP_DTR_ON, SP_DTR_OFF or SP_DTR_FLOW_CONTROL) | |
254 | int dsr: DSR pin mode. | |
255 | (SP_DSR_IGNORE or SP_DSR_FLOW_CONTROL) | |
256 | int xon_xoff: XON/XOFF flow control mode. | |
257 | (SP_XONXOFF_DISABLED, SP_XONXOFF_IN, | |
258 | SP_XONXOFF_OUT or SP_XONXOFF_INOUT) | |
259 | ||
260 | To retain the current value of any setting, set the field to to a | |
261 | negative value. | |
0a16d4de ML |
262 | |
263 | Returns: SP_OK on success, SP_ERR_FAIL on failure, or SP_ERR_ARG | |
264 | for invalid arguments. | |
265 | ||
266 | Reading, writing and flushing data | |
267 | ---------------------------------- | |
268 | ||
269 | int sp_read(struct sp_port *port, const void *buf, size_t count) | |
270 | ||
25ab82f6 ML |
271 | Reads bytes from the specified serial port. Note that this function may |
272 | return after reading less than the specified number of bytes; it is the | |
273 | user's responsibility to iterate as necessary in this case. | |
0a16d4de ML |
274 | |
275 | Parameters: | |
276 | ||
277 | port: Pointer to port structure. | |
278 | buf: Buffer in which to store the bytes read. | |
25ab82f6 | 279 | count: Maximum number of bytes to read. |
0a16d4de ML |
280 | |
281 | Returns: The number of bytes read, SP_ERR_FAIL on failure, | |
282 | or SP_ERR_ARG for invalid arguments. | |
283 | ||
284 | int sp_write(struct sp_port *port, const void *buf, size_t count) | |
285 | ||
25ab82f6 ML |
286 | Write bytes to the specified serial port. Note that this function may |
287 | return after writing less than the specified number of bytes; it is the | |
288 | user's responsibility to iterate as necessary in this case. | |
0a16d4de ML |
289 | |
290 | Parameters: | |
291 | ||
292 | port: Pointer to port structure. | |
293 | buf: Buffer containing the bytes to write. | |
25ab82f6 | 294 | count: Maximum number of bytes to write. |
0a16d4de ML |
295 | |
296 | Returns: The number of bytes written, SP_ERR_FAIL on failure, | |
297 | or SP_ERR_ARG for invalid arguments. | |
298 | ||
299 | int sp_flush(struct sp_port *port); | |
300 | ||
301 | Flushes serial port buffers. | |
302 | ||
303 | Returns: SP_OK on success, SP_ERR_FAIL on failure, or SP_ERR_ARG | |
304 | if an invalid port is passed. | |
305 | ||
306 | Error handling | |
307 | -------------- | |
308 | ||
309 | int sp_last_error_code(); | |
310 | ||
311 | Gets the error code for a failed operation. | |
312 | ||
313 | In order to obtain the correct result, this function should be called | |
314 | straight after the failure, before executing any other system operations. | |
315 | ||
316 | Returns: The system's numeric code for the error that caused the last | |
317 | operation to fail. | |
318 | ||
319 | char *sp_last_error_message(); | |
320 | ||
321 | Gets the error message for failed operation. | |
322 | ||
323 | In order to obtain the correct result, this function should be called | |
324 | straight after the failure, before executing other system operations. | |
325 | ||
326 | Returns: The system's message for the error that caused the last | |
327 | operation to fail. This string may be allocated by the function, | |
328 | and should be freed after use by calling sp_free_error_message. | |
329 | ||
330 | void sp_free_error_message(char *message); | |
331 | ||
332 | Frees the error message returned by sp_last_error_message(). |