Sun, 07 Jun 2020 20:59:33 +0200
Better web directory display.
0 | 1 | |
2 | By Blake Felt - blake.w.felt@gmail.com | |
3 | ||
4 | ESP32 WebSocket | |
5 | ================== | |
6 | ||
7 | A component for WebSockets on ESP-IDF using lwip netconn. | |
8 | For an example, see https://github.com/Molorius/ESP32-Examples. | |
9 | ||
10 | To add to a project, type: | |
11 | `git submodule add https://github.com/Molorius/esp32-websocket.git components/websocket` | |
12 | into the base directory of your project. | |
13 | ||
14 | Some configuration options for the Server can be found in menuconfig in: | |
15 | Component config ---> WebSocket Server | |
16 | ||
17 | This presently only has the WebSocket server code working, but client code will be added in the future (the groundwork is there). | |
18 | ||
19 | The code only allows one WebSocket server at a time, but this merely handles all incoming reads. New connections are added externally, so this can be used to hold various WebSocket connections. | |
20 | ||
21 | While this can theoretically handle very large messages, hardware constraints (RAM) limits the size of messages. I highly recommend not using more than 5000 bytes per message, but no constraint is in place for this. | |
22 | ||
23 | Any suggestions or fixes are gladly appreciated. | |
24 | ||
25 | Table of Contents | |
26 | ================= | |
27 | * [Enumerations](#enumerations) | |
28 | * [WEBSOCKET_TYPE_t](#enum-websocket_type_t) | |
29 | * [Functions](#functions) | |
30 | * [ws_server_start](#int-ws_server_start) | |
31 | * [ws_server_stop](#int-ws_server_stop) | |
32 | * [ws_server_add_client](#int-ws_server_add_clientstruct-netconn-connchar-msguint16_t-lenchar-urlvoid-callback) | |
33 | * [ws_server_add_client_protocol](#int-ws_server_add_client_protocolstruct-netconn-connchar-msguint16_t-lenchar-urlchar-protocolvoid-callback) | |
34 | * [ws_server_len_url](#int-ws_server_len_urlchar-url) | |
35 | * [ws_server_len_all](#int-ws_server_len_all) | |
36 | * [ws_server_remove_client](#int-ws_server_remove_clientint-num) | |
37 | * [ws_server_remove_clients](#int-ws_server_remove_clientschar-url) | |
38 | * [ws_server_remove_all](#int-ws_server_remove_all) | |
39 | * [ws_server_send_text_client](#int-ws_server_send_text_clientint-numchar-msguint64_t-len) | |
40 | * [ws_server_send_text_clients](#int-ws_server_send_text_clientschar-urlchar-msguint64_t-len) | |
41 | * [ws_server_send_text_all](#int-ws_server_send_text_allchar-msguint64_t-len) | |
42 | * [ws_server_send_text_client_from_callback](#int-ws_server_send_text_client_from_callbackint-numchar-msguint64_t-len) | |
43 | * [ws_server_send_text_clients_from_callback](#int-ws_server_send_text_clients_from_callbackchar-urlchar-msguint64_t-len) | |
44 | * [ws_server_send_text_all_from_callback](#int-ws_server_send_text_all_from_callbackchar-msguint64_t-len) | |
45 | ||
46 | Enumerations | |
47 | ============ | |
48 | ||
49 | enum WEBSOCKET_TYPE_t | |
50 | --------------------- | |
51 | ||
52 | The different types of WebSocket events. | |
53 | ||
54 | *Values* | |
55 | * `WEBSOCKET_CONNECT`: A new client has successfully connected. | |
56 | * `WEBSOCKET_DISCONNECT_EXTERNAL`: The other side sent a disconnect message. | |
57 | * `WEBSOCKET_DISCONNECT_INTERNAL`: The esp32 server sent a disconnect message. | |
58 | * `WEBSOCKET_DISCONNECT_ERROR`: Disconnect due to a connection error. | |
59 | * `WEBSOCKET_TEXT`: Incoming text. | |
60 | * `WEBSOCKET_BIN`: Incoming binary. | |
61 | * `WEBSOCKET_PING`: The other side sent a ping message. | |
62 | * `WEBSOCKET_PONG`: The other side successfully replied to our ping. | |
63 | ||
64 | Functions | |
65 | ========= | |
66 | ||
67 | int ws_server_start() | |
68 | --------------------- | |
69 | ||
70 | Starts the WebSocket Server. Use this function before attempting any | |
71 | sort of transmission or adding a client. | |
72 | ||
73 | *Returns* | |
74 | * 1: successful start | |
75 | * 0: server already running | |
76 | ||
77 | int ws_server_stop() | |
78 | -------------------- | |
79 | ||
80 | Stops the WebSocket Server. New clients can still be added and | |
81 | messages can be sent, but new messages will not be received. | |
82 | ||
83 | *Returns* | |
84 | * 1: successful stop | |
85 | * 0: server was not running before | |
86 | ||
87 | int ws_server_add_client(struct netconn* conn,char* msg,uint16_t len,char* url,void *callback) | |
88 | ---------------------------------------------------------------------------------------------- | |
89 | ||
90 | Adds a client to the WebSocket Server handler and performs the necessary handshake. | |
91 | ||
92 | *Parameters* | |
93 | * `conn`: the lwip netconn connection. | |
94 | * `msg`: the entire incoming request message to join the server. Necessary for the handshake. | |
95 | * `len`: the length of `msg`. | |
96 | * `url`: the NULL-terminated url. Used to keep track of clients, not required. | |
97 | * `callback`: the callback that is used to run WebSocket events. This must be with parameters(uint8_t num,WEBSOCKET_TYPE_t type,char* msg,uint64_t len) where "num" is the client number, "type" is the event type, "msg" is the incoming message, and "len" is the message length. The callback itself is optional. | |
98 | ||
99 | *Returns* | |
100 | * -2: not enough information in `msg` to perform handshake. | |
101 | * -1: server full, or connection issue. | |
102 | * 0 or greater: connection number | |
103 | ||
104 | int ws_server_add_client_protocol(struct netconn* conn,char* msg,uint16_t len,char* url,char* protocol,void *callback) | |
105 | ---------------------------------------------------------------------------------------------------------------------- | |
106 | ||
107 | Adds a client to the WebSocket Server handler and performs the necessary handshake. Will also send | |
108 | the specified protocol. | |
109 | ||
110 | *Parameters* | |
111 | * `conn`: the lwip netconn connection. | |
112 | * `msg`: the entire incoming request message to join the server. Necessary for the handshake. | |
113 | * `len`: the length of `msg`. | |
114 | * `url`: the NULL-terminated url. Used to keep track of clients, not required. | |
115 | * `protocol`: the NULL-terminated protocol. This will be sent to the client in the header. | |
116 | * `callback`: the callback that is used to run WebSocket events. This must be with parameters(uint8_t num,WEBSOCKET_TYPE_t type,char* msg,uint64_t len) where "num" is the client number, "type" is the event type, "msg" is the incoming message, and "len" is the message length. The callback itself is optional. | |
117 | ||
118 | *Returns* | |
119 | * -2: not enough information in `msg` to perform handshake. | |
120 | * -1: server full, or connection issue. | |
121 | * 0 or greater: connection number | |
122 | ||
123 | int ws_server_len_url(char* url) | |
124 | -------------------------------- | |
125 | ||
126 | Returns the number of clients connected to the specified URL. | |
127 | ||
128 | *Parameters* | |
129 | * `url`: the NULL-terminated string of the desired URL. | |
130 | ||
131 | *Returns* | |
132 | * The number of clients connected to the specified URL. | |
133 | ||
134 | int ws_server_len_all() | |
135 | ----------------------- | |
136 | ||
137 | *Returns* | |
138 | * The number of connected clients. | |
139 | ||
140 | int ws_server_remove_client(int num) | |
141 | ------------------------------------ | |
142 | ||
143 | Removes the desired client. | |
144 | ||
145 | *Parameters* | |
146 | * `num`: the client number | |
147 | ||
148 | *Returns* | |
149 | * 0: not a valid client number | |
150 | * 1: client disconnected | |
151 | ||
152 | int ws_server_remove_clients(char* url) | |
153 | --------------------------------------- | |
154 | ||
155 | Removes all clients connect to the desired URL. | |
156 | ||
157 | *Parameters* | |
158 | * `url`: the NULL-terminated URL. | |
159 | ||
160 | *Returns* | |
161 | * The number of clients that were disconnected. | |
162 | ||
163 | int ws_server_remove_all() | |
164 | -------------------------- | |
165 | ||
166 | Removes all clients from server. | |
167 | ||
168 | *Returns* | |
169 | * The number of clients that were disconnected. | |
170 | ||
171 | int ws_server_send_text_client(int num,char* msg,uint64_t len) | |
172 | -------------------------------------------------------------- | |
173 | ||
174 | Sends the desired message to the client. | |
175 | ||
176 | *Parameters* | |
177 | * `num`: the client's number. | |
178 | * `msg`: the desired message. | |
179 | * `len`: the length of the message. | |
180 | ||
181 | *Returns* | |
182 | * 0: message not sent properly | |
183 | * 1: message sent | |
184 | ||
185 | int ws_server_send_text_clients(char* url,char* msg,uint64_t len) | |
186 | ----------------------------------------------------------------- | |
187 | ||
188 | Sends the message to clients connected to the desired URL. | |
189 | ||
190 | *Parameters* | |
191 | * `url`: the NULL-terminated URL. | |
192 | * `msg`: the desired message. | |
193 | * `len`: the length of the message. | |
194 | ||
195 | *Returns* | |
196 | * The number of clients that the message was sent to. | |
197 | ||
198 | int ws_server_send_text_all(char* msg,uint64_t len) | |
199 | --------------------------------------------------- | |
200 | ||
201 | Sends the message to all connected clients. | |
202 | ||
203 | *Parameters* | |
204 | * `msg`: the desired message | |
205 | * `len`: the length of the message | |
206 | ||
207 | *Returns* | |
208 | * The number of clients that the message was sent to. | |
209 | ||
210 | int ws_server_send_text_client_from_callback(int num,char* msg,uint64_t len) | |
211 | ---------------------------------------------------------------------------- | |
212 | ||
213 | Sends the desired message to the client. Only use this inside the callback function. | |
214 | ||
215 | *Parameters* | |
216 | * `num`: the client's number. | |
217 | * `msg`: the desired message. | |
218 | * `len`: the length of the message. | |
219 | ||
220 | *Returns* | |
221 | * 0: message not sent properly | |
222 | * 1: message sent | |
223 | ||
224 | int ws_server_send_text_clients_from_callback(char* url,char* msg,uint64_t len) | |
225 | ------------------------------------------------------------------------------- | |
226 | ||
227 | Sends the message to clients connected to the desired URL. Only use this inside the callback function. | |
228 | ||
229 | *Parameters* | |
230 | * `url`: the NULL-terminated URL. | |
231 | * `msg`: the desired message. | |
232 | * `len`: the length of the message. | |
233 | ||
234 | *Returns* | |
235 | * The number of clients that the message was sent to. | |
236 | ||
237 | int ws_server_send_text_all_from_callback(char* msg,uint64_t len) | |
238 | ----------------------------------------------------------------- | |
239 | ||
240 | Sends the message to all connected clients. Only use this inside the callback function. | |
241 | ||
242 | *Parameters* | |
243 | * `msg`: the desired message | |
244 | * `len`: the length of the message | |
245 | ||
246 | *Returns* | |
247 | * The number of clients that the message was sent to. |