WPILibC++ 2025.3.1
Loading...
Searching...
No Matches
I2C.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#include <hal/I2C.h>
10#include <hal/I2CTypes.h>
11
12namespace frc {
13
14/**
15 * I2C bus interface class.
16 *
17 * This class is intended to be used by sensor (and other I2C device) drivers.
18 * It probably should not be used directly.
19 *
20 * The Onboard I2C port is subject to system lockups. See <a
21 * href="https://docs.wpilib.org/en/stable/docs/yearly-overview/known-issues.html#onboard-i2c-causing-system-lockups">
22 * WPILib Known Issues</a> page for details.
23 */
24class I2C {
25 public:
26 /**
27 * I2C connection ports.
28 */
29 enum Port {
30 /// Onboard I2C port.
32 /// MXP (roboRIO MXP) I2C port.
33 kMXP
34 };
35
36 /**
37 * Constructor.
38 *
39 * @param port The I2C port to which the device is connected.
40 * @param deviceAddress The address of the device on the I2C bus.
41 */
42 I2C(Port port, int deviceAddress);
43
44 I2C(I2C&&) = default;
45 I2C& operator=(I2C&&) = default;
46
47 /**
48 * Returns I2C port.
49 *
50 * @return I2C port.
51 */
52 Port GetPort() const;
53
54 /**
55 * Returns I2C device address.
56 *
57 * @return I2C device address.
58 */
59 int GetDeviceAddress() const;
60
61 /**
62 * Generic transaction.
63 *
64 * This is a lower-level interface to the I2C hardware giving you more control
65 * over each transaction. If you intend to write multiple bytes in the same
66 * transaction and do not plan to receive anything back, use writeBulk()
67 * instead. Calling this with a receiveSize of 0 will result in an error.
68 *
69 * @param dataToSend Buffer of data to send as part of the transaction.
70 * @param sendSize Number of bytes to send as part of the transaction.
71 * @param dataReceived Buffer to read data into.
72 * @param receiveSize Number of bytes to read from the device.
73 * @return Transfer Aborted... false for success, true for aborted.
74 */
75 bool Transaction(uint8_t* dataToSend, int sendSize, uint8_t* dataReceived,
76 int receiveSize);
77
78 /**
79 * Attempt to address a device on the I2C bus.
80 *
81 * This allows you to figure out if there is a device on the I2C bus that
82 * responds to the address specified in the constructor.
83 *
84 * @return Transfer Aborted... false for success, true for aborted.
85 */
87
88 /**
89 * Execute a write transaction with the device.
90 *
91 * Write a single byte to a register on a device and wait until the
92 * transaction is complete.
93 *
94 * @param registerAddress The address of the register on the device to be
95 * written.
96 * @param data The byte to write to the register on the device.
97 * @return Transfer Aborted... false for success, true for aborted.
98 */
99 bool Write(int registerAddress, uint8_t data);
100
101 /**
102 * Execute a bulk write transaction with the device.
103 *
104 * Write multiple bytes to a device and wait until the
105 * transaction is complete.
106 *
107 * @param data The data to write to the register on the device.
108 * @param count The number of bytes to be written.
109 * @return Transfer Aborted... false for success, true for aborted.
110 */
111 bool WriteBulk(uint8_t* data, int count);
112
113 /**
114 * Execute a read transaction with the device.
115 *
116 * Read bytes from a device.
117 * Most I2C devices will auto-increment the register pointer internally
118 * allowing you to read consecutive registers on a device in a single
119 * transaction.
120 *
121 * @param registerAddress The register to read first in the transaction.
122 * @param count The number of bytes to read in the transaction.
123 * @param data A pointer to the array of bytes to store the data
124 * read from the device.
125 * @return Transfer Aborted... false for success, true for aborted.
126 */
127 bool Read(int registerAddress, int count, uint8_t* data);
128
129 /**
130 * Execute a read only transaction with the device.
131 *
132 * Read bytes from a device. This method does not write any data to prompt the
133 * device.
134 *
135 * @param buffer A pointer to the array of bytes to store the data read from
136 * the device.
137 * @param count The number of bytes to read in the transaction.
138 * @return Transfer Aborted... false for success, true for aborted.
139 */
140 bool ReadOnly(int count, uint8_t* buffer);
141
142 /**
143 * Verify that a device's registers contain expected values.
144 *
145 * Most devices will have a set of registers that contain a known value that
146 * can be used to identify them. This allows an I2C device driver to easily
147 * verify that the device contains the expected value.
148 *
149 * @pre The device must support and be configured to use register
150 * auto-increment.
151 *
152 * @param registerAddress The base register to start reading from the device.
153 * @param count The size of the field to be verified.
154 * @param expected A buffer containing the values expected from the
155 * device.
156 */
157 bool VerifySensor(int registerAddress, int count, const uint8_t* expected);
158
159 private:
161 int m_deviceAddress;
162};
163
164} // namespace frc
I2C bus interface class.
Definition I2C.h:24
I2C(I2C &&)=default
I2C(Port port, int deviceAddress)
Constructor.
bool Read(int registerAddress, int count, uint8_t *data)
Execute a read transaction with the device.
bool ReadOnly(int count, uint8_t *buffer)
Execute a read only transaction with the device.
bool Transaction(uint8_t *dataToSend, int sendSize, uint8_t *dataReceived, int receiveSize)
Generic transaction.
bool Write(int registerAddress, uint8_t data)
Execute a write transaction with the device.
I2C & operator=(I2C &&)=default
bool WriteBulk(uint8_t *data, int count)
Execute a bulk write transaction with the device.
bool VerifySensor(int registerAddress, int count, const uint8_t *expected)
Verify that a device's registers contain expected values.
int GetDeviceAddress() const
Returns I2C device address.
Port GetPort() const
Returns I2C port.
bool AddressOnly()
Attempt to address a device on the I2C bus.
Port
I2C connection ports.
Definition I2C.h:29
@ kOnboard
Onboard I2C port.
Definition I2C.h:31
@ kMXP
MXP (roboRIO MXP) I2C port.
Definition I2C.h:33
A move-only C++ wrapper around a HAL handle.
Definition Types.h:96
Definition CAN.h:11