diff --git a/text/0006-wifi-setup-messages.md b/text/0006-wifi-setup-messages.md new file mode 100644 index 0000000..bc96abd --- /dev/null +++ b/text/0006-wifi-setup-messages.md @@ -0,0 +1,126 @@ + * Start date: 2018-05-7 + * Contributors: Vladimir Provalov , Alexey Bulatov + * Related PR: [wifi-setup mavlink](https://github.com/mavlink/mavlink/pull/900) + +# Summary + +This document describes the new messages for Wi-Fi setup through mavlink protocol. +With these messages GCS can switch Wi-Fi between two modes (Client/AP), save/delete +networks to/from vehicle and requests current status of Wi-Fi. + +# Motivation + +Some of vehicles can connect to a ground station via Wi-Fi. It follows that the vehicle can be in two modes: Access Point (AP) - vehicle is connected to GCS directly (GCS is client of vehicle's access point), Client - vehicle is connected to another access point (for example, your home network) and communicates with GCS using it. +On start, vehicle is in AP mode. We need some instrument: + +* for switching vehicle's Wi-Fi between modes, +* for requesting current Wi-Fi status (Current Wi-Fi mode and SSID of current network or SSID of vehicle's AP) +* for saving/removing networks to/from a vehicle, to which vehicle can connect. +* for getting list of saved/scanned networks + +> Note: saved network - is a network which was added to vehicle using `WIFI_NETWORK_ADD` or manually (through SSH). Scanned network - is a network which was scanned by vehicle's Wi-Fi adapter. + +Switching between modes is useful for users. For example, they can add a local AP (with access to the internet) and connect their vehicles to it, ssh, and install needed packages. + +For these reasons, we want to add new messages to the mavlink protocol for setting up Wi-Fi via GCS. + +> Note: Following messages come as additional functionality to existing `WIFI_CONFIG_AP` message. + +# Detailed Design + +## Messages naming + +All messages which is related to Wi-Fi start with `WIFI_object` +All commands which is related to Wi-Fi start with `MAV_CMD_action_WIFI_objects` + +## Communication + +### Enums + +* `WIFI_SECURITY_TYPE` defines a set of Wi-Fi security types: + * `WIFI_SECURITY_TYPE_OPEN` + * `WIFI_SECURITY_TYPE_WEP` + * `WIFI_SECURITY_TYPE_WPA` + * `WIFI_SECURITY_TYPE_WPA2` + +* `WIFI_STATE` def +* ines current Wi-Fi state: + * `WIFI_STATE_UNDEFINED` + * `WIFI_STATE_AP` - Access point mode + * `WIFI_STATE_CLIENT` - Client mode + +### Wi-Fi Ack + +Wi-Fi ACK sends by vehicle as a response to GCS wifi messages (not commands). + +* `WIFI_ACK`, contains: + * `WIFI_*` message id + * Result: 0 - success, 1 - network already exists (on add), 2 - network is not exist (on delete or connect), 3 - already in AP, 4 - unknown error (may be described in `STATUS_TEXT`) + +### Request Wi-Fi status + +#### Messages + +* `MAV_CMD_GET_WIFI_STATUS` +* `WIFI_STATUS`, contains: + * current state (see `WIFI_STATE`) + * SSID (If current state is `WIFI_STATE_AP` - SSID of vehicle's AP, else if current state is `WIFI_STATE_CLIENT` - SSID of AP, to which vehicle is connected, otherwise - undefined) + +#### Description + +GCS requests Wi-Fi status using `MAV_CMD_GET_WIFI_STATUS` and waits for `WIFI_STATUS` message. + +### Request saved/scanned Wi-Fi networks list + +#### Messages + +* `MAV_CMD_GET_WIFI_NETWORKS_COUNT`, contains: + * Networks type (Saved or Scanned) +* `WIFI_NETWORKS_COUNT`, contains: + * Number of networks + * Networks type (Saved or Scanned) +* `MAV_CMD_GET_WIFI_NETWORKS_INFO`, contains: + * Networks type (Saved or Scanned) +* `WIFI_NETWORK_INFO`, contains: + * SSID of network + * Security type (See `WIFI_SECURITY_TYPE`) + * Network type (Saved scanned) + +#### Description + +First of all, GCS requests number of saved/scanned Wi-Fi networks using `MAV_CMD_GET_WIFI_NETWORKS_COUNT`. When GCS receives `WIFI_NETWORKS_COUNT`, it requests needed networks using `MAV_CMD_GET_WIFI_NETWORKS_INFO` and receives nth `WIFI_NETWORKS_INFO` from vehicle (losses can be detected using number of networks). + +### Add/delete network to/from vehicle + +#### Messages + +* `WIFI_NETWORK_ADD` + * SSID of network + * Security type (see `WIFI_SECURITY_TYPE`) + * password +* `WIFI_NETWORK_DELETE` + * SSID of network, which we want to delete + +#### Description + +GCS sends `WIFI_NETWORK_ADD`/`WIFI_NETWORK_DELETE` for adding/deleting network to/from vehicle, and waits for `WIFI_ACK`. + +### Switching between AP and Client + +#### Messages + +* `MAV_CMD_WIFI_START_AP` +* `WIFI_NETWORK_CONNECT` + * SSID of network, to which we want to connect (network should be already saved using `WIFI_NETWORK_ADD`) + +#### Description + +* For switching vehicle to AP GCS sends `MAV_CMD_WIFI_START_AP` to a vehicle and waits for `WIFI_ACK` (Possible results: 0 - success, 3 - already in AP, 4 - unknown Error) + +* For switching vehicle to Client mode GCS sends `WIFI_NETWORK_CONNECT` with SSID of network as parameter and waits for `WIFI_ACK` (Possible results: 0 - success, 2 - network doesn't exist, 4 - unknown error) + +> Note: after each switching, GCS should reconnect to a vehicle (using new IP) and, when connection is established, request for `WIFI_STATUS`. + +# References + +* [Documentation with GUI screenshots](https://docs.emlid.com/edge/qgc/wifi-setup/) \ No newline at end of file