search

TheThingsNetwork / lorawan-stack

The Things Stack, an Open Source LoRaWAN Network Server
https://www.thethingsindustries.com/stack/
Apache License 2.0
936 stars 302 forks source link

Update join flow example in the events guide #2410

Closed bafonins closed 3 years ago

bafonins commented 4 years ago

Summary

We should update the join flow example in the docs.

Why do we need this ?

To be consistent with the events used in the join flow.

What is already there? What do you see now?

https://github.com/TheThingsNetwork/lorawan-stack/blob/develop/doc/content/guides/events/_index.md#L46-L211

What is missing? What do you want to see?

Updated snapshot of events happening during the join flow

How do you propose to document this?

The same way, but with updated events snapshot

Can you do this yourself and submit a Pull Request?

yes

bafonins commented 4 years ago

cc @benolayinka

benolayinka commented 4 years ago

@bafonins it will take me a lot longer than you to do this, can you do it?

bafonins commented 3 years ago

Here are the events dispatched when a device join the network:

{
    "name": "ns.up.join.receive",
    "time": "2020-10-02T08:28:16.902963518Z",
    "identifiers": [
      {
        "device_ids": {
          "device_id": "uno-otaa",
          "application_ids": {
            "application_id": "example-application"
          },
          "dev_eui": "0004A30B001BDAED",
          "join_eui": "58A0CB0001500001"
        }
      }
    ],
    "data": {
      "@type": "type.googleapis.com/ttn.lorawan.v3.UplinkMessage",
      "raw_payload": "AAEAUAEAy6BY7dobAAujBACzaHMSWIU=",
      "payload": {
        "m_hdr": {},
        "mic": "cxJYhQ==",
        "join_request_payload": {
          "join_eui": "58A0CB0001500001",
          "dev_eui": "0004A30B001BDAED",
          "dev_nonce": "68B3"
        }
      },
      "settings": {
        "data_rate": {
          "lora": {
            "bandwidth": 125000,
            "spreading_factor": 7
          }
        },
        "data_rate_index": 5,
        "coding_rate": "4/5",
        "frequency": "868300000",
        "timestamp": 2292083595
      },
      "rx_metadata": [
        {
          "gateway_ids": {
            "gateway_id": "ttkg"
          },
          "time": "2020-10-02T08:28:19Z",
          "timestamp": 2292083595,
          "rssi": -58,
          "channel_rssi": -58,
          "snr": 10.5,
          "uplink_token": "ChAKDgoMdHRrZy1ib2dkYW5zEIvX+cQIGgwIoMnb+wUQlonR3QIg+K3Q1tqnCQ=="
        }
      ],
      "received_at": "2020-10-02T08:28:16.799062784Z",
      "correlation_ids": [
        "gs:conn:01EKJZRWEK1APM8H6C4TAEGPH2",
        "gs:up:host:01EKJZRWEX2TQ5GCRNVPJZDQT7",
        "gs:uplink:01EKM6T4YXP8XKCSRVDJMKZXF3",
        "ns:uplink:01EKM6T50ZCT9T121JQK7AJK0W",
        "rpc:/ttn.lorawan.v3.GsNs/HandleUplink:01EKM6T50YXZP05609QMJH17GV"
      ],
      "device_channel_index": 1
    },
    "correlation_ids": [
      "gs:conn:01EKJZRWEK1APM8H6C4TAEGPH2",
      "gs:up:host:01EKJZRWEX2TQ5GCRNVPJZDQT7",
      "gs:uplink:01EKM6T4YXP8XKCSRVDJMKZXF3",
      "ns:uplink:01EKM6T50ZCT9T121JQK7AJK0W",
      "rpc:/ttn.lorawan.v3.GsNs/HandleUplink:01EKM6T50YXZP05609QMJH17GV"
    ],
    "origin": "ip-10-20-6-248.eu-west-1.compute.internal",
    "context": {
      "tenant-id": "CgN0dGk="
    },
    "visibility": {
      "rights": ["RIGHT_APPLICATION_TRAFFIC_READ"]
    },
    "unique_id": "01EKM6T54646GHDVBYEQ963ZSW"
  }
  {
    "name": "ns.up.join.cluster.attempt",
    "time": "2020-10-02T08:28:16.903424542Z",
    "identifiers": [
      {
        "device_ids": {
          "device_id": "uno-otaa",
          "application_ids": {
            "application_id": "example-application"
          },
          "dev_eui": "0004A30B001BDAED",
          "join_eui": "58A0CB0001500001"
        }
      }
    ],
    "data": {
      "@type": "type.googleapis.com/ttn.lorawan.v3.JoinRequest",
      "raw_payload": "AAEAUAEAy6BY7dobAAujBACzaHMSWIU=",
      "payload": {
        "m_hdr": {},
        "mic": "cxJYhQ==",
        "join_request_payload": {
          "join_eui": "58A0CB0001500001",
          "dev_eui": "0004A30B001BDAED",
          "dev_nonce": "68B3"
        }
      },
      "dev_addr": "2600139A",
      "selected_mac_version": "1.0.2",
      "net_id": "000013",
      "downlink_settings": {
        "rx2_dr": 3
      },
      "rx_delay": 5,
      "cf_list": {
        "freq": [8671000, 8673000, 8675000, 8677000, 8679000]
      },
      "correlation_ids": [
        "gs:conn:01EKJZRWEK1APM8H6C4TAEGPH2",
        "gs:up:host:01EKJZRWEX2TQ5GCRNVPJZDQT7",
        "gs:uplink:01EKM6T4YXP8XKCSRVDJMKZXF3",
        "ns:uplink:01EKM6T50ZCT9T121JQK7AJK0W",
        "rpc:/ttn.lorawan.v3.GsNs/HandleUplink:01EKM6T50YXZP05609QMJH17GV"
      ]
    },
    "correlation_ids": [
      "gs:conn:01EKJZRWEK1APM8H6C4TAEGPH2",
      "gs:up:host:01EKJZRWEX2TQ5GCRNVPJZDQT7",
      "gs:uplink:01EKM6T4YXP8XKCSRVDJMKZXF3",
      "ns:uplink:01EKM6T50ZCT9T121JQK7AJK0W",
      "rpc:/ttn.lorawan.v3.GsNs/HandleUplink:01EKM6T50YXZP05609QMJH17GV"
    ],
    "origin": "ip-10-20-6-248.eu-west-1.compute.internal",
    "context": {
      "tenant-id": "CgN0dGk="
    },
    "visibility": {
      "rights": ["RIGHT_APPLICATION_TRAFFIC_READ"]
    },
    "unique_id": "01EKM6T547RGS9E4GWNWCWXK7X"
  }
  {
    "name": "js.join.accept",
    "time": "2020-10-02T08:28:17.201540934Z",
    "identifiers": [
      {
        "device_ids": {
          "device_id": "uno-otaa",
          "application_ids": {
            "application_id": "example-application"
          },
          "dev_eui": "0004A30B001BDAED",
          "join_eui": "58A0CB0001500001",
          "dev_addr": "2600139A"
        }
      }
    ],
    "correlation_ids": ["rpc:/ttn.lorawan.v3.NsJs/HandleJoin:01EKM6T57AH5W8EGPTYYVSZSWW"],
    "origin": "ip-10-20-5-198.eu-west-1.compute.internal",
    "context": {
      "tenant-id": "CgN0dGk="
    },
    "visibility": {
      "rights": ["RIGHT_APPLICATION_TRAFFIC_READ"]
    },
    "unique_id": "01EKM6T5DHAG2CF851EF8HEHZ9"
  }
  {
    "name": "ns.up.join.cluster.success",
    "time": "2020-10-02T08:28:17.203594110Z",
    "identifiers": [
      {
        "device_ids": {
          "device_id": "uno-otaa",
          "application_ids": {
            "application_id": "example-application"
          },
          "dev_eui": "0004A30B001BDAED",
          "join_eui": "58A0CB0001500001"
        }
      }
    ],
    "data": {
      "@type": "type.googleapis.com/ttn.lorawan.v3.JoinResponse",
      "raw_payload": "IHr4dD9ct8gcyAobFx1uVaiLhqU1zXVpOPENWtbQ8ucK",
      "session_keys": {
        "session_key_id": "AXTobRTs2dH2MdTyVER0aw=="
      }
    },
    "correlation_ids": [
      "gs:conn:01EKJZRWEK1APM8H6C4TAEGPH2",
      "gs:up:host:01EKJZRWEX2TQ5GCRNVPJZDQT7",
      "gs:uplink:01EKM6T4YXP8XKCSRVDJMKZXF3",
      "ns:uplink:01EKM6T50ZCT9T121JQK7AJK0W",
      "rpc:/ttn.lorawan.v3.GsNs/HandleUplink:01EKM6T50YXZP05609QMJH17GV"
    ],
    "origin": "ip-10-20-6-248.eu-west-1.compute.internal",
    "context": {
      "tenant-id": "CgN0dGk="
    },
    "visibility": {
      "rights": ["RIGHT_APPLICATION_TRAFFIC_READ"]
    },
    "unique_id": "01EKM6T5DK1YCJ7MBQ2GSXTCJA"
  }
  {
    "name": "ns.up.join.process",
    "time": "2020-10-02T08:28:17.402372075Z",
    "identifiers": [
      {
        "device_ids": {
          "device_id": "uno-otaa",
          "application_ids": {
            "application_id": "example-application"
          },
          "dev_eui": "0004A30B001BDAED",
          "join_eui": "58A0CB0001500001"
        }
      }
    ],
    "data": {
      "@type": "type.googleapis.com/ttn.lorawan.v3.UplinkMessage",
      "raw_payload": "AAEAUAEAy6BY7dobAAujBACzaHMSWIU=",
      "payload": {
        "m_hdr": {},
        "mic": "cxJYhQ==",
        "join_request_payload": {
          "join_eui": "58A0CB0001500001",
          "dev_eui": "0004A30B001BDAED",
          "dev_nonce": "68B3"
        }
      },
      "settings": {
        "data_rate": {
          "lora": {
            "bandwidth": 125000,
            "spreading_factor": 7
          }
        },
        "data_rate_index": 5,
        "coding_rate": "4/5",
        "frequency": "868300000",
        "timestamp": 2292083595
      },
      "rx_metadata": [
        {
          "gateway_ids": {
            "gateway_id": "ttkg"
          },
          "time": "2020-10-02T08:28:19Z",
          "timestamp": 2292083595,
          "rssi": -58,
          "channel_rssi": -58,
          "snr": 10.5,
          "uplink_token": "ChAKDgoMdHRrZy1ib2dkYW5zEIvX+cQIGgwIoMnb+wUQlonR3QIg+K3Q1tqnCQ=="
        }
      ],
      "received_at": "2020-10-02T08:28:16.799062784Z",
      "correlation_ids": [
        "gs:conn:01EKJZRWEK1APM8H6C4TAEGPH2",
        "gs:up:host:01EKJZRWEX2TQ5GCRNVPJZDQT7",
        "gs:uplink:01EKM6T4YXP8XKCSRVDJMKZXF3",
        "ns:uplink:01EKM6T50ZCT9T121JQK7AJK0W",
        "rpc:/ttn.lorawan.v3.GsNs/HandleUplink:01EKM6T50YXZP05609QMJH17GV"
      ],
      "device_channel_index": 1
    },
    "correlation_ids": [
      "gs:conn:01EKJZRWEK1APM8H6C4TAEGPH2",
      "gs:up:host:01EKJZRWEX2TQ5GCRNVPJZDQT7",
      "gs:uplink:01EKM6T4YXP8XKCSRVDJMKZXF3",
      "ns:uplink:01EKM6T50ZCT9T121JQK7AJK0W",
      "rpc:/ttn.lorawan.v3.GsNs/HandleUplink:01EKM6T50YXZP05609QMJH17GV"
    ],
    "origin": "ip-10-20-6-248.eu-west-1.compute.internal",
    "context": {
      "tenant-id": "CgN0dGk="
    },
    "visibility": {
      "rights": ["RIGHT_APPLICATION_TRAFFIC_READ"]
    },
    "unique_id": "01EKM6T5KTGQAFHES7WBE289EM"
  }

  {
    "name": "as.up.join.receive",
    "time": "2020-10-02T08:28:17.413644566Z",
    "identifiers": [
      {
        "device_ids": {
          "device_id": "uno-otaa",
          "application_ids": {
            "application_id": "example-application"
          },
          "dev_eui": "0004A30B001BDAED",
          "join_eui": "58A0CB0001500001",
          "dev_addr": "2600139A"
        }
      }
    ],
    "correlation_ids": [
      "as:up:01EKM6T5M5VSEF1S4Y0TK4EHA4",
      "gs:conn:01EKJZRWEK1APM8H6C4TAEGPH2",
      "gs:up:host:01EKJZRWEX2TQ5GCRNVPJZDQT7",
      "gs:uplink:01EKM6T4YXP8XKCSRVDJMKZXF3",
      "ns:uplink:01EKM6T50ZCT9T121JQK7AJK0W",
      "rpc:/ttn.lorawan.v3.GsNs/HandleUplink:01EKM6T50YXZP05609QMJH17GV"
    ],
    "origin": "ip-10-20-5-68.eu-west-1.compute.internal",
    "context": {
      "tenant-id": "CgN0dGk="
    },
    "visibility": {
      "rights": ["RIGHT_APPLICATION_TRAFFIC_READ"]
    },
    "unique_id": "01EKM6T5M5NZX0M4F066KC40AG"
  }

  {
    "name": "as.up.join.forward",
    "time": "2020-10-02T08:28:17.415363680Z",
    "identifiers": [
      {
        "device_ids": {
          "device_id": "uno-otaa",
          "application_ids": {
            "application_id": "example-application"
          },
          "dev_eui": "0004A30B001BDAED",
          "join_eui": "58A0CB0001500001",
          "dev_addr": "2600139A"
        }
      }
    ],
    "data": {
      "@type": "type.googleapis.com/ttn.lorawan.v3.ApplicationUp",
      "end_device_ids": {
        "device_id": "uno-otaa",
        "application_ids": {
          "application_id": "example-application"
        },
        "dev_eui": "0004A30B001BDAED",
        "join_eui": "58A0CB0001500001",
        "dev_addr": "2600139A"
      },
      "correlation_ids": [
        "as:up:01EKM6T5M5VSEF1S4Y0TK4EHA4",
        "gs:conn:01EKJZRWEK1APM8H6C4TAEGPH2",
        "gs:up:host:01EKJZRWEX2TQ5GCRNVPJZDQT7",
        "gs:uplink:01EKM6T4YXP8XKCSRVDJMKZXF3",
        "ns:uplink:01EKM6T50ZCT9T121JQK7AJK0W",
        "rpc:/ttn.lorawan.v3.GsNs/HandleUplink:01EKM6T50YXZP05609QMJH17GV"
      ],
      "received_at": "2020-10-02T08:28:17.414199860Z",
      "join_accept": {
        "session_key_id": "AXTobRTs2dH2MdTyVER0aw==",
        "received_at": "2020-10-02T08:28:17.203636471Z"
      }
    },
    "correlation_ids": [
      "as:up:01EKM6T5M5VSEF1S4Y0TK4EHA4",
      "gs:conn:01EKJZRWEK1APM8H6C4TAEGPH2",
      "gs:up:host:01EKJZRWEX2TQ5GCRNVPJZDQT7",
      "gs:uplink:01EKM6T4YXP8XKCSRVDJMKZXF3",
      "ns:uplink:01EKM6T50ZCT9T121JQK7AJK0W",
      "rpc:/ttn.lorawan.v3.GsNs/HandleUplink:01EKM6T50YXZP05609QMJH17GV"
    ],
    "origin": "ip-10-20-5-68.eu-west-1.compute.internal",
    "context": {
      "tenant-id": "CgN0dGk="
    },
    "visibility": {
      "rights": ["RIGHT_APPLICATION_TRAFFIC_READ"]
    },
    "unique_id": "01EKM6T5M78EXJ9NT99F43EV3B"
  }

  {
    "name": "ns.up.join.accept.forward",
    "time": "2020-10-02T08:28:17.498968919Z",
    "identifiers": [
      {
        "device_ids": {
          "device_id": "uno-otaa",
          "application_ids": {
            "application_id": "example-application"
          },
          "dev_eui": "0004A30B001BDAED",
          "join_eui": "58A0CB0001500001",
          "dev_addr": "2600139A"
        }
      }
    ],
    "data": {
      "@type": "type.googleapis.com/ttn.lorawan.v3.ApplicationUp",
      "end_device_ids": {
        "device_id": "uno-otaa",
        "application_ids": {
          "application_id": "example-application"
        },
        "dev_eui": "0004A30B001BDAED",
        "join_eui": "58A0CB0001500001",
        "dev_addr": "2600139A"
      },
      "correlation_ids": [
        "gs:conn:01EKJZRWEK1APM8H6C4TAEGPH2",
        "gs:up:host:01EKJZRWEX2TQ5GCRNVPJZDQT7",
        "gs:uplink:01EKM6T4YXP8XKCSRVDJMKZXF3",
        "ns:uplink:01EKM6T50ZCT9T121JQK7AJK0W",
        "rpc:/ttn.lorawan.v3.GsNs/HandleUplink:01EKM6T50YXZP05609QMJH17GV"
      ],
      "join_accept": {
        "session_key_id": "AXTobRTs2dH2MdTyVER0aw==",
        "received_at": "2020-10-02T08:28:17.203636471Z"
      }
    },
    "correlation_ids": ["rpc:/ttn.lorawan.v3.AsNs/LinkApplication:01EKJGM4NMR20GT3CB0RJGPMWK"],
    "origin": "ip-10-20-6-248.eu-west-1.compute.internal",
    "context": {
      "tenant-id": "CgN0dGk="
    },
    "visibility": {
      "rights": ["RIGHT_APPLICATION_TRAFFIC_READ"]
    },
    "unique_id": "01EKM6T5PTN642VDGXZ0MVNM5K"
  }

  {
    "name": "ns.down.join.schedule.attempt",
    "time": "2020-10-02T08:28:19.610405211Z",
    "identifiers": [
      {
        "device_ids": {
          "device_id": "uno-otaa",
          "application_ids": {
            "application_id": "example-application"
          },
          "dev_eui": "0004A30B001BDAED",
          "join_eui": "58A0CB0001500001"
        }
      }
    ],
    "data": {
      "@type": "type.googleapis.com/ttn.lorawan.v3.DownlinkMessage",
      "raw_payload": "IHr4dD9ct8gcyAobFx1uVaiLhqU1zXVpOPENWtbQ8ucK",
      "payload": {
        "m_hdr": {
          "m_type": "JOIN_ACCEPT"
        },
        "join_accept_payload": {
          "join_nonce": "000000",
          "net_id": "000013",
          "dev_addr": "2600139A",
          "dl_settings": {
            "rx2_dr": 3
          },
          "rx_delay": 5,
          "cf_list": {
            "freq": [8671000, 8673000, 8675000, 8677000, 8679000]
          }
        }
      },
      "request": {
        "downlink_paths": [
          {
            "uplink_token": "ChAKDgoMdHRrZy1ib2dkYW5zEIvX+cQIGgwIoMnb+wUQlonR3QIg+K3Q1tqnCQ=="
          }
        ],
        "rx1_delay": 5,
        "rx1_data_rate_index": 5,
        "rx1_frequency": "868300000",
        "rx2_frequency": "869525000",
        "priority": "HIGHEST",
        "frequency_plan_id": "EU_863_870_TTN"
      },
      "correlation_ids": [
        "gs:conn:01EKJZRWEK1APM8H6C4TAEGPH2",
        "gs:up:host:01EKJZRWEX2TQ5GCRNVPJZDQT7",
        "gs:uplink:01EKM6T4YXP8XKCSRVDJMKZXF3",
        "ns:downlink:01EKM6T7RTXXQ3K8ZB58JBR82X",
        "ns:uplink:01EKM6T50ZCT9T121JQK7AJK0W",
        "rpc:/ttn.lorawan.v3.GsNs/HandleUplink:01EKM6T50YXZP05609QMJH17GV"
      ]
    },
    "correlation_ids": [
      "gs:conn:01EKJZRWEK1APM8H6C4TAEGPH2",
      "gs:up:host:01EKJZRWEX2TQ5GCRNVPJZDQT7",
      "gs:uplink:01EKM6T4YXP8XKCSRVDJMKZXF3",
      "ns:downlink:01EKM6T7RTXXQ3K8ZB58JBR82X",
      "ns:uplink:01EKM6T50ZCT9T121JQK7AJK0W",
      "rpc:/ttn.lorawan.v3.GsNs/HandleUplink:01EKM6T50YXZP05609QMJH17GV"
    ],
    "origin": "ip-10-20-6-248.eu-west-1.compute.internal",
    "context": {
      "tenant-id": "CgN0dGk="
    },
    "visibility": {
      "rights": ["RIGHT_APPLICATION_TRAFFIC_READ"]
    },
    "unique_id": "01EKM6T7RTKT4DPZWAYMEYT3D7"
  }

  {
    "name": "ns.down.join.schedule.success",
    "time": "2020-10-02T08:28:19.619543215Z",
    "identifiers": [
      {
        "device_ids": {
          "device_id": "uno-otaa",
          "application_ids": {
            "application_id": "example-application"
          },
          "dev_eui": "0004A30B001BDAED",
          "join_eui": "58A0CB0001500001"
        }
      }
    ],
    "data": {
      "@type": "type.googleapis.com/ttn.lorawan.v3.ScheduleDownlinkResponse",
      "delay": "2.117555039s"
    },
    "correlation_ids": [
      "gs:conn:01EKJZRWEK1APM8H6C4TAEGPH2",
      "gs:up:host:01EKJZRWEX2TQ5GCRNVPJZDQT7",
      "gs:uplink:01EKM6T4YXP8XKCSRVDJMKZXF3",
      "ns:downlink:01EKM6T7RTXXQ3K8ZB58JBR82X",
      "ns:uplink:01EKM6T50ZCT9T121JQK7AJK0W",
      "rpc:/ttn.lorawan.v3.GsNs/HandleUplink:01EKM6T50YXZP05609QMJH17GV"
    ],
    "origin": "ip-10-20-6-248.eu-west-1.compute.internal",
    "context": {
      "tenant-id": "CgN0dGk="
    },
    "visibility": {
      "rights": ["RIGHT_APPLICATION_TRAFFIC_READ"]
    },
    "unique_id": "01EKM6T7S3KKWHYGM06B3T00HP"
  }

The list is much longer that what we currently have. Do we really want to keep this in the documentation? Especially taking into account that this flow will change in the future (by removing/adding events). Do we really want to keep this synced with the docs?

@benolayinka @laurensslats

johanstokking commented 3 years ago

@benolayinka please re-open if this is still relevant.