Skip to content

Outdated documentation

You are reading outdated documentation. This page documents ChirpStack v3. ChirpStack v4 is the latest version.

Commands

Commands are generated by ChirpStack Network Server or external applications integrating with the ChirpStack Gateway Bridge. Depending the marshaler configuration these must be sent as JSON or Protobuf. For the Protobuf definitions, please refer to gw.proto.

  • The Protocol Buffers JSON Mapping defines that bytes must be encoded as base64 strings. This also affects the gatewayID field. When re-encoding this filed to HEX encoding, you will find the expected gateway ID string.

Request the gateway to schedule a downlink transmission.

The items must contain at least one downlink option but can contain multiple items. At most one item will be emitted by the gateway. By specifying multiple items (e.g. RX1 and RX2), the gateway can retry with the next item in case of a scheduling issue.

The context key must contain the same value as the related uplink frame. It holds the gateway internal context (e.g. internal timing information).

JSON

Delay timing (e.g. Class-A)

{
    "gatewayID": "AQIDBAUGBwg=",
    "token": 1234,
    "items": [
        {
            "phyPayload": "IHN792Ld0vEHetyVv9+llJnnmz88Up6pFz8UiUdJMnUc",
            "txInfo": {
                "frequency": 868100000,
                "power": 14,
                "modulation": "LORA",
                "loRaModulationInfo": {
                    "bandwidth": 125,
                    "spreadingFactor": 10,
                    "codeRate": "4/5",
                    "polarizationInversion": true
                },
                "board": 0,
                "antenna": 0,
                "timing": "DELAY",
                "delayTimingInfo": {
                    "delay": "1s"
                },
                "context": "AAAAAAAAAAMAAAAAAAAABA=="
            }
        }
    ]
}

GPS timing (e.g. Class-B)

{
    "token": 1234,
    "gatewayID": "AQIDBAUGBwg=",
    "items": [
        {
            "phyPayload": "IHN792Ld0vEHetyVv9+llJnnmz88Up6pFz8UiUdJMnUc",
            "txInfo": {
                "frequency": 868100000,
                "power": 14,
                "modulation": "LORA",
                "loRaModulationInfo": {
                    "bandwidth": 125,
                    "spreadingFactor": 10,
                    "codeRate": "4/5",
                    "polarizationInversion": true
                },
                "board": 0,
                "antenna": 0,
                "timing": "GPS_EPOCH",
                "gpsEpochTimingInfo": {
                    "timeSinceGPSEpoch": "1s"
                }
            },
        }
    ]
}

Immediately (e.g. Class-C)

{
    "token": 1234,
    "gatewayID": "AQIDBAUGBwg=",
    "items": [
        {
            "phyPayload": "IHN792Ld0vEHetyVv9+llJnnmz88Up6pFz8UiUdJMnUc",
            "txInfo": {
                "frequency": 868100000,
                "power": 14,
                "modulation": "LORA",
                "loRaModulationInfo": {
                    "bandwidth": 125,
                    "spreadingFactor": 10,
                    "codeRate": "4/5",
                    "polarizationInversion": true
                },
                "board": 0,
                "antenna": 0,
                "timing": "IMMEDIATELY"
            },
        }
    ]
}

Protobuf

This message is defined by the DownlinkFrame Protobuf message.

exec - Command execution request

This will request the execution of a command by the ChirpStack Gateway Bridge. Please note that these commands must be pre-configured in the Configuration file.

JSON

{
    "gatewayID": "cnb/AC4GLBg=",
    "command": "reboot",
    "token": "[BASE64 ENCODED BLOB]",
    "stdin": "[OPTIONAL BASE64 ENCODED BLOB]",
    "environment": {
        "ENV_VAR_1": "value1",
        "ENV_VAR_2": "value2"
    }
}

Note: the given environment variables will be extended to the environment variables that are already exposed to the "main" process.

Protobuf

This message is defined by the GatewayCommandExecRequest Protobuf message.

raw - Raw packet-forwarder command

This payload is used for raw packet-forwarder commands that are not integrated with the ChirpStack Gateway Bridge. Currently these are the:

JSON

{
    "gatewayID": "cnb/AC4GLBg=",
    "rawID": "gsy9FN+rTwOEL8YzJJo+Kw==",
    "payload": "[BASE64 ENCODED BLOB]"
}

Protobuf

This message is defined by the RawPacketForwarderCommand Protobuf message.