This repository has been archived by the owner on Nov 11, 2024. It is now read-only.
-
Notifications
You must be signed in to change notification settings - Fork 104
/
Copy pathu_ubx_protocol.h
240 lines (217 loc) · 10 KB
/
u_ubx_protocol.h
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
/*
* Copyright 2019-2024 u-blox
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
#ifndef _U_UBX_PROTOCOL_H_
#define _U_UBX_PROTOCOL_H_
/* Only header files representing a direct and unavoidable
* dependency between the API of this module and the API
* of another module should be included here; otherwise
* please keep #includes to your .c files. */
/** \addtogroup __ubx-protocol __UBX Protocol
* @{
*/
/** @file
* @brief This header file defines the UBX protocol API, intended to
* encode/decode UBX format messages when communicating with a u-blox
* GNSS module.
*/
#ifdef __cplusplus
extern "C" {
#endif
/* ----------------------------------------------------------------
* COMPILE-TIME MACROS
* -------------------------------------------------------------- */
/** The length of the UBX protocol (header consisting of 0xB5,
* 0x62, class, ID and two bytes of length).
*/
#define U_UBX_PROTOCOL_HEADER_LENGTH_BYTES 6
/** The overhead of the UBX protocol (header consisting of 0xB5,
* 0x62, class, ID, two bytes of length and, at the end, two bytes
* of CRC). Must be added to the encoded message length to obtain
* the required encode buffer size.
*/
#define U_UBX_PROTOCOL_OVERHEAD_LENGTH_BYTES (U_UBX_PROTOCOL_HEADER_LENGTH_BYTES + 2)
/* ----------------------------------------------------------------
* TYPES
* -------------------------------------------------------------- */
/* ----------------------------------------------------------------
* PUBLIC FUNCTIONS
* -------------------------------------------------------------- */
/** The UBX message protocol is natively little endian, hence any
* multi-byte values must be little-endian encoded. Call this
* function to confirm that your processor is little endian if you
* intend to use multi-byte values in a message body; you must convert
* them to little-endian form if it is not since this message codec
* has no way of knowing what content you are sending. You can do this
* with the uUbxProtocolUint16Encode() and uUbxProtocolUint32Encode()
* functions provided and, likewise, decode received multi-byte values
* from a message body with the uUbxProtocolUint16Decode() and
* uUbxProtocolUint32Decode() functions provided. Of course, you can
* always use this functions in any case, since they automatically
* respect endianness, but you do not need to do so if your processor
* is already little-endian.
*
* @return true if the processor is little-endian, else false.
*/
bool uUbxProtocolIsLittleEndian();
/** Decode a uint16_t from a pointer to a little-endian uint16_t,
* ensuring that the endianness of the decoded value is correct
* for this processor.
*
* @param[in] pByte a pointer to a uint16_t value to decode; cannot be NULL.
* @return the decoded uint16_t value, endianness respected.
*/
uint16_t uUbxProtocolUint16Decode(const char *pByte);
/** Decode a uint32_t from a pointer to a little-endian uint32_t,
* ensuring that the endianness of the decoded value is correct
* for this processor.
*
* @param[in] pByte a pointer to a uint32_t value to decode; cannot be NULL.
* @return the decoded uint32_t value, endianness respected.
*/
uint32_t uUbxProtocolUint32Decode(const char *pByte);
/** Decode a uint64_t from a pointer to a little-endian uint64_t,
* ensuring that the endianness of the decoded value is correct
* for this processor.
*
* @param[in] pByte a pointer to a uint64_t value to decode; cannot be NULL.
* @return the decoded uint64_t value, endianness respected.
*/
uint64_t uUbxProtocolUint64Decode(const char *pByte);
/** Encode the given uint16_t value with correct endianness for the UBX
* protocol.
*
* @param uint16 the uint16_t value to encode.
* @return the encoded uint16_t value.
*/
uint16_t uUbxProtocolUint16Encode(uint16_t uint16);
/** Encode the given uint32_t value with correct endianness for the UBX
* protocol.
*
* @param uint32 the uint32_t value to encode.
* @return the encoded uint32_t value.
*/
uint32_t uUbxProtocolUint32Encode(uint32_t uint32);
/** Encode the given uint64_t value with correct endianness for the UBX
* protocol.
*
* @param uint64 the uint64_t value to encode.
* @return the encoded uint64_t value.
*/
uint64_t uUbxProtocolUint64Encode(uint64_t uint64);
/** Encode a UBX protocol message.
*
* @param messageClass the UBX protocol message class.
* @param messageId the UBX protocol message ID.
* @param[in] pMessageBody the message body to be encoded,
* may be NULL if the message has no
* body.
* @param messageBodyLengthBytes the length of the message body,
* must non-zero if pMessage is not
* NULL.
* @param[out] pBuffer a buffer in which the encoded
* message is to be stored; at least
* messageLengthBytes +
* #U_UBX_PROTOCOL_OVERHEAD_LENGTH_BYTES
* must be allowed.
* @return on success the number of bytes written
* to pBuffer, else negative error code.
*/
int32_t uUbxProtocolEncode(int32_t messageClass, int32_t messageId,
const char *pMessageBody, size_t messageBodyLengthBytes,
char *pBuffer);
/** Decode a UBX protocol message. Call this function with a buffer
* and it will return the first valid UBX format message it finds
* in the buffer. ppBufferOut will be set to the first position in
* the buffer after any message is found, or will point one byte
* beyond the end of the buffer if no message or a partial message
* is found. Hence a good pattern for use of this function could be:
*
* ```
* const char *pBufferStart = &(dataIn[0]);
* size_t bufferLength = sizeof(dataIn);
* const char *pBufferEnd = pBufferStart;
* int32_t messageClass;
* int32_t messageId;
* char messageBody[128];
*
* for (int32_t x = uUbxProtocolDecode(pBufferStart, bufferLength,
* &messageClass, &messageId,
* messageBody, sizeof(messageBody),
* &pBufferEnd);
* x > 0;
* x = uUbxProtocolDecode(pBufferStart, bufferLength,
* &messageClass, &messageId,
* messageBody, sizeof(messageBody),
* &pBufferEnd)) {
* printf("Message class 0x%02x, message ID 0x%02x, "
* " message body length %d byte(s).\n", messageClass,
* messageId, x);
* if (x > sizeof(messageBody)) {
* printf("Warning: message body is larger than storage"
* " buffer (only %d bytes).\n", sizeof(messageBody));
* x = sizeof(messageBody);
* }
*
* // Handle the message here
*
* bufferLength -= pBufferEnd - pBufferStart;
* pBufferStart = pBufferEnd;
* }
* ```
*
* @param[in] pBufferIn a pointer to the message buffer to
* decode.
* @param bufferLengthBytes the amount of data at pBufferIn.
* @param[out] pMessageClass a pointer to somewhere to store the
* decoded UBX message class; may be NULL.
* @param[out] pMessageId a pointer to somewher to store the
* decoded UBX message ID; may be NULL.
* @param[out] pMessageBody a pointer to somewhere to store
* the decoded message body; it is safe
* to decode back into pBufferIn if you
* don't mind over-writing the message.
* May be NULL.
* @param maxMessageBodyLengthBytes the amount of storage at pMessageBody.
* @param[out] ppBufferOut a pointer to somewhere to store the
* buffer pointer after message decoding
* has been completed; may be NULL;
* @return on success the number of message body
* bytes decoded, else negative error
* code. If pMessageBody is NULL then
* the number of bytes that would have
* been decoded is returned, hence
* allowing the potential size of a
* decoded message to be determined in
* order to make a subsequent call with
* exactly the right buffer size or
* destination. Note that the
* return value may be larger than
* maxMessageBodyLengthBytes, though only
* a maximum of maxMessageBodyLengthBytes
* will be written to pMessageBody. If
* pBufferIn contains a partial message
* #U_ERROR_COMMON_TIMEOUT will be returned.
*/
int32_t uUbxProtocolDecode(const char *pBufferIn, size_t bufferLengthBytes,
int32_t *pMessageClass, int32_t *pMessageId,
char *pMessageBody, size_t maxMessageBodyLengthBytes,
const char **ppBufferOut);
#ifdef __cplusplus
}
#endif
/** @}*/
#endif // _U_UBX_PROTOCOL_H_
// End of file