Onboarding Service Provider
No contexto do serviço de Tracking, um Service Provider é um provedor USS que é capaz de receber dos seus drones os dados de localização em tempo real, e disponibilizar esses dados on demand em uma API também em tempo real.
Pré-requisitos técnicos
Para um USS se tornar um provedor de Tracking existem os seguintes pré-requisitos técnicos que não estão no escopo dessa documentação, ficando a critério do provedor como implementar esses pré-requisitos:
- Possuir um servidor HTTP para solicitar e receber as requisições listadas abaixo
- Possuir infraestrutura para obter os dados de posição instantânea do drone. Esses dados devem estar disponíveis em tempo real no servidor HTTP
Autenticação
Para o ensaio, a autenticação será feita em um serviço OAuth centralizado do DECEA, ainda a ser descrito.
Fluxograma
Endpoints
A dinâmica de comunicação entre Service Provider, Display Provider e DSS está descrita na norma ASTM 3411-22a. Para facilitar o entendimento, alguns possíveis cenários de utilização estão descritos na página Cenários.
O padrão seguido no ensaio será o descrito em https://github.com/uastech/standards/tree/astm_rid_api_2.1/remoteid
Conforme o padrão OpenAPI acima, os endpoints que o Service Provider precisará prover
GET | /uss/flights |
Endpoint onde os Display Providers obterão os dados de tracking das aeronaves sob responsabilidade do Service Provider em uma determinada área
Query Parameters
view | Área da solicitação, representada por dois pontos no formato lat1,lng1,lat2,lng2 . Os pontos são as extremidades da diagonal de um quadrado, onde esse quadrado representa a área da solicitação |
29.978,31.132,29.980,31.135 |
recent_positions_duration |
Se for maior que zero, indica que a requisição deve enviar todas as posições do drone nos últimos N segundos. Valor máximo: 60. Se for zero, indica que deve ser enviado apenas a última posição do drone |
60 |
Response
{
"timestamp": {
"value": "1985-04-12T23:20:50.52Z",
"format": "RFC3339"
},
"flights": [
{
"id": "PR-333334433.0dfe0e82-fd7a-44d9-af17-7fdd42751b45",
"aircraft_type": "Helicopter",
"current_state": RIDAircraftState,
"operating_area": OperatingArea,
"simulated": false,
"recent_positions" = [ RIDRecentAircraftPosition ]
}
],
"no_isas_present": false
}
timestamp | Horário em que o Service Provider recebeu a requisição |
flights.id |
ID único do provedor que identifica um voo em particular. Deverá vir no formato: "UAS_ID.FLIGHT_ID", onde UAS_ID é código SISANT da aeronave, e FLIGHT_ID é o uuid da solicitação do voo realizada no ECO-UTM.
|
flights.aircraft_type | Tipo de aeronave no padrão ICAO. Para drones, o tipo = Helicopter. Para drones de asa fixa que conseguem decolar verticalmente, o tipo = "HybridLift" |
flights.current_state | Dados do tracking de fato da aeronave, no momento atual. |
flights.operating_area | A área que a aeronave se encontra. Deve ser usado apenas quando o campo "flights.current_state" não está preenchido. |
flights.recent_positions | Lista de posições recentes da aeronave. Deve ser informado apenas quando as "recent_positions" foram requisitadas. |
no_isas_present | Indica se o provedor não possui nenhuma ISA na região informada. Caso esse valor retorne verdadeiro, o requisitante deve parar de realizar requisições para a área. |
GET | /uss/flights/{id}/details |
Endpoint onde os Display Providers obterão dados específicos de um determinado voo
Path Parameters
id | ID único do provedor para identificar o voo | b41f2785-1182-4c2e-82d5-f72f754b3fe2.0dfe0e82-fd7a-44d9-af17-7fdd42751b45 |
Response
{
"details": {
"id": "b41f2785-1182-4c2e-82d5-f72f754b3fe2.0dfe0e82-fd7a-44d9-af17-7fdd42751b45",
},
"uas_id": {
"registration_id": "PR-333334433",
},
"operator_id": "HUKMBB",
"operator_location": {
"position": {
"lng": -118.456,
"lat": 34.123
},
"altitude": {
"value": 19.5,
"reference": "W84",
"units": "M"
},
"altitude_type": "Takeoff"
},
"operation_description": "Descrição do voo, mesma descrição informada no SARPAS"
}
}
uas_id | Código SISANT da aeronave |
operator_id | Código SARPAS do operador |
operator_location | Localização do operador. Opcional |
operation_description | Descrição da Operação conforme solicitação no SARPAS |
GET | /uss/identification_service_areas/{id} |
Endpoint para obter o volume 4D de uma ISA controlada pelo Service Provider
Path Parameters
id | UUID da área possuída pelo provedor | UUID |
Response
{
"extents": {
"volume": {
"outline_circle": {
"center": {
"lng": -118.456,
"lat": 34.123
},
"radius": {
"value": 300.183,
"units": "M"
}
},
"outline_polygon": {
"vertices": [
{
"lng": -118.456,
"lat": 34.123
},
{
"lng": -118.456,
"lat": 34.123
},
{
"lng": -118.456,
"lat": 34.123
}
]
},
"altitude_lower": {
"value": 19.5,
"reference": "W84",
"units": "M"
},
"altitude_upper": {
"value": 19.5,
"reference": "W84",
"units": "M"
}
},
"time_start": {
"value": "1985-04-12T23:20:50.52Z",
"format": "RFC3339"
},
"time_end": {
"value": "1985-04-12T23:20:50.52Z",
"format": "RFC3339"
}
}
}
volume | Volume 4D da área específica |
Interação com DSS
O Service Provider, conforme definido no padrão ASTM3411-22a, deve criar entidades de área 4D denominadas Identification Service Area (ISA), onde este proverá o serviço de tracking. Os endpoints expostos pelo DSS estão descritos no arquivo OpenAPI descrito acima.
Como exemplo, o endpoint abaixo é onde o Service Provider realizará a criação da ISA no DSS:
PUT | /dss/identification_service_area/{id} |
Endpoint exposto pelo DSS onde o Service Provider realizará a criação da ISA. Essa área deve ser idêntica à area solicitada e aprovada no Sarpas
Path Param
id | UUID da ISA. Deve ser o mesmo UUID devolvido pelo ECO-UTM após a criação da solicitação de voo. |
Body
{
"extents": {
"volume": {
"outline_circle": {
"center": {
"lng": -118.456,
"lat": 34.123
},
"radius": {
"value": 300.183,
"units": "M"
}
},
"outline_polygon": {
"vertices": [
{
"lng": -118.456,
"lat": 34.123
},
{
"lng": -118.456,
"lat": 34.123
},
{
"lng": -118.456,
"lat": 34.123
}
]
},
"altitude_lower": {
"value": 19.5,
"reference": "W84",
"units": "M"
},
"altitude_upper": {
"value": 19.5,
"reference": "W84",
"units": "M"
}
},
"time_start": {
"value": "1985-04-12T23:20:50.52Z",
"format": "RFC3339"
},
"time_end": {
"value": "1985-04-12T23:20:50.52Z",
"format": "RFC3339"
}
},
"uss_base_url": "https://example.com/rid"
}
Campos notáveis
volume | Polígono OU círculo da área, idêntico ao definido no SARPAS |
altitude_lower, altitude_upper |
Altitude geodésica (WSG84, W84) máxima e mínima em metros. |
time_start, time_end |
Horário de início e fim da área. Todos os horários devem estar no timezone Zulo (UTC+0). O único formato suportado é "RFC3339" |
uss_base_url |
URL a qual o Service Provider irá responder à solicitações. Não deve conter uma barra '/' ao final. Sugere-se utilizar uma URL e não um IP. |
Response
{
"subscribers": [],
"service_area": {
"uss_base_url": "https://example.com/rid",
"owner": "myuss",
"time_start": {
"value": "1985-04-12T23:20:50.52Z",
"format": "RFC3339"
},
"time_end": {
"value": "1985-04-12T23:20:50.52Z",
"format": "RFC3339"
},
"version": "string",
"id": "string"
}
}
Campos notáveis
subcribers | Lista dos atuais subcribers dessa área. Caso a lista não esteja vazia, é OBRIGATÓRIO o envio da ISA para cada um dos subscribers listados |
version | Versão da ISA, gerado pelo DSS, para garantia de integridade. É necessário utilizar esse campo para atualizar ou deletar uma ISA. |