comparison: components/websocket/README.md
components/websocket/README.md
- changeset 0
- b74b0e4902c3
equal
deleted
inserted
replaced
| -1:000000000000 | 0:b74b0e4902c3 |
|---|---|
| 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. |
