Executar um receptor contra um cenário exportado

Um fabricante de receptores que possua um simulador GNSS de laboratório pode reproduzir nele o movimento do veículo de um cenário do Kshana, registrar o que o receptor sob teste faz e pontuar esse registro com kshana receiver-trust contra eventos declarados antes da execução. O Kshana fornece o movimento, os horários dos eventos e a pontuação. Ele não grava nenhum sinal: nada exportado aqui sintetiza, modela ou transmite uma forma de onda de radiofrequência ou de banda base, e um evento exportado é um intervalo de tempo rotulado, não uma receita para produzir interferência. O simulador e seu operador fornecem os sinais, e o operador é responsável por executá-los somente onde isso seja permitido (conduzido ou blindado, segundo as próprias instruções de segurança do simulador).

Esta página é um método. Ela não publica resultados.

1. Exportar#

kshana bench-export scenarios/gnss-ins.toml --out run1 --epoch 2025-03-01T10:00:00Z

Aplica-se ao tipo de cenário gnss-ins (um perfil de condução com atitude; as interrupções do estado de navegação são os eventos), e a jamming e gnss-sim (um receptor estacionário durante a duração do cenário; o emissor de jamming de um cenário jamming é um evento ao longo da execução). Outros tipos de cenário informam por que não têm trajetória de veículo. --epoch é o instante UTC do tempo zero do movimento (padrão 2024-01-01T00:00:00Z); os cenários não trazem data de calendário própria para o movimento do veículo. Deve ser um instante UTC real, YYYY-MM-DDTHH:MM:SS (um Z final é aceito) com o ano em 2000 a 2099 e todos os campos dentro da faixa; qualquer outra coisa é recusada. A saída é idêntica byte a byte para o mesmo cenário e época.

Referenciais e convenções#

• Posição: WGS 84, fixa à Terra (ECEF: x pelo equador no meridiano de Greenwich, z pelo polo); lat_deg, lon_deg, h_m dão a mesma posição em coordenadas geodésicas, h_m acima do elipsoide.
• Velocidade: eixos fixos à Terra, relativa à Terra.
• Attitude: heading_deg no sentido horário a partir do norte verdadeiro em [0, 360), pitch_deg positivo com o nariz para cima, roll_deg positivo com a asa direita para baixo; guinada-arfagem-rolagem (3-2-1) do referencial local norte-leste-baixo para os eixos do corpo x para a frente, y para a direita, z para baixo. Uma fonte estacionária escreve zeros. O NMEA e o texto de waypoints não carregam atitude.
• O rumo é a guinada do corpo, não a direção do deslocamento. No perfil de condução gnss-ins o corpo gira em guinada em ondas quadradas enquanto a velocidade segue, de modo que o rumo e o curso sobre o solo podem diferir em dezenas de graus (até cerca de 77 graus no cenário automotive-urban-canyon incluído). O curso RMC do NMEA é o curso sobre o solo, a direção do vetor velocidade, de modo que um simulador que lê o rumo do arquivo de movimento e outro que lê o curso do arquivo NMEA veem ângulos diferentes. O curso sobre o solo do CSV é atan2(v_east, v_north) de sua velocidade rotacionada para norte-leste-baixo.
• A altura segue o cenário. Para gnss-ins, h_m é o próprio passo no plano tangente do tipo de cenário sobre sua verdade-terreno e não é mantida constante (cerca de 7 m ao longo dos 180 s de automotive-urban-canyon); é o movimento do cenário, escrito como é.
• Valores provisórios do NMEA GGA. A qualidade do fix (1), os satélites usados (12) e o HDOP (1,0) são escritos apenas para tornar a sentença bem formada. Não dizem nada sobre a geometria do cenário nem sobre qualquer estado do receptor.
• Time: time_s após a época, UTC, segundos intercalares não modelados.
• As alturas do NMEA são elipsoidais. A altitude GGA contém a altura elipsoidal e a separação do geoide é escrita como 0,0. Um simulador que trate a altitude como altura acima do nível médio do mar colocará o veículo deslocado pela ondulação local do geoide.
• Tolerâncias de ida e volta (testadas lendo cada arquivo de volta): posição no CSV 0,1 mm, latitude e longitude 1e-9 grau, velocidade 0,1 mm/s, ângulos 1e-6 grau; posição horizontal no NMEA 5 mm, altura 1 mm, velocidade 0,001 nó, curso 0,001 grau.

Carregar os arquivos em um simulador#

Os simuladores de laboratório diferem, e este repositório não reproduz o manual de nenhum simulador. Verifique qual dos formatos acima o seu lê e quais são seus requisitos declarados:

• Muitos importadores de movimento esperam uma taxa de atualização fixa, comumente de 10 Hz. O cenário gnss-ins avança a 0,1 s; para um cenário estacionário, defina [time] step_s com a taxa que o seu simulador quer.
• Alguns importadores descartam amostras que caem entre segundos inteiros, ou ignoram a coluna de tempo e usam a ordem das linhas. Inicie o movimento em um segundo inteiro e mantenha a grade regular.
• Um importador de CSV que permita mapear colunas pode ler run1.motion.csv diretamente: escolha as colunas fixas à Terra ou geodésicas e defina suas unidades a partir de run1.motion.json. Truncar as casas decimais produz aceleração falsa, portanto mantenha a precisão escrita.
• O arquivo contém apenas movimento. Configure a constelação, a interferência e o front end do receptor no simulador, e sincronize-os com os eventos em run1.events.csv.

Nenhuma interface de script de fornecedor é escrita pelo Kshana.

Verificado com os leitores de um simulador de código aberto

Os leitores de movimento do gps-sdr-sim (MIT, commit 28ca29a6) receberam as exportações de oito cenários incluídos. Cada leitor devolveu a trajetória exportada (tests/testbench_gpssdrsim_oracle.rs, pré-registrado em xval/testbench-gpssdrsim/PREREGISTRATION.md):

• Não dê a -u o CSV de movimento completo. O leitor dele comporta 100 caracteres por linha, e uma linha do CSV tem cerca de 160 caracteres, de modo que cada linha é lida como duas amostras. A linha de cabeçalho é lida como mais uma amostra sem nenhum número.
• O gps-sdr-sim comporta no máximo 3000 amostras, 300 s a seus 10 Hz fixos, e ignora a coluna de tempo. As exportações de gnss-ins avançam a exatamente 0,1 s. Cenários mais longos, como o gnss-ins-maritime de 20 minutos, são lidos apenas até os primeiros 300 s.
• Isto verifica que os arquivos são lidos como foram escritos. Não verifica a física do cenário nem nada do que o simulador transmite.

2. Declare o que você vai pontuar antes da execução#

O arquivo de eventos traz os intervalos que o cenário define. Copie run1.events.toml para um cenário receiver-trust, acrescente qualquer previsão que queira verificar e fixe os limiares e as tolerâncias dos monitores antes de o receptor rodar. Não os ajuste depois de ver o registro; o cenário, os limiares e o SHA-256 do registro estão todos no hash do resultado.

kind = "receiver-trust"
name = "bench session 1"

[log]
format = "ubx"                 # ubx, rinex, android or nmea
path = "receiver-log.ubx"

[monitors]
calibration_s = 60.0

# paste run1.events.toml here, and shift onsets by the log offset (step 4)
[[events]]
label = "gnss-denied-1"
kind = "other"
onset_s = 100.0
end_s = 160.0

Os eventos exportados trazem o tipo próprio do cenário: o emissor de jamming de um cenário jamming é jamming; uma interrupção do estado de navegação é other, porque o cenário declara que o GNSS estava indisponível, não como. Altere kind para corresponder ao que você configurar o simulador para fazer.

3. Execute o receptor#

Inicie o receptor e seu registrador, inicie o cenário do simulador com o arquivo de movimento e deixe a execução cobrir o intervalo de calibração, todos os eventos e uma margem após o último. Guarde o registro do próprio receptor (UBX, observações RINEX 3, um CSV de registrador Android ou NMEA com sentenças de status de satélite). Um registro sem intensidade de sinal por satélite ainda pode ser pontuado pela posição do próprio receptor, mas os monitores de relação portadora-ruído precisam dela.

4. Alinhe os relógios#

receiver-trust conta os tempos dos eventos a partir da primeira época do registro do receptor; o arquivo de movimento conta a partir de sua primeira amostra. Se o registro começa d segundos antes da primeira amostra do movimento, some d a todo onset_s e end_s. Registre o deslocamento e como você o mediu, e declare-o no name do cenário ou em um comentário, já que um deslocamento errado move todas as pontuações. Os tempos dos eventos sozinhos não revelam o deslocamento; use o marcador de início de cenário do simulador ou as próprias marcas de tempo do receptor.

5. Pontue#

kshana receiver-trust bench-session.toml

grava bench-session.result.json, .trust.csv e .trust.svg. Para cada evento, o resultado informa os falsos alarmes antes do início, o primeiro alarme e seus monitores, a latência e o desfecho (detected, late, missed, not-evaluable), além de uma queda prevista e observada da relação portadora-ruído onde você declarou uma previsão. Uma discordância é informada, nunca ajustada para desaparecer. Veja RECEIVER-TRUST.md.

Para ver em quais linhas de referenciais públicos a sessão fornece evidências em apoio de:

kshana compliance-report bench-session.result.json

Veja compliance/README.md. Esse relatório descreve as evidências nas execuções que você fornece; não faz nenhuma constatação sobre o receptor nem sobre qualquer referencial.

6. Vincule o ciclo completo em um único pacote assinado#

Após a pontuação, kshana evidence round-trip amarra os quatro registros: o cenário que você exportou, as condições de teste do laboratório, o registro do receptor e a pontuação. Preencha run1.conditions.json (o caminho e o SHA-256 do registro, o receptor sob teste, o tipo e a potência declarada de cada evento) e então:

kshana evidence keygen --out lab.key
kshana evidence round-trip bench-session.toml --scenario scenarios/gnss-ins.toml \
    --conditions run1.conditions.json --from 0 --to 180 --key lab.key --out round-trip-pack
kshana evidence verify round-trip-pack --pubkey <signer public key>

round-trip-pack/config.json traz um bloco round_trip (kshana.round-trip/1) com scenario_sha256, conditions_hash, log_sha256 e a pontuação (eventos detectados dos avaliáveis, primeiro alarme), coberto pelos hashes do manifesto e pela assinatura. O comando recusa um pacote cujas condições e eventos de pontuação discordam, ou cujo hash declarado do registro não é o do registro. Como todo pacote de evidências, é um registro técnico, não um parecer jurídico.

Exemplo prático: gps-sdr-sim gravando um arquivo#

Este exemplo usa o simulador de código aberto gps-sdr-sim apenas para gravar um arquivo de banda base a partir do movimento exportado. O Kshana não transmite, e nada nesta página automatiza a reprodução desse arquivo por um rádio. Se o seu laboratório reproduz um arquivo desse tipo em um receptor, isso é responsabilidade do seu operador, feito somente onde for permitido (com cabo ou blindado, seguindo as instruções de segurança do simulador e do próprio rádio), e o Kshana não o documenta nem o encapsula.

kshana bench-export scenarios/gnss-ins.toml --out run1 --epoch 2025-03-01T10:00:00Z
tail -n +2 run1.motion.csv | cut -d, -f1-4 > run1.xyz          # time, x, y, z (see above)
gps-sdr-sim -e brdc0600.25n -u run1.xyz -b 8 -o run1.iq        # writes a file, nothing else

O que o laboratório fizer em seguida com run1.iq acontece fora do Kshana. O registro do próprio receptor, seja como for obtido, é o que o passo 5 pontua e o passo 6 vincula. Os arquivos e as verificações que o Kshana faz em suas próprias exportações são testados apenas com dados sintéticos (tests/round_trip_pack.rs); nenhuma execução de laboratório é alegada aqui.

O que este método não faz#

• Ele não produz um sinal e não diz que interferência um simulador deve gerar. Os eventos dizem quando, não o quê.
• Uma única sessão é um único ponto de dados. O resultado descreve aquele registro sob aquela configuração e nada diz sobre outros receptores, firmware, antenas ou interferência real.
• Alturas, taxas e alinhamento de tempo cabem ao operador conferir com o simulador; a exportação declara suas próprias convenções e tolerâncias, e nada além.