Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Feature: Deprecate VTOL #93

Merged
merged 11 commits into from
Oct 5, 2024
Merged

Feature: Deprecate VTOL #93

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
11 commits
Select commit Hold shift + click to select a range
f4e9657
switch timestamp to milliseconds since epoch
i25052i Jun 5, 2024
910ee3b
Handling more waypoint types
i25052i Jun 6, 2024
c07050c
support time in milliseconds
i25052i Jun 6, 2024
499141a
add endpoint for insertion
i25052i Jun 6, 2024
00dfbfa
doc updates
i25052i Jun 6, 2024
d44cb03
explicitly reset mission after new mission / insertion
i25052i Jun 6, 2024
1f88231
command-line option to disable GCOM-facing socket
i25052i Jun 11, 2024
1fe1447
change message as well
i25052i Jun 11, 2024
1f15d93
Updated README
i25052i Jun 11, 2024
e8c3994
removed vtol transition endpoints
i25052i Sep 28, 2024
083a357
refactored land and rtl waypoints to remove vtol behaviour
i25052i Sep 28, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
233 changes: 25 additions & 208 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -6,9 +6,9 @@
2. [Endpoints](#endpoints)
3. [Sockets](#sockets)

# Instructions
## Instructions

## SITL & MissionPlanner
### SITL & MissionPlanner

1. In order to run SITL on your local machine, you will need to have Docker installed. For installation instructions, refer to the
following:
Expand Down Expand Up @@ -48,7 +48,7 @@ following:

7. If you have completed all of the above steps you should be ready to use SITL with MissionPlanner. If you see a drone show up on the map then you should be ready to go.

## Using MissionPlanner-Scripts
### Using MissionPlanner-Scripts

> [!NOTE]
> MissionPlanner currently only works on Windows
Expand Down Expand Up @@ -92,220 +92,37 @@ Then, enter the src directory and run the `pytest` command via Poetry:
poetry run pytest
```

# Endpoints
### Command Line Arguments

## (GET) /queue
| Argument | Description |
|-|-|
| `--dev` | If present, server is started in development mode rather than production. |
| `--port=9000` | Port on which to listen for HTTP requests. |
| `--status-host=localhost` | Hostname for the status socket to connect to. |
| `--status-port=1323` | Port for the status socket to connect to. |
| `--disable-status` | If present, disables the status socket. |

Returns the remaining list of waypoints in the order provided by the queue. GCOM stores longitudes and latitudes internally, so we really only need the order of names of waypoints.
## Endpoints

Waypoints that have been passed and removed from the queue, obviously, should not be displayed here either.
See `api_spec.yml` or `postman_collection.json` for up-to-date information on endpoints.

Altitude is measured relative to sea level.
## Sockets

Example response body:
The status WebSocket client connects to `localhost:1323` by default. The hostname and port can be changed via command-line arguments.

```json
[
{
"id": 1,
"name": "Alpha",
"longitude": 38.83731,
"latitude": -20.48321,
"altitude": 50.7
},
{
"id": 2,
"name": "Beta",
"longitude": 38.83731,
"latitude": -20.48321,
"altitude": 50.7
}
]
```

## (POST) /queue

POST request containing a list of waypoints with names and longitude, latitude, and altitude values. If altitude is nil, carry on with the same altitude as you had last waypoint.

Previous queue should be overwritten if there is already one in place.

Longitude, name, and latitude must not be null/empty. Returns a Bad Request status code and error message in that case.
Longitude and latitude in degrees, altitude in meters.

Altitude is measured relative to sea level.

Return status code 200 if successfully POSTed.

Example request body:

```json
[
{
"id": 1,
"name": "Alpha",
"longitude": 38.83731,
"latitude": -20.48321,
"altitude": 50.7
},
{
"id": 2,
"name": "Beta",
"longitude": 38.83731,
"latitude": -20.48321,
"altitude": null
}
]
```

## (GET) /clear

Call this endpoint to clear the current contents of the queue. The drone will no longer pursue the mission, as all waypoints have been removed.

An alternative to this endpoint is to call `POST /queue` with an empty queue as the body, since it overwrites the mission.

## (GET) /status

GET request returns the aircraft status.
Velocity in m/s. Altitude in meters and is relative to sea level. Longitude, latitude, heading in degrees.

Example response:

```json
{
"velocity": 22.2,
"longitude": 38.3182,
"latitude": 82.111,
"altitude": 28.1111,
"heading": 11.2,
"batteryvoltage": 1.5
}
```

## (GET) /lock

Stops the aircraft from moving based on the Mission Planner scripts' waypoint queue loading functionality, maintaining the queue internally.
Return Bad Request if the aircraft is already locked,
or the queue is empty.

It is still be possible to run (POST) /queue while the aircraft is locked.

This won't literally lock the aircraft either, i.e.
we can still manually set waypoints with Mission Planner. This just pauses the loading functionality of the queue program. If currently moving toward a waypoint, stop moving toward it by removing it.

## (GET) /unlock

Resume moving the aircraft based on the currently stored queue. Returns a Bad Request status code and an error message if the aircraft is already unlocked.

## (POST) /takeoff

POST request containing an altitude that is measured relative to sea level.

The altitude cannot be null. Returns a Bad Request status code and error message in that case. Altitude is in meters. Return status code 200 if successfully POSTed.

Example request body:

```json
{
"altitude": 50.7
}
```

## (POST) /rtl

Aircraft returns to home waypoint and lands (return-to-launch). Returns a Bad Request status code and error message if the drone could not execute the operation.

## (GET) /land

Aircraft stops at its current position and lands. Enters loiter mode before landing. Returns a Bad Request status code and error message if the drone could not execute the operation.

## (POST) /home

POST request containing a waypoint whose longitude, latitiude and altitiude will be the basis for the new home waypoint. All other fields will be ignored.

Longitude, latitude and altitude must not be null/empty. Returns a Bad Request status code and error message in that case.

Longitude and latitude in degrees.
Altitude in meters and is relative to sea level.
Return status code 200 if successfully POSTed.

Example request body:

```json
{
"id": 1,
"name": "Alpha",
"longitude": 38.83731,
"latitude": -20.48321,
"altitude": 50.7
}
```

## (PUT) /flightmode

This PUT request allows you to modify various settings for a drone:

- **Flight Mode:** Change the active flight mode by setting the `flight_mode` key to one of the following: `loiter`, `stabilize`, `auto`, or `guided`.
- **Drone Type:** Modify the drone configuration by setting the `drone_type` key to either `vtol` or `plane`.
- **Altitude Reference:** Update the altitude measurement standard by setting the `altitude_standard` key to `AGL` (Above Ground Level) or `ASL` (Above Sea Level).

Each of these key-value pairs is optional; you can include any, all, or none of them in the JSON request body.

### Example Request Body

```json
{
"flight_mode": "loiter",
"drone_type": "vtol",
"altitude_standard": "ASL"
}
```

## (POST) /insert
Inserts a new waypoint at the beginning of the queue. Drone should immediately head to this waypoint when the request is sent.

Example request body:

```json
{
"id": 2,
"name": "Beta",
"longitude": 18.43731,
"latitude": -19.24251,
"altitude": 42.7
}
```

# Sockets

A connection can be established through a Socket endpoint (set through command line argument, port 9001 by default). An example Node.js client has been provided in `testing/socket.js` that establishes a connection, and continually sends/recieves status information every 500ms.

## Events (server-side)

The server is listening for the following events:

### connect

Socket client connects. Outputs to console to confirm connection.

### disconnect

Socket client disconnects. Outputs to console to confirm disconnection.

### message

On recieving a `message` event, the server emits another `message` event in response, carrying a JSON containing basic drone status information. JSON Response template:
Every 100ms, it will emit the `drone_update` event with the following information:

```json
{
"velocity": 22.2,
"longitude": 38.3182,
"latitude": 82.111,
"altitude": 28.1111,
"heading": 11.2,
"batteryvoltage": 1.5
"timestamp": 0,
"latitude": 0.0,
"longitude": 0.0,
"altitude": 0.0,
"vertical_velocity": 0.0,
"velocity": 0.0,
"heading": 0.0,
"battery_voltage": 0.0
}
```

## Heartbeat

We are using the Flask SocketIO library for our implementation. By default, the server pings the client every 25 seconds.
The timestamp is the number of milliseconds since the epoch.
72 changes: 14 additions & 58 deletions api_spec.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -67,21 +67,18 @@ paths:
description: successful operation
"400":
description: bad request
/prepend:
/insert:
post:
tags:
- queue
summary: Insert a waypoint onto the front of the queue.
responses:
"200":
description: successful operation
"400":
description: bad request
/append:
post:
tags:
- queue
summary: Insert a waypoint onto the back of the queue.
summary: Inserts waypoints immediately before the current waypoint
requestBody:
content:
application/json:
schema:
type: array
items:
$ref: "#/components/schemas/Waypoint"
responses:
"200":
description: successful operation
Expand Down Expand Up @@ -192,9 +189,9 @@ paths:
post:
tags:
- landing
summary: land at designated location (VTOL-compatible)
summary: land at designated location
description: >-
VTOL compatible land at the location in the request.
Land at the location in the request.
requestBody:
content:
application/json:
Expand Down Expand Up @@ -224,47 +221,6 @@ paths:
description: Successfully set new home position
"400":
description: Home position could not be set
/vtol/transition:
get:
tags:
- options
summary: return whether the aircraft is in VTOL or fixed wing mode
description: >-
Returns the current flight mode of the aircraft. The values
correspond to those in the MAV commands, so 3 indicates VTOL flight
while 4 indicates fixed wing flight.
responses:
"200":
description: Returned flight mode
content:
application/json:
schema:
type: object
properties:
mode:
type: integer
post:
tags:
- options
summary: change the aircraft's flight mode
description: >-
Change the aircraft's flight mode. The mode to change to is
specified by the mode property in the request body. As in
the GET endpoint, use 3 to indicate VTOL and 4 to indicate
fixed wing.
requestBody:
content:
application/json:
schema:
type: object
properties:
mode:
type: integer
responses:
"200":
description: Flight mode changed
"400":
description: Invalid flight mode
/diversion:
post:
tags:
Expand Down Expand Up @@ -298,7 +254,7 @@ paths:
- options
summary: Change flight mode of the aircraft
description: >-
Set the flight mode of the aircraft to Loiter, Stabilize, Auto, or Guided
Set the flight mode of the aircraft to Loiter, Stabilize, Auto, or Guided, or set the current aircraft type to Copter or Plane.
requestBody:
content:
application/json:
Expand All @@ -307,7 +263,7 @@ paths:
properties:
mode:
type: string
enum: ['loiter', 'stabilize', 'auto', 'guided']
enum: ['copter', 'plane', 'loiter', 'stabilize', 'auto', 'guided']
responses:
"200":
description: Operation processed
Expand Down Expand Up @@ -372,7 +328,7 @@ components:
format: float64
command:
type: string
enum: ['WAYPOINT', 'LOITER_UNLIM', 'DO_VTOL_TRANSITION', 'DO_CHANGE_SPEED']
description: "Put the waypoint command here as in MissionPlanner, i.e., `LOITER_UNLIM` or `DO_CHANGE_SPEED`. Default value: `WAYPOINT`"
param1:
type: number
format: integer
Expand Down
Loading