{ "$schema": "http://json-schema.org/draft-07/schema#", "$id": "https://api-evangelist.github.io/the-things-network/json-schema/the-things-stack-uplink-message-schema.json", "title": "lorawanv3UplinkMessage", "description": "JSON Schema for lorawanv3UplinkMessage, extracted from The Things Stack v3.36 api.swagger.json", "definitions": { "lorawanv3UplinkMessage": { "type": "object", "properties": { "raw_payload": { "type": "string", "format": "byte" }, "payload": { "$ref": "#/definitions/lorawanv3Message" }, "settings": { "$ref": "#/definitions/lorawanv3TxSettings" }, "rx_metadata": { "type": "array", "items": { "type": "object", "$ref": "#/definitions/lorawanv3RxMetadata" } }, "received_at": { "type": "string", "format": "date-time", "description": "Server time when a component received the message.\nThe Gateway Server and Network Server set this value to their local server time of reception." }, "correlation_ids": { "type": "array", "items": { "type": "string" } }, "device_channel_index": { "type": "integer", "format": "int64", "description": "Index of the device channel that received the message.\nSet by Network Server." }, "consumed_airtime": { "type": "string", "description": "Consumed airtime for the transmission of the uplink message. Calculated by Network Server using the RawPayload size and the transmission settings." }, "crc_status": { "type": "boolean", "description": "Cyclic Redundancy Check (CRC) status of demodulating the frame.\nIf unset, the modulation does not support CRC or the gateway did not provide a CRC status.\nIf set to false, this message should not be processed." } }, "description": "Mapping from UDP message (other fields can be set in \"advanced\"):\n\n - time: rx_metadata.time\n - tmst: rx_metadata.timestamp\n - freq: settings.frequency\n - modu: settings.modulation\n - datr: settings.data_rate_index (and derived fields)\n - codr: settings.coding_rate\n - size: len(raw_payload)\n - data: raw_payload (and derived payload)\n - rsig: rx_metadata\n - ant: rx_metadata.antenna_index\n - chan: rx_metadata.channel_index\n - rssis: rx_metadata.rssi\n - lsnr: rx_metadata.snr", "title": "Uplink message from the end device to the network" }, "lorawanv3Message": { "type": "object", "properties": { "m_hdr": { "$ref": "#/definitions/lorawanv3MHDR" }, "mic": { "type": "string", "format": "byte" }, "mac_payload": { "$ref": "#/definitions/lorawanv3MACPayload" }, "join_request_payload": { "$ref": "#/definitions/v3JoinRequestPayload" }, "join_accept_payload": { "$ref": "#/definitions/v3JoinAcceptPayload" }, "rejoin_request_payload": { "$ref": "#/definitions/v3RejoinRequestPayload" } }, "title": "Message represents a LoRaWAN message" }, "v3RejoinRequestPayload": { "type": "object", "properties": { "rejoin_type": { "$ref": "#/definitions/v3RejoinRequestType" }, "net_id": { "type": "string", "format": "string", "example": "000013" }, "join_eui": { "type": "string", "format": "string", "example": "70B3D57ED000ABCD" }, "dev_eui": { "type": "string", "format": "string", "example": "70B3D57ED000ABCD" }, "rejoin_cnt": { "type": "integer", "format": "int64", "description": "Contains RJCount0 or RJCount1 depending on rejoin_type." } } }, "v3RejoinRequestType": { "type": "string", "enum": [ "CONTEXT", "SESSION", "KEYS" ], "default": "CONTEXT", "description": " - CONTEXT: Resets DevAddr, Session Keys, Frame Counters, Radio Parameters.\n - SESSION: Equivalent to the initial JoinRequest.\n - KEYS: Resets DevAddr, Session Keys, Frame Counters, while keeping the Radio Parameters." }, "v3JoinAcceptPayload": { "type": "object", "properties": { "encrypted": { "type": "string", "format": "byte" }, "join_nonce": { "type": "string", "format": "string", "example": "ABCDEF" }, "net_id": { "type": "string", "format": "string", "example": "000013" }, "dev_addr": { "type": "string", "format": "string", "example": "2600ABCD" }, "dl_settings": { "$ref": "#/definitions/v3DLSettings" }, "rx_delay": { "$ref": "#/definitions/v3RxDelay" }, "cf_list": { "$ref": "#/definitions/v3CFList" } } }, "v3RxDelay": { "type": "string", "enum": [ "RX_DELAY_0", "RX_DELAY_1", "RX_DELAY_2", "RX_DELAY_3", "RX_DELAY_4", "RX_DELAY_5", "RX_DELAY_6", "RX_DELAY_7", "RX_DELAY_8", "RX_DELAY_9", "RX_DELAY_10", "RX_DELAY_11", "RX_DELAY_12", "RX_DELAY_13", "RX_DELAY_14", "RX_DELAY_15" ], "default": "RX_DELAY_0", "description": " - RX_DELAY_0: 1 second.\n - RX_DELAY_1: 1 second.\n - RX_DELAY_2: 2 seconds.\n - RX_DELAY_3: 3 seconds.\n - RX_DELAY_4: 4 seconds.\n - RX_DELAY_5: 5 seconds.\n - RX_DELAY_6: 6 seconds.\n - RX_DELAY_7: 7 seconds.\n - RX_DELAY_8: 8 seconds.\n - RX_DELAY_9: 9 seconds.\n - RX_DELAY_10: 10 seconds.\n - RX_DELAY_11: 11 seconds.\n - RX_DELAY_12: 12 seconds.\n - RX_DELAY_13: 13 seconds.\n - RX_DELAY_14: 14 seconds.\n - RX_DELAY_15: 15 seconds." }, "v3DLSettings": { "type": "object", "properties": { "rx1_dr_offset": { "$ref": "#/definitions/v3DataRateOffset" }, "rx2_dr": { "$ref": "#/definitions/v3DataRateIndex" }, "opt_neg": { "type": "boolean", "description": "OptNeg is set if Network Server implements LoRaWAN 1.1 or greater." } } }, "v3DataRateOffset": { "type": "string", "enum": [ "DATA_RATE_OFFSET_0", "DATA_RATE_OFFSET_1", "DATA_RATE_OFFSET_2", "DATA_RATE_OFFSET_3", "DATA_RATE_OFFSET_4", "DATA_RATE_OFFSET_5", "DATA_RATE_OFFSET_6", "DATA_RATE_OFFSET_7" ], "default": "DATA_RATE_OFFSET_0" }, "v3DataRateIndex": { "type": "string", "enum": [ "DATA_RATE_0", "DATA_RATE_1", "DATA_RATE_2", "DATA_RATE_3", "DATA_RATE_4", "DATA_RATE_5", "DATA_RATE_6", "DATA_RATE_7", "DATA_RATE_8", "DATA_RATE_9", "DATA_RATE_10", "DATA_RATE_11", "DATA_RATE_12", "DATA_RATE_13", "DATA_RATE_14", "DATA_RATE_15" ], "default": "DATA_RATE_0" }, "v3CFList": { "type": "object", "properties": { "type": { "$ref": "#/definitions/v3CFListType" }, "freq": { "type": "array", "items": { "type": "integer", "format": "int64" }, "description": "Frequencies to be broadcasted, in hecto-Hz.\nThese values are broadcasted as 24 bits unsigned integers.\nThis field should not contain default values." }, "ch_masks": { "type": "array", "items": { "type": "boolean" }, "description": "ChMasks controlling the channels to be used.\nLength of this field must be equal to the amount of uplink channels\ndefined by the selected frequency plan." } } }, "v3CFListType": { "type": "string", "enum": [ "FREQUENCIES", "CHANNEL_MASKS" ], "default": "FREQUENCIES" }, "lorawanv3MHDR": { "type": "object", "properties": { "m_type": { "$ref": "#/definitions/v3MType" }, "major": { "$ref": "#/definitions/v3Major" } } }, "v3MType": { "type": "string", "enum": [ "JOIN_REQUEST", "JOIN_ACCEPT", "UNCONFIRMED_UP", "UNCONFIRMED_DOWN", "CONFIRMED_UP", "CONFIRMED_DOWN", "REJOIN_REQUEST", "PROPRIETARY" ], "default": "JOIN_REQUEST" }, "v3Major": { "type": "string", "enum": [ "LORAWAN_R1" ], "default": "LORAWAN_R1" }, "v3JoinRequestPayload": { "type": "object", "properties": { "join_eui": { "type": "string", "format": "string", "example": "70B3D57ED000ABCD" }, "dev_eui": { "type": "string", "format": "string", "example": "70B3D57ED000ABCD" }, "dev_nonce": { "type": "string", "format": "string", "example": "ABCD" } } }, "lorawanv3MACPayload": { "type": "object", "properties": { "f_hdr": { "$ref": "#/definitions/v3FHDR" }, "f_port": { "type": "integer", "format": "int64" }, "frm_payload": { "type": "string", "format": "byte" }, "decoded_payload": { "type": "object" }, "full_f_cnt": { "type": "integer", "format": "int64", "description": "Full 32-bit FCnt value. Used internally by Network Server." } } }, "v3FHDR": { "type": "object", "properties": { "dev_addr": { "type": "string", "format": "string", "example": "2600ABCD" }, "f_ctrl": { "$ref": "#/definitions/v3FCtrl" }, "f_cnt": { "type": "integer", "format": "int64" }, "f_opts": { "type": "string", "format": "byte" } } }, "v3FCtrl": { "type": "object", "properties": { "adr": { "type": "boolean" }, "adr_ack_req": { "type": "boolean", "description": "Only on uplink." }, "ack": { "type": "boolean" }, "f_pending": { "type": "boolean", "description": "Only on downlink." }, "class_b": { "type": "boolean", "description": "Only on uplink." } } }, "lorawanv3RxMetadata": { "type": "object", "properties": { "gateway_ids": { "$ref": "#/definitions/lorawanv3GatewayIdentifiers" }, "packet_broker": { "$ref": "#/definitions/lorawanv3PacketBrokerMetadata" }, "relay": { "$ref": "#/definitions/lorawanv3RelayMetadata" }, "antenna_index": { "type": "integer", "format": "int64" }, "time": { "type": "string", "format": "date-time", "description": "Timestamp at the end of the transmission, provided by the gateway. The accuracy is undefined." }, "timestamp": { "type": "integer", "format": "int64", "description": "Gateway concentrator timestamp when the Rx finished (microseconds)." }, "fine_timestamp": { "type": "string", "format": "uint64", "description": "Gateway's internal fine timestamp when the Rx finished (nanoseconds)." }, "encrypted_fine_timestamp": { "type": "string", "format": "byte", "description": "Encrypted gateway's internal fine timestamp when the Rx finished (nanoseconds)." }, "encrypted_fine_timestamp_key_id": { "type": "string" }, "rssi": { "type": "number", "format": "float", "description": "Received signal strength indicator (dBm).\nThis value equals `channel_rssi`." }, "signal_rssi": { "type": "number", "format": "float", "description": "Received signal strength indicator of the signal (dBm)." }, "channel_rssi": { "type": "number", "format": "float", "description": "Received signal strength indicator of the channel (dBm)." }, "rssi_standard_deviation": { "type": "number", "format": "float", "description": "Standard deviation of the RSSI during preamble." }, "snr": { "type": "number", "format": "float", "description": "Signal-to-noise ratio (dB)." }, "frequency_offset": { "type": "string", "format": "int64", "description": "Frequency offset (Hz)." }, "location": { "$ref": "#/definitions/lorawanv3Location", "description": "Antenna location; injected by the Gateway Server." }, "downlink_path_constraint": { "$ref": "#/definitions/v3DownlinkPathConstraint", "description": "Gateway downlink path constraint; injected by the Gateway Server." }, "uplink_token": { "type": "string", "format": "byte", "description": "Uplink token to be included in the Tx request in class A downlink; injected by gateway, Gateway Server or fNS." }, "channel_index": { "type": "integer", "format": "int64", "description": "Index of the gateway channel that received the message." }, "hopping_width": { "type": "integer", "format": "int64", "description": "Hopping width; a number describing the number of steps of the LR-FHSS grid." }, "frequency_drift": { "type": "integer", "format": "int32", "description": "Frequency drift in Hz between start and end of an LR-FHSS packet (signed)." }, "gps_time": { "type": "string", "format": "date-time", "description": "Timestamp at the end of the transmission, provided by the gateway.\nGuaranteed to be based on a GPS PPS signal, with an accuracy of 1 millisecond." }, "received_at": { "type": "string", "format": "date-time", "description": "Timestamp at which the Gateway Server has received the message." }, "advanced": { "type": "object", "title": "Advanced metadata fields\n- can be used for advanced information or experimental features that are not yet formally defined in the API\n- field names are written in snake_case" } }, "description": "Contains metadata for a received message. Each antenna that receives\na message corresponds to one RxMetadata." }, "lorawanv3GatewayIdentifiers": { "type": "object", "properties": { "gateway_id": { "type": "string" }, "eui": { "type": "string", "format": "string", "example": "70B3D57ED000ABCD", "description": "Secondary identifier, which can only be used in specific requests." } } }, "lorawanv3PacketBrokerMetadata": { "type": "object", "properties": { "message_id": { "type": "string", "description": "Message identifier generated by Packet Broker Router." }, "forwarder_net_id": { "type": "string", "format": "string", "example": "000013", "description": "LoRa Alliance NetID of the Packet Broker Forwarder Member." }, "forwarder_tenant_id": { "type": "string", "description": "Tenant ID managed by the Packet Broker Forwarder Member." }, "forwarder_cluster_id": { "type": "string", "description": "Forwarder Cluster ID of the Packet Broker Forwarder." }, "forwarder_gateway_eui": { "type": "string", "format": "string", "example": "70B3D57ED000ABCD", "description": "Forwarder gateway EUI." }, "forwarder_gateway_id": { "type": "string", "description": "Forwarder gateway ID." }, "home_network_net_id": { "type": "string", "format": "string", "example": "000013", "description": "LoRa Alliance NetID of the Packet Broker Home Network Member." }, "home_network_tenant_id": { "type": "string", "description": "Tenant ID managed by the Packet Broker Home Network Member.\nThis value is empty if it cannot be determined by the Packet Broker Router." }, "home_network_cluster_id": { "type": "string", "description": "Home Network Cluster ID of the Packet Broker Home Network." }, "hops": { "type": "array", "items": { "type": "object", "$ref": "#/definitions/v3PacketBrokerRouteHop" }, "description": "Hops that the message passed. Each Packet Broker Router service appends an entry." } } }, "v3PacketBrokerRouteHop": { "type": "object", "properties": { "received_at": { "type": "string", "format": "date-time", "description": "Time when the service received the message." }, "sender_name": { "type": "string", "description": "Sender of the message, typically the authorized client identifier." }, "sender_address": { "type": "string", "description": "Sender IP address or host name." }, "receiver_name": { "type": "string", "description": "Receiver of the message." }, "receiver_agent": { "type": "string", "description": "Receiver agent." } } }, "lorawanv3Location": { "type": "object", "properties": { "latitude": { "type": "number", "format": "double", "description": "The North\u2013South position (degrees; -90 to +90), where 0 is the equator, North pole is positive, South pole is negative." }, "longitude": { "type": "number", "format": "double", "description": "The East-West position (degrees; -180 to +180), where 0 is the Prime Meridian (Greenwich), East is positive , West is negative." }, "altitude": { "type": "integer", "format": "int32", "description": "The altitude (meters), where 0 is the mean sea level." }, "accuracy": { "type": "integer", "format": "int32", "description": "The accuracy of the location (meters)." }, "source": { "$ref": "#/definitions/v3LocationSource", "description": "Source of the location information." } } }, "v3LocationSource": { "type": "string", "enum": [ "SOURCE_UNKNOWN", "SOURCE_GPS", "SOURCE_REGISTRY", "SOURCE_IP_GEOLOCATION", "SOURCE_WIFI_RSSI_GEOLOCATION", "SOURCE_BT_RSSI_GEOLOCATION", "SOURCE_LORA_RSSI_GEOLOCATION", "SOURCE_LORA_TDOA_GEOLOCATION", "SOURCE_COMBINED_GEOLOCATION" ], "default": "SOURCE_UNKNOWN", "description": " - SOURCE_UNKNOWN: The source of the location is not known or not set.\n - SOURCE_GPS: The location is determined by GPS.\n - SOURCE_REGISTRY: The location is set in and updated from a registry.\n - SOURCE_IP_GEOLOCATION: The location is estimated with IP geolocation.\n - SOURCE_WIFI_RSSI_GEOLOCATION: The location is estimated with WiFi RSSI geolocation.\n - SOURCE_BT_RSSI_GEOLOCATION: The location is estimated with BT/BLE RSSI geolocation.\n - SOURCE_LORA_RSSI_GEOLOCATION: The location is estimated with LoRa RSSI geolocation.\n - SOURCE_LORA_TDOA_GEOLOCATION: The location is estimated with LoRa TDOA geolocation.\n - SOURCE_COMBINED_GEOLOCATION: The location is estimated by a combination of geolocation sources.\n\nMore estimation methods can be added." }, "v3DownlinkPathConstraint": { "type": "string", "enum": [ "DOWNLINK_PATH_CONSTRAINT_NONE", "DOWNLINK_PATH_CONSTRAINT_PREFER_OTHER", "DOWNLINK_PATH_CONSTRAINT_NEVER" ], "default": "DOWNLINK_PATH_CONSTRAINT_NONE", "description": " - DOWNLINK_PATH_CONSTRAINT_NONE: Indicates that the gateway can be selected for downlink without constraints by the Network Server.\n - DOWNLINK_PATH_CONSTRAINT_PREFER_OTHER: Indicates that the gateway can be selected for downlink only if no other or better gateway can be selected.\n - DOWNLINK_PATH_CONSTRAINT_NEVER: Indicates that this gateway will never be selected for downlink, even if that results in no available downlink path." }, "lorawanv3RelayMetadata": { "type": "object", "properties": { "device_id": { "type": "string", "description": "End device identifiers of the relay." }, "wor_channel": { "$ref": "#/definitions/lorawanv3RelayWORChannel", "description": "Wake on radio channel." } } }, "lorawanv3RelayWORChannel": { "type": "string", "enum": [ "RELAY_WOR_CHANNEL_DEFAULT", "RELAY_WOR_CHANNEL_SECONDARY" ], "default": "RELAY_WOR_CHANNEL_DEFAULT" }, "lorawanv3TxSettings": { "type": "object", "properties": { "data_rate": { "$ref": "#/definitions/v3DataRate", "description": "Data rate." }, "frequency": { "type": "string", "format": "uint64", "description": "Frequency (Hz)." }, "enable_crc": { "type": "boolean", "description": "Send a CRC in the packet; only on uplink; on downlink, CRC should not be enabled." }, "timestamp": { "type": "integer", "format": "int64", "description": "Timestamp of the gateway concentrator when the uplink message was received, or when the downlink message should be transmitted (microseconds).\nOn downlink, set timestamp to 0 and time to null to use immediate scheduling." }, "time": { "type": "string", "format": "date-time", "description": "Time of the gateway when the uplink message was received, or when the downlink message should be transmitted.\nFor downlink, this requires the gateway to have GPS time synchronization." }, "downlink": { "$ref": "#/definitions/TxSettingsDownlink", "description": "Transmission settings for downlink." }, "concentrator_timestamp": { "type": "string", "format": "int64", "description": "Concentrator timestamp for the downlink as calculated by the Gateway Server scheduler.\nThis value takes into account necessary offsets such as the RTT (Round Trip Time) and TOA (Time Of Arrival).\nThis field is set and used only by the Gateway Server." } }, "description": "TxSettings contains the settings for a transmission.\nThis message is used on both uplink and downlink.\nOn downlink, this is a scheduled transmission." }, "TxSettingsDownlink": { "type": "object", "properties": { "antenna_index": { "type": "integer", "format": "int64", "description": "Index of the antenna on which the uplink was received and/or downlink must be sent." }, "tx_power": { "type": "number", "format": "float", "description": "Transmission power (dBm). Only on downlink." }, "invert_polarization": { "type": "boolean", "description": "Invert LoRa polarization; false for LoRaWAN uplink, true for downlink." } }, "description": "Transmission settings for downlink." }, "v3DataRate": { "type": "object", "properties": { "lora": { "$ref": "#/definitions/v3LoRaDataRate" }, "fsk": { "$ref": "#/definitions/v3FSKDataRate" }, "lrfhss": { "$ref": "#/definitions/v3LRFHSSDataRate" } } }, "v3FSKDataRate": { "type": "object", "properties": { "bit_rate": { "type": "integer", "format": "int64", "description": "Bit rate (bps)." } } }, "v3LoRaDataRate": { "type": "object", "properties": { "bandwidth": { "type": "integer", "format": "int64", "description": "Bandwidth (Hz)." }, "spreading_factor": { "type": "integer", "format": "int64" }, "coding_rate": { "type": "string" } } }, "v3LRFHSSDataRate": { "type": "object", "properties": { "modulation_type": { "type": "integer", "format": "int64" }, "operating_channel_width": { "type": "integer", "format": "int64", "description": "Operating Channel Width (Hz)." }, "coding_rate": { "type": "string" } } } }, "$ref": "#/definitions/lorawanv3UplinkMessage" }