]>
Commit | Line | Data |
---|---|---|
0a16d4de ML |
1 | ---------------------------------------------------------------- |
2 | libserialport: cross-platform library for accessing serial ports | |
3 | ---------------------------------------------------------------- | |
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 | ||
d54e9004 ML |
64 | Most functions take a pointer to a struct sp_port, which represents an serial |
65 | port. This structure is obtained from the array returned by sp_list_ports(). | |
0a16d4de | 66 | |
e9a2f9c9 | 67 | All functions can return only three possible error values. SP_ERR_ARG indicates |
0a16d4de | 68 | the function was called with invalid arguments. SP_ERR_FAIL indicates that the |
e9a2f9c9 | 69 | OS reported a failure. SP_ERR_MEM indicates that a memory allocation failed. |
01619328 | 70 | All of these error values are negative. |
0a16d4de ML |
71 | |
72 | When SP_ERR_FAIL is returned, an error code or string description of the error | |
73 | can be obtained by calling sp_last_error_code() or sp_last_error_message(). The | |
74 | error code or message is that provided by the OS; libserialport does not define | |
75 | any error codes or messages of its own. | |
76 | ||
77 | Functions calls that succeed return SP_OK, which is equal to zero, or where | |
78 | otherwise documented a positive value. | |
79 | ||
80 | The available functions are as follows: | |
81 | ||
82 | Enumeration | |
83 | ----------- | |
84 | ||
01619328 | 85 | int sp_get_port_by_name(const char *portname, struct sp_port **port_ptr); |
0a16d4de | 86 | |
01619328 ML |
87 | Obtains a pointer to a new sp_port structure representing the named port. The |
88 | user should allocate a variable of type "struct sp_port *" and pass a pointer | |
89 | to this to receive the result. | |
90 | ||
91 | Returns: SP_OK on success, SP_ERR_FAIL on failure, SP_ERR_MEM on allocation failure, | |
92 | or SP_ERR_ARG if an invalid pointer is passed. If any error is returned, | |
93 | the value pointed to by port_ptr will be set to NULL. | |
94 | ||
95 | void sp_free_port(struct sp_port *port); | |
96 | ||
97 | Frees a port structure obtained from sp_get_port_by_name(). | |
98 | ||
99 | int sp_list_ports(struct sp_port ***list_ptr); | |
100 | ||
101 | Lists the serial ports available on the system. The result obtained is an | |
102 | array of pointers to sp_port structures, terminated by a NULL. The user should | |
103 | allocate a variable of type "struct sp_port **" and pass a pointer to this to | |
104 | receive the result. | |
105 | ||
106 | The result should be freed after use by calling sp_free_port_list(). | |
107 | ||
108 | Returns: SP_OK on success, SP_ERR_FAIL on failure, SP_ERR_MEM on allocation failure, | |
109 | or SP_ERR_ARG if an invalid pointer is passed. If any error is returned, | |
110 | the value pointed to by list_ptr will be set to NULL. | |
0a16d4de | 111 | |
d54e9004 | 112 | void sp_free_port_list(struct sp_port **list); |
0a16d4de | 113 | |
01619328 | 114 | Frees a port list obtained from sp_list_ports(). |
0a16d4de ML |
115 | |
116 | Opening and closing ports | |
117 | ------------------------- | |
118 | ||
d54e9004 | 119 | int sp_open(struct sp_port *port, int flags); |
0a16d4de ML |
120 | |
121 | Opens the specified serial port. | |
122 | ||
123 | Parameters: | |
124 | ||
d54e9004 | 125 | port: Pointer to port structure. |
0a16d4de ML |
126 | flags: Flags to use when opening the serial port. Possible |
127 | flags are: SP_MODE_RDWR, SP_MODE_RDONLY, and SP_MODE_NONBLOCK. | |
128 | ||
129 | Returns: SP_OK on success, SP_ERR_FAIL on failure, or SP_ERR_ARG | |
01619328 | 130 | if an invalid port is passed. |
0a16d4de ML |
131 | |
132 | int sp_close(struct sp_port *port); | |
133 | ||
134 | Closes the specified serial port. | |
135 | ||
136 | Returns: SP_OK on success, SP_ERR_FAIL on failure, or SP_ERR_ARG | |
137 | if an invalid port is passed. | |
138 | ||
139 | Setting port parameters | |
140 | ----------------------- | |
141 | ||
142 | int sp_set_params(struct sp_port *port, int baudrate, | |
143 | int bits, int parity, int stopbits, | |
144 | int flowcontrol, int rts, int dtr); | |
145 | ||
146 | Sets serial parameters for the specified serial port. | |
147 | ||
148 | Parameters: | |
149 | ||
150 | port: Pointer to port structure. | |
151 | baudrate: Baud rate to set. | |
152 | bits: Number of data bits to use. | |
153 | parity: Parity setting to use | |
154 | (SP_PARITY_NONE, SP_PARITY_EVEN or SP_PARITY_ODD) | |
155 | stopbits: Number of stop bits to use (1 or 2). | |
156 | flowcontrol: Flow control setting to use | |
157 | (SP_FLOW_NONE, SP_FLOW_HARDWARE or SP_FLOW_SOFTWARE) | |
158 | ||
159 | Returns: SP_OK on success, SP_ERR_FAIL on failure, or SP_ERR_ARG | |
160 | for invalid arguments. | |
161 | ||
162 | Reading, writing and flushing data | |
163 | ---------------------------------- | |
164 | ||
165 | int sp_read(struct sp_port *port, const void *buf, size_t count) | |
166 | ||
167 | Reads a number of bytes from the specified serial port. | |
168 | ||
169 | Parameters: | |
170 | ||
171 | port: Pointer to port structure. | |
172 | buf: Buffer in which to store the bytes read. | |
173 | count: Number of bytes to read. | |
174 | ||
175 | Returns: The number of bytes read, SP_ERR_FAIL on failure, | |
176 | or SP_ERR_ARG for invalid arguments. | |
177 | ||
178 | int sp_write(struct sp_port *port, const void *buf, size_t count) | |
179 | ||
180 | Writes a number of bytes to the specified serial port. | |
181 | ||
182 | Parameters: | |
183 | ||
184 | port: Pointer to port structure. | |
185 | buf: Buffer containing the bytes to write. | |
186 | count: Number of bytes to write. | |
187 | ||
188 | Returns: The number of bytes written, SP_ERR_FAIL on failure, | |
189 | or SP_ERR_ARG for invalid arguments. | |
190 | ||
191 | int sp_flush(struct sp_port *port); | |
192 | ||
193 | Flushes serial port buffers. | |
194 | ||
195 | Returns: SP_OK on success, SP_ERR_FAIL on failure, or SP_ERR_ARG | |
196 | if an invalid port is passed. | |
197 | ||
198 | Error handling | |
199 | -------------- | |
200 | ||
201 | int sp_last_error_code(); | |
202 | ||
203 | Gets the error code for a failed operation. | |
204 | ||
205 | In order to obtain the correct result, this function should be called | |
206 | straight after the failure, before executing any other system operations. | |
207 | ||
208 | Returns: The system's numeric code for the error that caused the last | |
209 | operation to fail. | |
210 | ||
211 | char *sp_last_error_message(); | |
212 | ||
213 | Gets the error message for failed operation. | |
214 | ||
215 | In order to obtain the correct result, this function should be called | |
216 | straight after the failure, before executing other system operations. | |
217 | ||
218 | Returns: The system's message for the error that caused the last | |
219 | operation to fail. This string may be allocated by the function, | |
220 | and should be freed after use by calling sp_free_error_message. | |
221 | ||
222 | void sp_free_error_message(char *message); | |
223 | ||
224 | Frees the error message returned by sp_last_error_message(). |