WPILibC++ 2024.3.2
HALBase.h
Go to the documentation of this file.
1// Copyright (c) FIRST and other WPILib contributors.
2// Open Source Software; you can modify and/or share it under the terms of
3// the WPILib BSD license file in the root directory of this project.
4
5#pragma once
6
7#include <stdint.h>
8
9#ifdef __cplusplus
10#include <cstddef>
11#else
12
13#include <stddef.h> // NOLINT(build/include_order)
14
15#endif
16
17#include "hal/Types.h"
18
19/**
20 * @defgroup hal_capi WPILib HAL API
21 * Hardware Abstraction Layer (HAL) to hardware or simulator
22 * @{
23 */
24
29};
30
31#ifdef __cplusplus
32extern "C" {
33#endif
34
35/**
36 * Gets the last error set on this thread, or the message for the status code.
37 *
38 * If passed HAL_USE_LAST_ERROR, the last error set on the thread will be
39 * returned.
40 *
41 * @param[out] status the status code, set to the error status code if input is
42 * HAL_USE_LAST_ERROR
43 * @return the error message for the code. This does not need to be freed,
44 * but can be overwritten by another hal call on the same thread.
45 */
46const char* HAL_GetLastError(int32_t* status);
47
48/**
49 * Gets the error message for a specific status code.
50 *
51 * @param code the status code
52 * @return the error message for the code. This does not need to be freed.
53 */
54const char* HAL_GetErrorMessage(int32_t code);
55
56/**
57 * Returns the FPGA Version number.
58 *
59 * For now, expect this to be competition year.
60 *
61 * @param[out] status the error code, or 0 for success
62 * @return FPGA Version number.
63 */
64int32_t HAL_GetFPGAVersion(int32_t* status);
65
66/**
67 * Returns the FPGA Revision number.
68 *
69 * The format of the revision is 3 numbers.
70 * The 12 most significant bits are the Major Revision.
71 * the next 8 bits are the Minor Revision.
72 * The 12 least significant bits are the Build Number.
73 *
74 * @param[out] status the error code, or 0 for success
75 * @return FPGA Revision number.
76 */
77int64_t HAL_GetFPGARevision(int32_t* status);
78
79/**
80 * Returns the roboRIO serial number.
81 *
82 * @param[out] buffer The roboRIO serial number.
83 * @param size The maximum characters to copy into buffer.
84 * @return Number of characters copied into buffer.
85 */
86size_t HAL_GetSerialNumber(char* buffer, size_t size);
87
88/**
89 * Returns the comments from the roboRIO web interface.
90 *
91 * @param[out] buffer The comments string.
92 * @param size The maximum characters to copy into buffer.
93 * @return Number of characters copied into buffer.
94 */
95size_t HAL_GetComments(char* buffer, size_t size);
96
97/**
98 * Returns the team number configured for the robot controller.
99 * @return team number, or 0 if not found.
100 */
101int32_t HAL_GetTeamNumber(void);
102
103/**
104 * Returns the runtime type of the HAL.
105 *
106 * @return HAL Runtime Type
107 */
109
110/**
111 * Gets the state of the "USER" button on the roboRIO.
112 *
113 * @warning the User Button is used to stop user programs from automatically
114 * loading if it is held for more then 5 seconds. Because of this, it's not
115 * recommended to be used by teams for any other purpose.
116 *
117 * @param[out] status the error code, or 0 for success
118 * @return true if the button is currently pressed down
119 */
121
122/**
123 * Gets if the system outputs are currently active.
124 *
125 * @param[out] status the error code, or 0 for success
126 * @return true if the system outputs are active, false if disabled
127 */
129
130/**
131 * Gets if the system is in a browned out state.
132 *
133 * @param[out] status the error code, or 0 for success
134 * @return true if the system is in a low voltage brown out, false otherwise
135 */
137
138/**
139 * Gets a port handle for a specific channel.
140 *
141 * The created handle does not need to be freed.
142 *
143 * @param channel the channel number
144 * @return the created port
145 */
147
148/**
149 * Gets a port handle for a specific channel and module.
150 *
151 * This is expected to be used for PCMs, as the roboRIO does not work with
152 * modules anymore.
153 *
154 * The created handle does not need to be freed.
155 *
156 * @param module the module number
157 * @param channel the channel number
158 * @return the created port
159 */
160HAL_PortHandle HAL_GetPortWithModule(int32_t module, int32_t channel);
161
162/**
163 * Reads the microsecond-resolution timer on the FPGA.
164 *
165 * @param[out] status the error code, or 0 for success
166 * @return The current time in microseconds according to the FPGA (since FPGA
167 * reset).
168 */
169uint64_t HAL_GetFPGATime(int32_t* status);
170
171/**
172 * Given an 32 bit FPGA time, expand it to the nearest likely 64 bit FPGA time.
173 *
174 * Note: This is making the assumption that the timestamp being converted is
175 * always in the past. If you call this with a future timestamp, it probably
176 * will make it in the past. If you wait over 70 minutes between capturing the
177 * bottom 32 bits of the timestamp and expanding it, you will be off by
178 * multiples of 1<<32 microseconds.
179 *
180 * @param[in] unexpandedLower 32 bit FPGA time
181 * @param[out] status the error code, or 0 for success
182 * @return The current time in microseconds according to the FPGA (since FPGA
183 * reset) as a 64 bit number.
184 */
185uint64_t HAL_ExpandFPGATime(uint32_t unexpandedLower, int32_t* status);
186
187/**
188 * Gets the current state of the Robot Signal Light (RSL).
189 *
190 * @param[out] status the error code, or 0 for success
191 * @return The current state of the RSL- true if on, false if off
192 */
193HAL_Bool HAL_GetRSLState(int32_t* status);
194
195/**
196 * Gets if the system time is valid.
197 *
198 * @param[out] status the error code, or 0 for success
199 * @return True if the system time is valid, false otherwise
200 */
202
203/**
204 * Call this to start up HAL. This is required for robot programs.
205 *
206 * This must be called before any other HAL functions. Failure to do so will
207 * result in undefined behavior, and likely segmentation faults. This means that
208 * any statically initialized variables in a program MUST call this function in
209 * their constructors if they want to use other HAL calls.
210 *
211 * The common parameters are 500 for timeout and 0 for mode.
212 *
213 * This function is safe to call from any thread, and as many times as you wish.
214 * It internally guards from any reentrancy.
215 *
216 * The applicable modes are:
217 * 0: Try to kill an existing HAL from another program, if not successful,
218 * error.
219 * 1: Force kill a HAL from another program.
220 * 2: Just warn if another hal exists and cannot be killed. Will likely result
221 * in undefined behavior.
222 *
223 * @param timeout the initialization timeout (ms)
224 * @param mode the initialization mode (see remarks)
225 * @return true if initialization was successful, otherwise false.
226 */
227HAL_Bool HAL_Initialize(int32_t timeout, int32_t mode);
228
229/**
230 * Call this to shut down HAL.
231 *
232 * This must be called at termination of the robot program to avoid potential
233 * segmentation faults with simulation extensions at exit.
234 */
235void HAL_Shutdown(void);
236
237/**
238 * Calls registered SimPeriodic "before" callbacks (only in simulation mode).
239 * This should be called prior to user code periodic simulation functions.
240 */
242
243/**
244 * Calls registered SimPeriodic "after" callbacks (only in simulation mode).
245 * This should be called after user code periodic simulation functions.
246 */
248
249#ifdef __cplusplus
250} // extern "C"
251#endif
252/** @} */
and restrictions which apply to each piece of software is included later in this file and or inside of the individual applicable source files The disclaimer of warranty in the WPILib license above applies to all code in and nothing in any of the other licenses gives permission to use the names of FIRST nor the names of the WPILib contributors to endorse or promote products derived from this software The following pieces of software have additional or alternate and or Google Inc All rights reserved Redistribution and use in source and binary with or without are permitted provided that the following conditions are this list of conditions and the following disclaimer *Redistributions in binary form must reproduce the above copyright this list of conditions and the following disclaimer in the documentation and or other materials provided with the distribution *Neither the name of Google Inc nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS AS IS AND ANY EXPRESS OR IMPLIED BUT NOT LIMITED THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR ANY OR CONSEQUENTIAL WHETHER IN STRICT OR EVEN IF ADVISED OF THE POSSIBILITY OF SUCH January AND DISTRIBUTION Definitions License shall mean the terms and conditions for and distribution as defined by Sections through of this document Licensor shall mean the copyright owner or entity authorized by the copyright owner that is granting the License Legal Entity shall mean the union of the acting entity and all other entities that control are controlled by or are under common control with that entity For the purposes of this definition control direct or to cause the direction or management of such whether by contract or including but not limited to software source code
Definition: ThirdPartyNotices.txt:110
@ HAL_ENUM
Definition: Value.h:14
int32_t HAL_GetTeamNumber(void)
Returns the team number configured for the robot controller.
HAL_PortHandle HAL_GetPort(int32_t channel)
Gets a port handle for a specific channel.
size_t HAL_GetSerialNumber(char *buffer, size_t size)
Returns the roboRIO serial number.
HAL_Bool HAL_GetFPGAButton(int32_t *status)
Gets the state of the "USER" button on the roboRIO.
const char * HAL_GetLastError(int32_t *status)
Gets the last error set on this thread, or the message for the status code.
HAL_Bool HAL_GetSystemActive(int32_t *status)
Gets if the system outputs are currently active.
HAL_RuntimeType
Definition: HALBase.h:25
uint64_t HAL_ExpandFPGATime(uint32_t unexpandedLower, int32_t *status)
Given an 32 bit FPGA time, expand it to the nearest likely 64 bit FPGA time.
const char * HAL_GetErrorMessage(int32_t code)
Gets the error message for a specific status code.
HAL_RuntimeType HAL_GetRuntimeType(void)
Returns the runtime type of the HAL.
uint64_t HAL_GetFPGATime(int32_t *status)
Reads the microsecond-resolution timer on the FPGA.
int64_t HAL_GetFPGARevision(int32_t *status)
Returns the FPGA Revision number.
int32_t HAL_GetFPGAVersion(int32_t *status)
Returns the FPGA Version number.
HAL_Bool HAL_GetBrownedOut(int32_t *status)
Gets if the system is in a browned out state.
HAL_Bool HAL_GetSystemTimeValid(int32_t *status)
Gets if the system time is valid.
size_t HAL_GetComments(char *buffer, size_t size)
Returns the comments from the roboRIO web interface.
HAL_Bool HAL_GetRSLState(int32_t *status)
Gets the current state of the Robot Signal Light (RSL).
HAL_Bool HAL_Initialize(int32_t timeout, int32_t mode)
Call this to start up HAL.
HAL_PortHandle HAL_GetPortWithModule(int32_t module, int32_t channel)
Gets a port handle for a specific channel and module.
void HAL_SimPeriodicAfter(void)
Calls registered SimPeriodic "after" callbacks (only in simulation mode).
void HAL_SimPeriodicBefore(void)
Calls registered SimPeriodic "before" callbacks (only in simulation mode).
void HAL_Shutdown(void)
Call this to shut down HAL.
@ HAL_Runtime_RoboRIO2
Definition: HALBase.h:27
@ HAL_Runtime_RoboRIO
Definition: HALBase.h:26
@ HAL_Runtime_Simulation
Definition: HALBase.h:28
int32_t HAL_Bool
Definition: Types.h:73
HAL_Handle HAL_PortHandle
Definition: Types.h:19