third-party-mirrors/EDDN
1
0
Fork 0
mirror of https://github.com/EDCD/EDDN.git synced 2025-04-19 18:17:37 +03:00
Code Issues Actions Packages Projects Releases Wiki Activity

Merge pull request #191 from EDCD/enhancement/152/schema-fsssignaldiscovered

Browse Source 
schemas/fsssignaldiscovered: Rework based on in-game findings
This commit is contained in:
Athanasius 2022-06-15 14:08:30 +01:00 committed by GitHub
commit a6fa60431a
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
3 changed files with 297 additions and 225 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

309
schemas/fsssignaldiscovered-README.md
View File

@ -1,122 +1,187 @@
# EDDN FSSSignalDiscovered Schema
## Introduction
Here we document how to take data from an ED `FSSSignalDiscovered` Journal
Event and properly structure it for sending to EDDN.
Please consult [EDDN Schemas README](./README-EDDN-schemas.md) for general
documentation for a schema such as this.
## Senders
The primary data source for this schema is the ED Journal event
`FSSSignalDiscovered`.
### Batching
You MUST put several `FSSSignalDiscovered` events to an array `signals` which is key of `message`. Minimum size of
`signals` is 1 item.
Do not make a request for every single event.
Possible algorithm of batching:
1. If the event is FSSSignalDiscovered, store it to the temporal list and proceed to next event.
2. If the next event is also FSSSignalDiscovered, repeat 1.
3. If the next event is any other or there is no other event for more than 10 seconds, send the
temporal list in a single message to EDDN.
### Elisions
You MUST remove the following key/value pairs from the data:
- `TimeRemaining` key/value pair.
You MUST refuse to send the whole `FSSSignalDiscovered` event if `USSType` key has `$USS_Type_MissionTarget;` value.
### Augmentations
#### horizons flag
You SHOULD add this key/value pair, using the value from the `LoadGame` event.
#### odyssey flag
You SHOULD add this key/value pair, using the value from the `LoadGame` event.
#### systemName
You SHOULD add a `systemName` string containing the system name from the last `FSDJump`, `CarrierJump`, or `Location`
event There exists problem when you gets `FSSSignalDiscovered` before
`FSDJump`, `CarrierJump`, or `Location` event, so you MUST cross-check it with `SystemAddress` or don't include at all.
#### StarPos
You SHOULD add a `StarPos` array containing the system co-ordinates from the
last `FSDJump`, `CarrierJump`, or `Location` event. There exists problem when you gets `FSSSignalDiscovered` before
`FSDJump`, `CarrierJump`, or `Location` event, so you MUST cross-check it with `SystemAddress` or don't include at all.
## Receivers
Receivers should remember: `horizons`, `odyssey`, `systemName`, `StarPos` are optional key/value pairs, it means you
should not rely on it will appear in every EDDN event.
## Examples
This is a few example of messages that passes current `FSSSignalDiscovered` schema.
1. A message without `horizons`, `odyssey`, `systemName`, `StarPos` fields.
```json
{
"$schemaRef":"https://eddn.edcd.io/schemas/fsssignaldiscovered/1",
"header":{
"gatewayTimestamp":"2021-11-06T22:48:43.483147Z",
"softwareName":"an software",
"softwareVersion":"a version",
"uploaderID":"an uploader"
},
"message":{
"event":"FSSSignalDiscovered",
"signals":[
{
"timestamp":"2021-07-30T19:03:08Z",
"event":"FSSSignalDiscovered",
"SystemAddress":1774711381,
"SignalName":"EXPLORER-CLASS X2X-74M",
"IsStation":true
}
]
}
}
```
2. A message with `horizons`, `odyssey`, `systemName`, `StarPos` fields which says it sent from Odyssey.
```json
{
"$schemaRef":"https://eddn.edcd.io/schemas/fsssignaldiscovered/1",
"header":{
"gatewayTimestamp":"2021-11-06T22:48:43.483147Z",
"softwareName":"an software",
"softwareVersion":"a version",
"uploaderID":"an uploader"
},
"message":{
"event":"FSSSignalDiscovered",
"signals":[
{
"timestamp":"2021-07-30T19:03:08Z",
"event":"FSSSignalDiscovered",
"SystemAddress":1774711381,
"SignalName":"EXPLORER-CLASS X2X-74M",
"IsStation":true
},
{
"timestamp":"2020-12-31T14:14:01Z",
"event":"FSSSignalDiscovered",
"SystemAddress":216054883492,
"SignalName":"$USS_NonHumanSignalSource;",
"USSType":"$USS_Type_NonHuman;",
"SpawningState":"$FactionState_None;",
"SpawningFaction":"$faction_none;",
"ThreatLevel":5
}
],
"StarPos": [
8.1875,
124.21875,
-38.5
],
"StarSystem": "HIP 56186",
"horizons": true,
"odyssey": true
}
}
```
# EDDN FSSSignalDiscovered Schema
## Introduction
Here we document how to take data from an ED `FSSSignalDiscovered` Journal
Event and properly structure it for sending to EDDN.
Please consult [EDDN Schemas README](./README-EDDN-schemas.md) for general
documentation for a schema such as this.
## Senders
The only data source for this schema is the ED Journal event
`FSSSignalDiscovered`.
### Batching
You MUST coalesce contiguous runs of `FSSSignalDiscovered` events into a
single `signals` array in the message. Minimum size of `signals` is 1 item.
Do not make a request for every single event other than where they occur
singly (such as when a player utilises the FSS to zoom into USS individually,
if there is a different following event).
Suggested algorithm for batching:
1. You will need to track the current location from `Location`, `FSDJump` and
`CarrierJump` events. This is in order to add the top-level augmentation
of `StarSystem` (system name) and `StarPos`. You will need to record:
1. `SystemAddress` - for cross-checking.
2. `StarSystem` - name of the star system.
3. `StarPos` - the galactic co-ordinates of the system.
2. If the event is `FSSSignalDiscovered`, store it to the temporal list.
3. If the event is any other, then:
1. check if it is `Location`, `FSDJump` or `CarrierJump` - if so you should
use this new location in the message for the augmentations.
2. If it is not one of those events then you should use the tracked
location from the prior such event for the augmentations.
Now construct the full `fsssignaldiscovered` schema message using the
tracked location and the stored list of events. *You **MUST** check that
the `SystemAddress` for each `FSSSignalDiscovered` event matches the
tracked location.* If there is a mis-match then drop that event.
4. Use the `timestamp` of the first signal in the batch as the top-level
`timestamp` in the `message` object.
Point 3i/ii above are because in the current (3.8.0.406) Horizons client the
`FSSSignalDiscovered` events arrive after `Location`/`FSDJump`/`CarrierJump`,
but in the current (4.0.0.1302) Odyssey client they arrive before such events.
Thus, in Horizons you use the last-tracked location, but in Odyssey you use
the "just arrived" location.
Manually FSS-scanned USS type signals will come in one by one, possibly with
other events between them (such as `Music` due to zooming in/out in FSS).
There is no need to attempt batching these together if separated by other
events, even though you'll be using the `timestamp` of the first on the
message, despite the actual time-line being dependent on how quickly the
player scans them.
This batching is more concerned with not causing an EDDN message per event
upon entry into a system.
### Elisions
Remove the `event` key/pair from each member of the `signals` array. Including
this would be redundant as by definition we're sending `FSSSignalDiscovered`
events on this schema.
You MUST remove the following key/value pairs from the data:
- `TimeRemaining` key/value pair (will be present on USS). This has a slight
PII nature and is also very ephemeral.
You MUST drop the whole `FSSSignalDiscovered` event if `USSType` key
has `$USS_Type_MissionTarget;` value. Only the Cmdr with the mission has any
use of these. There's not even a statistical use.
Because of the location cross-check the `SystemAddress` is in the top-level
`message` object, and thus you **MUST** remove such from each signal in the
array.
Do **NOT** remove the `timestamp` from each signal in the array. Whilst these
should be identical for a "just logged in or arrived in system" set of signals,
this is not true of manually FSS scanned USS signals.
### Augmentations
#### horizons flag
You SHOULD add this key/value pair, using the value from the `LoadGame` event.
#### odyssey flag
You SHOULD add this key/value pair, using the value from the `LoadGame` event.
#### StarSystem
You **MUST** add a `StarSystem` string containing the system name from the last
tracked location. You **MUST** cross-check each `FSSSignalDiscovered`
->`SystemAddress` value to ensure it matches. If it does not, you **MUST**
drop the event.
#### StarPos
You **MUST** add a `StarPos` array containing the system co-ordinates from the
tracked location. You **MUST** cross-check each `FSSSignalDiscovered`
->`SystemAddress` value to ensure it matches. If it does not, you **MUST**
drop the event.
## Receivers
### Augmentations are 'SHOULD', not 'MUST'
Receivers should remember that `horizons` and `odyssey` augmentations
are optional key/value pairs. You **SHOULD NOT** rely on them being present
in any given event.
### Duplicate messages from 'busy' systems
When a system is particularly full of signals, such as when many Fleet Carriers
are present, it has been observed that the game repeats the identical
sequence of `FSSSignalDiscovered` events. So you might receive what looks like
a duplicate message, other than the timestamp (if the timestamp is the same
then the EDDN Relay should drop the duplicate).
## Examples
This is a few example of messages that passes current `FSSSignalDiscovered` schema.
1. A message without `horizons` or `odyssey` augmentations.
```json
{
"$schemaRef":"https://eddn.edcd.io/schemas/fsssignaldiscovered/1",
"header":{
"gatewayTimestamp":"2021-11-06T22:48:43.483147Z",
"softwareName":"a software",
"softwareVersion":"a version",
"uploaderID":"an uploader"
},
"message":{
"timestamp":"2021-11-06T22:48:42Z",
"event":"FSSSignalDiscovered",
"SystemAddress":1774711381,
"signals":[
{
"timestamp":"2021-11-06T22:48:42Z",
"SignalName":"EXPLORER-CLASS X2X-74M",
"IsStation":true
}
],
"StarSystem":"HR 1185",
"StarPos": [
-64.66, -148.94, -330.41
]
}
}
```
2. A message with `horizons`, `odyssey`, `systemName`, `StarPos` fields which says it sent from Odyssey.
```json
{
"$schemaRef":"https://eddn.edcd.io/schemas/fsssignaldiscovered/1",
"header":{
"gatewayTimestamp":"2021-11-06T22:48:43.483147Z",
"softwareName":"a software",
"softwareVersion":"a version",
"uploaderID":"an uploader"
},
"message":{
"timestamp":"2021-11-06T22:48:42Z",
"event":"FSSSignalDiscovered",
"SystemAddress":1350507186531,
"signals":[
{
"timestamp":"2021-11-06T22:48:42Z",
"event":"FSSSignalDiscovered",
"SignalName":"EXPLORER-CLASS X2X-74M",
"IsStation":true
},
{
"timestamp":"2021-11-06T22:48:42Z",
"event":"FSSSignalDiscovered",
"SignalName":"$USS_NonHumanSignalSource;",
"USSType":"$USS_Type_NonHuman;",
"SpawningState":"$FactionState_None;",
"SpawningFaction":"$faction_none;",
"ThreatLevel":5
}
],
"StarPos": [
8.1875,
124.21875,
-38.5
],
"StarSystem": "HIP 56186",
"horizons": true,
"odyssey": true
}
}
```

209
schemas/fsssignaldiscovered-v1.0.json
View File

@ -1,101 +1,108 @@
{
"$schema" : "http://json-schema.org/draft-04/schema#",
"id" : "https://eddn.edcd.io/schemas/fsssignaldiscovered/1#",
"description" : "EDDN schema for FSSSignalDiscovered Journal events. Full documentation at https://github.com/EDCD/EDDN/tree/master/schemas/fsssignaldiscovered-README.md",
"type" : "object",
"additionalProperties" : false,
"required": [ "$schemaRef", "header", "message" ],
"properties": {
"$schemaRef": {
"type" : "string"
},
"header": {
"type" : "object",
"additionalProperties" : true,
"required" : [ "uploaderID", "softwareName", "softwareVersion" ],
"properties" : {
"uploaderID": {
"type" : "string"
},
"softwareName": {
"type" : "string"
},
"softwareVersion": {
"type" : "string"
},
"gatewayTimestamp": {
"type" : "string",
"format" : "date-time",
"description" : "Timestamp upon receipt at the gateway. If present, this property will be overwritten by the gateway; submitters are not intended to populate this property."
}
}
},
"message": {
"type" : "object",
"description" : "Contains all properties from the listed events in the client's journal minus Localised strings and the properties marked below as 'disallowed'",
"additionalProperties" : false,
"required" : [ "event", "signals"],
"properties" : {
"event": {
"enum" : [ "FSSSignalDiscovered" ]
},
"horizons": {
"type" : "boolean",
"description" : "Whether the sending Cmdr has a Horizons pass."
},
"odyssey": {
"type" : "boolean",
"description" : "Whether the sending Cmdr has an Odyssey expansion."
},
"signals": {
"type": "array",
"description": "Array of FSSSignalDiscovered events",
"minItems": 1,
"items": {
"type": "object",
"required": ["SystemAddress", "timestamp", "SignalName"],
"description": "Single FSSSignalDiscovered event",
"properties": {
"SystemAddress": { "type": "integer" },
"timestamp": {
"type" : "string",
"format" : "date-time"
},
"SignalName": { "type": "string" },
"IsStation": { "type": "boolean" },
"USSType": {
"type": "string",
"not": {
"pattern": "^\\$USS_Type_MissionTarget;$"
}
},
"TimeRemaining": {"$ref" : "#/definitions/disallowed"},
"SpawningState": {"type": "string"},
"SpawningFaction" : {"type": "string"},
"ThreatLevel": {"type": "integer" },
"patternProperties": {
"_Localised$" : { "$ref" : "#/definitions/disallowed" }
}
}
}
},
"systemName": {
"type" : "string",
"minLength" : 1,
"description": "Should be added by the sender"
},
"StarPos": {
"type" : "array",
"items" : { "type": "number" },
"minItems" : 3,
"maxItems" : 3,
"description" : "Should be added by the sender"
}
}
}
},
"definitions": {
"disallowed" : { "not" : { "type": [ "array", "boolean", "integer", "number", "null", "object", "string" ] } }
}
}
{
"$schema" : "http://json-schema.org/draft-04/schema#",
"id" : "https://eddn.edcd.io/schemas/fsssignaldiscovered/1#",
"description" : "EDDN schema for FSSSignalDiscovered Journal events. Full documentation at https://github.com/EDCD/EDDN/tree/master/schemas/fsssignaldiscovered-README.md",
"type" : "object",
"additionalProperties" : false,
"required": [ "$schemaRef", "header", "message" ],
"properties": {
"$schemaRef": {
"type" : "string"
},
"header": {
"type" : "object",
"additionalProperties" : true,
"required" : [ "uploaderID", "softwareName", "softwareVersion" ],
"properties" : {
"uploaderID": {
"type" : "string"
},
"softwareName": {
"type" : "string"
},
"softwareVersion": {
"type" : "string"
},
"gatewayTimestamp": {
"type" : "string",
"format" : "date-time",
"description" : "Timestamp upon receipt at the gateway. If present, this property will be overwritten by the gateway; submitters are not intended to populate this property."
}
}
},
"message": {
"type" : "object",
"description" : "Contains all properties from the listed events in the client's journal minus Localised strings and the properties marked below as 'disallowed'",
"additionalProperties" : false,
"required" : [ "event", "timestamp", "SystemAddress", "StarSystem", "StarPos", "signals"],
"properties" : {
"event": {
"enum" : [ "FSSSignalDiscovered" ]
},
"horizons": {
"type" : "boolean",
"description" : "Whether the sending Cmdr has a Horizons pass."
},
"odyssey": {
"type" : "boolean",
"description" : "Whether the sending Cmdr has an Odyssey expansion."
},
"timestamp": {
"type" : "string",
"format" : "date-time",
"description" : "Duplicate of the first signal's timestamp, for commonality with other schemas."
},
"SystemAddress": {
"type": "integer"
},
"signals": {
"type": "array",
"description": "Array of FSSSignalDiscovered events",
"minItems": 1,
"items": {
"type": "object",
"required": ["timestamp", "SignalName"],
"description": "Single FSSSignalDiscovered event",
"properties": {
"timestamp": {
"type" : "string",
"format" : "date-time"
},
"SignalName": { "type": "string" },
"IsStation": { "type": "boolean" },
"USSType": {
"type": "string",
"not": {
"pattern": "^\\$USS_Type_MissionTarget;$"
}
},
"TimeRemaining": {"$ref" : "#/definitions/disallowed"},
"SpawningState": {"type": "string"},
"SpawningFaction" : {"type": "string"},
"ThreatLevel": {"type": "integer" },
"patternProperties": {
"_Localised$" : { "$ref" : "#/definitions/disallowed" }
}
}
}
},
"StarSystem": {
"type" : "string",
"minLength" : 1,
"description": "Should be added by the sender"
},
"StarPos": {
"type" : "array",
"items" : { "type": "number" },
"minItems" : 3,
"maxItems" : 3,
"description" : "Should be added by the sender"
}
}
}
},
"definitions": {
"disallowed" : { "not" : { "type": [ "array", "boolean", "integer", "number", "null", "object", "string" ] } }
}
}

4
src/eddn/conf/Settings.py
View File

@ -82,8 +82,8 @@ class _Settings(object):
"https://eddn.edcd.io/schemas/fssbodysignals/1" : "schemas/fssbodysignals-v1.0.json",
"https://eddn.edcd.io/schemas/fssbodysignals/1/test" : "schemas/fssbodysignals-v1.0.json",
"https://eddn.edcd.io/schemasfsssignaldiscovered/1" : "schemas/fsssignaldiscovered-v1.0.json",
"https://eddn.edcd.io/schemasfsssignaldiscovered/1/test" : "schemas/fsssignaldiscovered-v1.0.json",
"https://eddn.edcd.io/schemas/fsssignaldiscovered/1" : "schemas/fsssignaldiscovered-v1.0.json",
"https://eddn.edcd.io/schemas/fsssignaldiscovered/1/test" : "schemas/fsssignaldiscovered-v1.0.json",
}
GATEWAY_OUTDATED_SCHEMAS = [