Line data Source code
1 1 : /*
2 : * Copyright (c) 2024 Cirrus Logic, Inc.
3 : * SPDX-License-Identifier: Apache-2.0
4 : */
5 :
6 : /**
7 : * @file
8 : * @brief Header file providing the API for the DRV2605 haptic driver
9 : * @ingroup drv2605_interface
10 : */
11 :
12 : #ifndef ZEPHYR_INCLUDE_DRIVERS_HAPTICS_DRV2605_H_
13 : #define ZEPHYR_INCLUDE_DRIVERS_HAPTICS_DRV2605_H_
14 :
15 : #include <zephyr/drivers/haptics.h>
16 : #include <zephyr/types.h>
17 :
18 : #ifdef __cplusplus
19 : extern "C" {
20 : #endif
21 :
22 : /**
23 : * @defgroup drv2605_interface DRV2605
24 : * @ingroup haptics_interface_ext
25 : * @brief DRV2605 Haptic Driver for ERM and LRA
26 : * @{
27 : */
28 :
29 : /**
30 : * @name Helpers
31 : * @{
32 : */
33 :
34 : /** Maximum number of waveforms that can be stored in the sequencer */
35 1 : #define DRV2605_WAVEFORM_SEQUENCER_MAX 8
36 :
37 : /**
38 : * @brief Creates a wait/delay value for the waveform sequencer.
39 : *
40 : * @details This macro generates a byte value that, when placed in the drv2605_rom_data::seq_regs
41 : * array, instructs the DRV2605 playback engine to idle for a specified duration.
42 : *
43 : * @param ms The desired delay in milliseconds (rounded down to the nearest 10ms). Valid range is
44 : * 10 to 1270.
45 : * @return A byte literal representing the wait time for the sequencer.
46 : */
47 1 : #define DRV2605_WAVEFORM_SEQUENCER_WAIT_MS(ms) (0x80 | ((ms) / 10))
48 :
49 : /** @} */
50 :
51 : /**
52 : * @brief Effect libraries
53 : *
54 : * This enumeration defines the different effect libraries that can be used with the DRV2605 when
55 : * using ROM source. TouchSense 2220 libraries are for open-loop ERM motors,
56 : * @ref DRV2605_LIBRARY_LRA is to be used for closed-loop LRA motors.
57 : */
58 1 : enum drv2605_library {
59 : DRV2605_LIBRARY_EMPTY = 0, /**< Empty library */
60 : DRV2605_LIBRARY_TS2200_A, /**< TouchSense 2220 A library */
61 : DRV2605_LIBRARY_TS2200_B, /**< TouchSense 2220 B library */
62 : DRV2605_LIBRARY_TS2200_C, /**< TouchSense 2220 C library */
63 : DRV2605_LIBRARY_TS2200_D, /**< TouchSense 2220 D library */
64 : DRV2605_LIBRARY_TS2200_E, /**< TouchSense 2220 E library */
65 : DRV2605_LIBRARY_LRA, /**< Linear Resonance Actuator (LRA) library */
66 : };
67 :
68 : /**
69 : * @brief Modes of operation
70 : *
71 : * @details This enumeration defines the different modes of operation supported by the DRV2605.
72 : *
73 : * See Table 5 of the DRV2605 datasheet for more information on the various operation modes.
74 : */
75 1 : enum drv2605_mode {
76 : DRV2605_MODE_INTERNAL_TRIGGER = 0, /**< Internal trigger mode */
77 : DRV2605_MODE_EXTERNAL_EDGE_TRIGGER, /**< External trigger mode (edge) */
78 : DRV2605_MODE_EXTERNAL_LEVEL_TRIGGER, /**< External trigger mode (level) */
79 : DRV2605_MODE_PWM_ANALOG_INPUT, /**< PWM or Analog input mode */
80 : DRV2605_MODE_AUDIO_TO_VIBE, /**< Audio-to-vibe mode */
81 : DRV2605_MODE_RTP, /**< RTP mode */
82 : DRV2605_MODE_DIAGNOSTICS, /**< Diagnostics mode */
83 : DRV2605_MODE_AUTO_CAL, /**< Auto-calibration mode */
84 : };
85 :
86 : /**
87 : * @brief Types of haptic signal sources.
88 : *
89 : * @details This enumeration defines the different types of haptic signal sources supported by the
90 : * DRV2605.
91 : */
92 1 : enum drv2605_haptics_source {
93 : DRV2605_HAPTICS_SOURCE_ROM, /**< Playback from the pre-programmed ROM library. */
94 : DRV2605_HAPTICS_SOURCE_RTP, /**< Playback from Real-Time Playback (RTP) data stream. */
95 : DRV2605_HAPTICS_SOURCE_AUDIO, /**< Playback is generated from an audio signal. */
96 : DRV2605_HAPTICS_SOURCE_PWM, /**< Playback is driven by an external PWM signal. */
97 : DRV2605_HAPTICS_SOURCE_ANALOG, /**< Playback is driven by an external analog signal. */
98 : };
99 :
100 : /**
101 : * @brief ROM data configuration
102 : *
103 : * @details This structure contains configuration data for when the DRV2605 is using the internal
104 : * ROM as the haptic source (@ref DRV2605_HAPTICS_SOURCE_ROM).
105 : */
106 1 : struct drv2605_rom_data {
107 : /** Mode of operation for triggering the ROM effects. */
108 1 : enum drv2605_mode trigger;
109 : /** Effect library to use for playback. */
110 1 : enum drv2605_library library;
111 : /**
112 : * @brief Waveform sequencer contents.
113 : *
114 : * This array contains the register values for the sequencer registers (0x04 to 0x0B).
115 : * Each byte can describe either:
116 : * - A waveform identifier (1 to 123) from the selected library to be played.
117 : * - A wait time, if the MSB is set. The lower 7 bits are a multiple of 10 ms.
118 : * Playback stops at the first zero entry.
119 : *
120 : * See Table 8 of the DRV2605 datasheet.
121 : */
122 1 : uint8_t seq_regs[DRV2605_WAVEFORM_SEQUENCER_MAX];
123 : /**
124 : * @brief Overdrive time offset.
125 : *
126 : * A signed 8-bit value that adds a time offset to the overdrive portion of the waveform.
127 : * The offset is `overdrive_time * 5 ms`.
128 : *
129 : * See Table 10 of the DRV2605 datasheet.
130 : */
131 1 : uint8_t overdrive_time;
132 : /**
133 : * @brief Sustain positive time offset.
134 : *
135 : * A signed 8-bit value that adds a time offset to the positive sustain portion of the
136 : * waveform. The offset is `sustain_pos_time * 5 ms`.
137 : *
138 : * See Table 11 of the DRV2605 datasheet.
139 : */
140 1 : uint8_t sustain_pos_time;
141 : /**
142 : * @brief Sustain negative time offset.
143 : *
144 : * A signed 8-bit value that adds a time offset to the negative sustain portion of the
145 : * waveform. The offset is `sustain_neg_time * 5 ms`.
146 : *
147 : * See Table 12 of the DRV2605 datasheet.
148 : */
149 1 : uint8_t sustain_neg_time;
150 : /**
151 : * @brief Brake time offset.
152 : *
153 : * A signed 8-bit value that adds a time offset to the braking portion of the waveform.
154 : * The offset is `brake_time * 5 ms`.
155 : *
156 : * See Table 13 of the DRV2605 datasheet.
157 : */
158 1 : uint8_t brake_time;
159 : };
160 :
161 : /**
162 : * @brief Real-Time Playback (RTP) data configuration.
163 : *
164 : * @details This structure contains configuration data for when the DRV2605 is in RTP mode
165 : * (@ref DRV2605_HAPTICS_SOURCE_RTP). It allows for streaming custom haptic waveforms.
166 : */
167 1 : struct drv2605_rtp_data {
168 : /** The number of entries in the @ref rtp_hold_us and @ref rtp_input arrays. */
169 1 : size_t size;
170 : /**
171 : * @brief Pointer to an array of hold times.
172 : *
173 : * Each value specifies the duration in microseconds to hold the corresponding
174 : * amplitude from the `rtp_input` array.
175 : */
176 1 : uint32_t *rtp_hold_us;
177 : /**
178 : * @brief Pointer to an array of RTP amplitude values.
179 : *
180 : * Each value is an 8-bit amplitude that will be written to the RTP input register (0x02).
181 : * These values can be signed or unsigned depending on device configuration.
182 : */
183 1 : uint8_t *rtp_input;
184 : };
185 :
186 : /**
187 : * @brief Configuration data union.
188 : *
189 : * @details This union holds a pointer to the specific configuration data struct required
190 : * for the selected haptic source. The correct member must be populated before calling
191 : * drv2605_haptic_config().
192 : */
193 1 : union drv2605_config_data {
194 : /** Pointer to ROM configuration data. Use when source is @ref DRV2605_HAPTICS_SOURCE_ROM */
195 1 : struct drv2605_rom_data *rom_data;
196 : /** Pointer to RTP configuration data. Use when source is @ref DRV2605_HAPTICS_SOURCE_RTP */
197 1 : struct drv2605_rtp_data *rtp_data;
198 : };
199 :
200 : /**
201 : * @brief Configure the DRV2605 device for a particular signal source
202 : *
203 : * @param dev Pointer to the device structure for haptic device instance
204 : * @param source The type of haptic signal source desired
205 : * @param config_data Pointer to the configuration data union for the source
206 : *
207 : * @retval 0 success
208 : * @retval -ENOTSUP signal source not supported
209 : * @retval -errno another negative error code on failure
210 : */
211 1 : int drv2605_haptic_config(const struct device *dev, enum drv2605_haptics_source source,
212 : const union drv2605_config_data *config_data);
213 :
214 :
215 : /** @} */
216 :
217 : #ifdef __cplusplus
218 : }
219 : #endif /* __cplusplus */
220 :
221 : #endif
|
