2 - Sending Messages
Messages sent from an end device to a network server via one or more nearby gateways are referred to as uplinks.
In this book, you learn the rules and best practices to follow when sending uplinks from your end device using the LoRaWAN® 1.0.4 specification.
Composing the Packet
Application Data and MAC Command Fields
The Frame Port (FPort), Frame Payload (FRMPayload), and Frame Options (FOpts) fields, indicated in Figure 1, are used when sending a message that contains application data or MAC commands.
Figure 1: Application data and MAC command fields highlighted in a LoRaWAN® uplink packet
When sending an uplink containing only application data, the Frame Port is used to define the data type and the Frame Payload field is used to send the MAC command, as shown in Figure 2.
Figure 2: Use of FPort, FRMPayload, FOpts, and FOptsLen fields when sending application data only
When sending an uplink containing only MAC commands, the Frame Port is used to define the data type and the Frame Payload field is used to send the MAC command, as shown in Figure 3.
Figure 3: Use of FPort, FRMPayload, FOpts, and FOptsLen fields when sending MAC commands only
When sending both application data and MAC commands in the same uplink, the Frame Options field is used to carry the MAC commands, the Frame Port is used to define the data type and the Frame Payload fields is used to send the application data, as shown in Figure 4.
Figure 4: Use of FPort, FRMPayload, FOpts, and FOptsLen fields when sending MAC commands as well as application data
When sending neither application data nor MAC commands, the Frame Options, Frame Port, and Frame Payload fields are not set, as shown in Figure 5.
Figure 5: Use of FPort, FRMPayload, FOpts, and FOptsLen fields when sending an empty message
The rest of this section covers how to set each field.
Frame Port (FPort)
FPort is an optional field of variable length between zero and one octet, located within the MAC Payload as shown in Figure 3.
FPort is used to define the type of message contained in the Frame Payload (FRMPayload) field.
If the uplink packet will transport MAC Commands in the FRMPayload field, set FPort to 0.
If the uplink packet will transport application data in the FRMPayload, set FPort to any value between 1 and 223.
Note
The application data FPort value can be used to help your users identify the type of data being transmitted. For example, if the end device broadcasts both temperature and humidity in separate messages, FPort could be set to 1 to identify a message containing temperature and set to 2 to identify a message containing humidity. This allows messages in the FRMPayload field to be as short as possible, as there is no need to add any identifying characters at the front of the message.
If the uplink packet will not transport any data and will only be an empty message or a confirmed downlink acknowledgement, omit the FPort field so that its length is zero octets.
Read more in Section 4.3.2, ‘Port field’ (page 23) of the TS001-1.0.4 LoRaWAN® L2 1.0.4 Specification.
Frame Payload (FRMPayload)
FRMPayload is an optional field of variable length between zero and N octets, located within the MAC Payload as shown in Figure 3. The value of N depends on the region the end device will operate in and the data rate it will use to transmit the data. Learn more in the Packet Size Considerations section of our Developing LoRaWAN®-based Devices book.
FRMPayload is used to transport MAC commands or application-specific data.
If the uplink packet will transport MAC Commands in the FRMPayload field, set FPort to 0. The commands must be encrypted using the network session key (NwkSKey) before setting them in the FRMPayload field, described below.
If the uplink will transport application data in the FRMPayload field, set FPort to a value between 1 and 223.
The raw application data needs to be transformed into a compact format before transmission. The message could be encoded using the Cayenne Low Power Payload standard, which has the benefit of being supported by some network servers, enabling users to identify a device as using a Cayenne LPP encoder and not having to include a decoder themselves. This eliminates the need for you to publish a decoder and reduces the amount of documentation and decisions you need to make. Alternatively, you can come up with your own encoder specific to this application. Read the Packet Optimization section of our Developing LoRaWAN-based Devices book for advice on designing sufficiently detailed application data packets while respecting packet size limitations.
Once the application data has been encoded, it must then be encrypted using the application session key (AppSKey) before setting it in the FRMPayload field, described below.
If the uplink packet will not contain any data and will only be an empty message or a confirmed downlink acknowledgement, omit the FRMPayload field so that its length is zero octets. The FPort field must also be left empty in this case.
Encryption of MAC-Only Data Frames
MAC commands sent in the Frame Payload (FRMPayload) where the Frame Port (FPort) is set to 0 are MAC-only data frames, as shown in Figure 2. MAC-only data frames are encrypted using the NwkSKey. The NwkSKey is derived during the activation process, explained in the End Device Activation Book.
Figure 5: MAC Payload where FRMPayload contains MAC commands, with FPort set to 0
Encrypt the FRMPayload using the NwkSKey following the instructions in Section 4.3.3, ‘MAC frame payload encryption specification’ (page 24) of the TS001-1.0.4 LoRaWAN® L2 1.0.4 Specification. Encrypting the FRMPayload provides security and prevents anyone from inspecting these messages.
Warning
When you encrypt the FRMPayload, ensure that you calculate the MIC after encryption, using the encrypted FRMPayload. If you calculate the MIC on the unencrypted FRMPayload, the MIC verification will fail.
Encryption of Application-Specific Data Frames
Application-specific data frames are data frames sent where the Frame Port (FPort) is set between 1 and 255, indicating that the Frame Payload (FRMPayload) contains application data as shown in Figure 6. Application-specific data frames are encrypted using the AppSKey. The AppSKey is derived during the activation process, explained in the End Device Activation Book.
Figure 6: MAC Payload where FRMPayload contains application-specific data, with FPort set between 1 and 255
Encrypt the FRMPayload in application-specific data frames using the AppSKey, following the instructions in Section 4.3.3, ‘MAC frame payload encryption specification’ (page 24) of the TS001-1.0.4 LoRaWAN® L2 1.0.4 Specification.
Warning
When you encrypt the FRMPayload, ensure that you calculate the MIC after encryption, using the encrypted FRMPayload. If you calculate the MIC on the unencrypted FRMPayload, the MIC verification will fail.
Frame Options (FOpts)
FOpts is an optional field of variable length between zero and fifteen octets, located within the Frame Header inside the MAC Payload as shown in Figure 3.
The FOpts field is used to transmit MAC commands in the same packet as application-specific data (referred to as piggybacking). Up to 15 octets of MAC commands can be sent in the FOpts field. The FOptsLen field must also be set to the length of the FOpts field, as described in the previous chapter Metadata Fields.
Warning
If the uplink will transport MAC commands on their own, without any application data in the same packet, it must use the FRMPayload field to transmit them instead of the FOpts field.
When the FOpts field is being used to transport MAC commands, the FPort field must not be set to 0.
Read more in Section 4.3.1.6, ‘Frame options’ (page 23) of the TS001-1.0.4 LoRaWAN® L2 1.0.4 Specification.