Dispatch Request Descriptions
The following diagram shows the message flow for dispatch requests.
A Generate Dispatch Message
The message sent over digital communications channels to transmit a sequence of service periods to a receiver.
The message may be triggered for multiple reasons - on purchase, on schedule, on repeat or on user request - but crucially can be sent and displayed on the receiver. The message is expected to carry multiple pending service periods for possibly multiple services. POST request will provide a service acknowledgment indicating if the service associated with the PSN being requested matches NovAtel’s expected service. If the service associated with the PSN does not match the expected service, NovAtel will send a response depending on the FW Version of the receiver. The activation stream or dispatch command will enable the correct service on the receiver.
There are two sets of parameters that need to be used in this API Application Programming Interface depending on the FW version of the receiver:
A) Pre-2025.R2 FW
B) 2025.R2 or Post-2025.R2 FW
To determine whether to use A or B parameters, request a DISPATCHRECEIPT log from the receiver:
-
A) If the firmware responds with a “REQUESTED LOG DOES NOT EXIST” command response that means it is pre-2025.R2 firmware so proceed with A - the activation stream sequence.
-
B) If the firmware responds with a DISPATCHRECEIPT log, it is 2025.R2 or later firmware so proceed with B - the dispatch command sequence.
|
Request name |
Type of Request |
Component |
Parameter name |
Description |
|---|---|---|---|---|
|
POST |
Request Header |
CustomerNumber |
A / B: The unique NovAtel customer number associated with your account. This number identifies the account for billing purposes and specifies the destination for the invoice. |
|
|
Generate Dispatch Message |
POST |
Request Header |
UserName |
A / B: Provide an email address to serve as the contact point for this transaction. This email is used for any necessary follow-up, and it may not necessarily belong to the individual who made the purchase. |
|
Generate Dispatch Message |
POST |
Request Header |
Authorization |
A / B: Provide the Bearer token |
|
Generate Dispatch Message |
POST |
Request Body |
psn |
A / B: Product Serial Number (PSN) of the receiver. This can be either the card or enclosure PSN. |
|
Generate Dispatch Message |
POST |
Request Body |
fwVersion |
A / B: The entire GPSCARD entry in the VERSION log as reported by the receiver in Binary format, encoded in Base64 (RFC4648).
CAN: Over an OEM7 CAN port configured for NovAtel commands and logs (ISO11783-3 ETP), use a log request for Message ID 37 (0x0025 = VERSION) in binary, once. Assemble and verify the Log message with ID 37. In the array of components, find the entry with type 1 (GPSCARD). Extract the entire 108 byte entry (from type to comp time inclusive). Encode the entire 108 byte entry in Base64.
Serial: Over an OEM7 serial port configured for NovAtel commands and logs, request LOG VERSIONB ONCE. Extract the message with ID 37, verify the checksum. In the array of components, find the entry with type 1 (GPSCARD). Extract the entire 108 byte entry (from type to comp time inclusive). Encode the entire 108 byte entry in Base64. The Base64 string is the value of the parameter.
Serial Binary Format VERSIONB log message. Shown in hex – the entire sequence is a single message. Shown broken up into header in green (with the message ID bold), followed by # comp and then each component entry as a line. The GPSCARD entry is in blue, with the type field in bold – these are the 108 bytes to convert to Base64. For CAN, the header is only 9 bytes long but the body is identical. AA44121C25000020F802000086B422097E8FA818000000028136DF43 07000000 0100000046464E4C594E544D4E50310000000000444D48523232303830303439500000004F454D373730302D312E3130000000004F4D37435230393031524E30303031004 150000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000004F4D56303730303031524E303030300000 16000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000455A41505230393031524E303030310000 19000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000455A44435230393031524E303030310000 17000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000455A504B5230323034524E303030300000 03000000000000000000000000000000000000004E4D4B4C323231373031323745000000322E312E302E30000000000000000000000000000000000000000000000000000 070000004570736F6E20473332304E203132350030303032303036370000000000000000473332305044474E00000000000000003235313000000000000000000000000000 8D796580 This example converts to Base64 as: AQAAAEZGTkxZTlRNTlAxAAAAAABETUhSMjIwODAwNDlQAAAAT0VNNzcwMC0xLjEwAAAAAE9NN0NSMDkwMVJOMDAwMQBPTTdCUjAyMDBSQjAwMDEAMjAyNC9N |
|
Generate Dispatch Message |
POST |
Request Body |
terrastarInfo |
Only A: Only include terrastarinfo if the initial request for DISPATCHRECEIPT log fails with “REQUESTED LOG DOES NOT EXIST” command response, otherwise use dispatchReceipt parameter. The body of the TERRASTARINFO log as reported by the receiver in Binary format, encoded in Base64 (RFC4648).
CAN: Over an OEM7 CAN port configured for NovAtel commands and logs (ISO11783-3 ETP), use a log request for Message ID 1719 (0x0687 = TERRASTARINFO) in binary, once. Assemble and verify the Log message with ID 1719, remove the log header, encode the entire 52 byte body (from PAC to Radius inclusive) in Base64.
Serial: Over an OEM7 serial port configured for NovAtel commands and logs, request LOG TERRASTARINFOB ONCE. Extract the message that has ID 1719, verify the checksum, remove both message header and checksum, encode the entire 52 byte body (from PAC to Radius inclusive) in Base64. The Base64 string is the value of the parameter.
Example: Serial Binary Format TERRASTARINFOB log message. Shown in hex. Header and checksum are highlighted in green, with the message ID in bold. The body is shown in blue. For CAN, the header is only 9 bytes long but the body is identical. Convert the entire blue section to Base64. AA44121CB706002034000000857821092CFE200A00000002EA91DF43
For this example the Base64 string is VFM3OTE6MTUyMTo5NDcxAGQAAAAAfwCAAAAAAAAAAAAAAAAAAgAAAOOZTEKlD+TCAgAAAA== |
|
Generate Dispatch Message |
POST |
Request Body |
callerStateInfo |
A / B: The identifier supplied by the customer for use in this API call. The value will be echoed back in the response and can be used to trace responses to the initiating call. |
|
Generate Dispatch Message |
POST |
Request Body |
currentLatitude |
A / B: The current latitude of the receiver, rounded to 1 decimal place. |
|
Generate Dispatch Message |
POST |
Request Body |
currentlongitude |
A / B: The current longitude of the receiver, rounded to 1 decimal place. |
|
Generate Dispatch Message |
POST |
Request Body |
dispatchChannel |
A / B: The dispatch channel the receiver should use and can be one of two values: "All" or "telematicsOnly". "telematicsOnly" indicates that the dispatch messages are only sent as a dispatch commend or activation stream through the dispatch response. "All" indicates that dispatch messages are sent through L-Band and NTRIP in addition to dispatch command or activation stream. |
|
Generate Dispatch Message |
POST |
Request Body |
lBandBeamTable |
Only A: Only include lBandBeamTable if the initial request for DISPATCHRECEIPT log fails with “REQUESTED LOG DOES NOT EXIST” command response, otherwise use dispatchReceipt parameter. The body of the LBANDBEAMTABLE log as reported by the receiver in Binary format, including all rows, encoded in Base64 (RFC4648).
CAN: Over an OEM7 CAN port configured for NovAtel commands and logs (ISO11783-3 ETP), use a log request for Message ID 1718 (0x0686 = LBANDBEAMTABLE) in binary, once. Assemble and verify the Log message with ID 1718, remove the log header, encode the entire variable length body (from #entries to the last Access field inclusive) in Base64.
Serial: Over an OEM7 serial port configured for NovAtel commands and logs, request LOG LBANDBEAMTABLEB ONCE. Extract the message that has ID 1718, verify the checksum, remove both message header and checksum, encode the entire variable length body (from #entries to last Access field inclusive) in Base64. The Base64 string is the value of the parameter.
Example: Serial Binary Format LBANDBEAMINFOB log message. Shown in hex. Header and checksum are highlighted in green, with the message ID in bold. The body is shown in blue. For CAN, the header is only 9 bytes long but the body is identical. Convert the entire blue section to Base64. AA44121CB606002004010000847821092CFE200A00000002B819DF43 08000000 414F524500000000410000000000000018E0235CB0040000000078C101000000 414F525700000000420000000000000008B9235CB0040000000058C201000000 494F52000000000043000000000000002807245CB00400000000A74201000000 504F520000000000440000000000000068A3245CB00400000000324301000000 32354500000000004500000000000000E86A235CB00400000000C84101000000 3134332E354500004600000000000000F891235CB004000000800F4301000000 393857000000000047000000000000002807245CB00400000000C4C201000000 535039385731000053503938573100004855245CB00400000000C4C201000000 2C71D054 This example converts to Base64 as: MDgwMDAwMDA0MTRGNTI0NTAwMDAwMDAwNDEwMDAwMDAwMDAwMDAwMDE4RTAyMzVDQjAwNDAwMDAwMDAwNzhDMTAxMDAwMDAwNDE0RjUyNTcwMDAw |
|
Generate Dispatch Message |
POST |
Request Body |
dispatchReceipt |
Only B: Only include dispatchReceipt if the request for DISPATCHRECEIPT log succeeds, otherwise use the terrastarInfo and lBandBeamTable parameters. The Receipt field of the DISPATCHRECEIPT log as reported by the receiver. This is already encoded in url safe characters so does not need to be encoded again. This indicates the receiver supports dispatch and the service and model dispatch message sequence numbers currently on the receiver.
CAN: Over an OEM7 CAN port configured for NovAtel commands and logs (ISO11783-3 ETP), use a log request for Message ID 2558 (0x09FE = DISPATCHRECEIPT) in binary, once. Assemble and verify the Log message with ID 2558. Advance past the header and the array entries (each entry is 12 bytes) to the last field “Receipt” and interpret the rest of the message as ascii bytes – that is, you can copy the bytes directly to the parameter value as characters not hex values. Remove any trailing zeroes.
SERIAL Binary: Over an OEM7 serial port configured for NovAtel commands and logs, request LOG DISPATCHRECEIPTB ONCE. Extract the message with ID 2558, verify the checksum. Extract the Receipt field by advancing past the header and the array entries (that is skip 4 + # Entries * 12 bytes) and removing the checksum. Remove any trailing zeros. The remainder is ascii bytes that are url safe – copy directly to the parameter value as characters.
SERIAL ASCII Over an OEM7 serial port configured for NovAtel commands and logs, request LOG DISPATCHRECEIPT ONCE. The last comma separated field of the response, before the * delimiting the checksum, is the Receipt field. Copy directly to the parameter value.
Example: Serial Binary Format DISPATCHRECEIPTB log message. Shown in hex – the entire sequence is a single message. Shown broken up into header in green (with the message ID bold), # Entries in blue, then the 3 rows in the array (12 bytes each) and finally the Receipt field in orange. Ignore any trailing zeroes and the checksum (in green). aa 44 12 1c fe 09 00 a0 2c 00 00 00 7c b4 46 09 e9 c1 5b 19 20 00 00 02 fa b7 00 80 03 00 00 00 00 00 00 00 01 00 00 01 00 00 00 00 01 00 00 00 02 00 00 01 00 00 00 00 03 00 00 00 00 00 00 00 00 00 00 00 42 4D 48 52 31 37 30 39 30 30 30 35 45 3D 42 37 71 41 6F 62 70 65 37 32 6E 61 30 33 4F 64 71 4D 35 4D 45 77 6A 46 71 6F 58 3D 00 00 0b 43 ea 47 The hex bytes in the Receipt, interpreted as ascii are BMHR17090005E=B7qAobpe72na03OdqM5MEwjFqoX= “dispatchReceipt”: “BMHR17090005E=B7qAobpe72na03OdqM5MEwjFqoX7=” |
|
Generate Dispatch Message |
POST |
Response Details |
requestId |
A / B: Unique Request ID for every API Call. This can be used to triage API Call specific questions. |
|
Generate Dispatch Message |
POST |
Response Details |
responseCode |
A / B: Response Code for every API Call. See Response Codes tab on API gateway for a list of Response Codes. |
|
Generate Dispatch Message |
POST |
Response Details |
responseMessage |
A / B: Response Message for a given Response Code. |
|
Generate Dispatch Message |
POST |
Response Details |
psn |
A / B: Product Serial Number (PSN) of the receiver card. |
|
Generate Dispatch Message |
POST |
Response Details |
enclosurePSN |
A / B: Product Serial Number (PSN) of the enclosure if there is one. |
|
Generate Dispatch Message |
POST |
Response Details |
callerStateInfo |
A / B: As provided by the customer and used as an identifier for this API call. The value will be echoed back in the response; this can be used to trace responses to the initiative call. |
|
Generate Dispatch Message |
POST |
Response Details |
acknowledgement |
A/B: This parameter will only be returned if the service is up to date and no activation or dispatch is required. A response indicating that the contract running on the unit is up to date based on the PSN and information provided in the request. If the contract is up to date, the response will be "ContractUptodate". This will only be sent in the response if the contract is up to date. |
|
Generate Dispatch Message |
POST |
Response Details |
command |
Only B: This parameter will only be returned if the service is not up to date and a dispatchReceipt was included in the DispatchRequest() call. The value is a dispatch message as a url safe string. Apply it to the receiver with DISPATCHSET ADD <command>. Copy the Command value directly to the DISPATCHSET command Message field and use Mode 0=ADD. The command id is 2554 (0x09FA). The body of the message is 4 zero bytes (for Mode = ADD) followed by all the bytes in the Command value including a null termination.
CAN Example If the Command is “BMHR17090005=bNYWJjZGVmZ2hpamts”, the equivalent hex values of those are 42 4D 48 52 31 37 30 39 30 30 30 35 3D 62 4E 59 57 4A 6A 5A 47 56 6D 5A 32 68 70 61 6D 74 73 00. (This is a very short example). The complete CAN message becomes (header is green, Mode is blue, string must have null terminator): 08 FA 09 00 00 00 00 42 4D 48 52 31 37 30 39 30 30 30 35 3D 62 4E 59 57 4A 6A 5A 47 56 6D 5A 32 68 70 61 6D 74 73 00 Note that the message can be very long in theory – up to 2kB. |
|
Generate Dispatch Message |
EXAMPLE |
URL |
|
https://ecommuat.hexagonap.com/dispatchmmt1/v1/generatemessage |
|
Generate Dispatch Message |
EXAMPLE |
Body |
|
Example A: { "psn": "BNHR13592651D", "fwVersion": "AQAAAEZGTkxZTlRNTlAxAAAAAABETUhSMjIwODAwNDlQAAAAT0VNNzcwMC0xLjEwAAAAAE9NN0NSMDkwMVJOMDAwMQBPTTdCUjAyMDBSQjAwMDEAMjAyNC9NY "terrastarInfo": "VFM3OTE6MTUyMTo5NDcxAGQAAAAAfwCAAAAAAAAAAAAAAAAAAgAAAOOZTEKlD+TCAgAAAA==", "callerStateInfo": "9BD67CE7-9387-4367-A346-CD10920E49D3", "currentLatitude": 51.1, "currentLongitude": -114.6, "dispatchChannel": "telematicsOnly", "lBandBeamTable": "MDgwMDAwMDA0MTRGNTI0NTAwMDAwMDAwNDEwMDAwMDAwMDAwMDAwMDE4RTAyMzVDQjAwNDAwMDAwMDAwNzhDMTAxMDAwMDAwNDE0RjUyNTcwMDAwMDAw }
Example B: { "psn": "BNHR13592651D", "fwVersion": "AQTlJZTlRMjEwNjAyODdKAAAAT0VNNzcwMC0xLjAyAAkwMUFOMDAxMABPTTdAxMDBSQkcwMDAAA", "dispatchReceipt": "BMHR22300574R=HgAEAJAAJUhYXT9U31K-CxGDQLf0GpeqCSviIyjTMHs=", "currentLatitude": 51.1, "currentLongitude": -114.6, "dispatchChannel": "telematicsOnly" } |
|
Generate Dispatch Message |
EXAMPLE |
Response |
|
Example A/B (acknowledgement): { "psn" : "VNHR13592651D", "enclosurePSN" : "VMBM68820177Y", "callerStateInfo" : "9BD67CE7-9387-4367-A346-CD10920E49D3", "dispatchDetails" : { "acknowledgement" : "ContractUptodate" }, "responseDetails" : { "requestId" : "fcbb26d0-1c27-49d5-bd52-91e1a6369d64", "responseCode" : 0 } }
Example A (responseStream): { "psn": "VNHR13592651D", "enclosurePSN": "VMBM68820177Y", "callerStateInfo": "9BD67CE7-9387-4367-A346-CD10920E49D3", "dispatchDetails": { "responseStream": "VTL7ZTZZkOWagLU3dBVeugleDzIoWZmvsxbtceLukjiTVoJAxZDYTfse1qsJ64wJ2QZGi2SEGszVuIt/Wn9C2fLgXqKY3lpYnVWUp98PQ3hxv }, "responseDetails": { "requestId": "d1d7664d-9c84-4f89-86d2-653a82adb2b7", "responseCode": 0, "responseMessage": "Request Completed Successfully" } }
Example B (command): { "psn": "VNHR13592651D", "enclosurePSN": "VMBM68820177Y", "callerStateInfo": "9BD67CE7-9387-4367-A346-CD10920E49D3", "dispatchDetails": { "command": "VMBM68820177Y=bNYWJjZGVmZ2hpamts" }, "responseDetails": { "requestId": "d1d7664d-9c84-4f89-86d2-653a82adb2b7", "responseCode": 0, "responseMessage": "Request Completed Successfully" } }" |