1 // SPDX-License-Identifier: GPL-2.0-or-later 2 /* 3 * PING: ultrasonic sensor for distance measuring by using only one GPIOs 4 * 5 * Copyright (c) 2019 Andreas Klinger <ak@it-klinger.de> 6 * 7 * For details about the devices see: 8 * http://parallax.com/sites/default/files/downloads/28041-LaserPING-2m-Rangefinder-Guide.pdf 9 * http://parallax.com/sites/default/files/downloads/28015-PING-Documentation-v1.6.pdf 10 * 11 * the measurement cycle as timing diagram looks like: 12 * 13 * GPIO ___ ________________________ 14 * ping: __/ \____________/ \________________ 15 * ^ ^ ^ ^ 16 * |<->| interrupt interrupt 17 * udelay(5) (ts_rising) (ts_falling) 18 * |<---------------------->| 19 * . pulse time measured . 20 * . --> one round trip of ultra sonic waves 21 * ultra . . 22 * sonic _ _ _. . 23 * burst: _________/ \_/ \_/ \_________________________________________ 24 * . 25 * ultra . 26 * sonic _ _ _. 27 * echo: __________________________________/ \_/ \_/ \________________ 28 */ 29 #include <linux/err.h> 30 #include <linux/gpio/consumer.h> 31 #include <linux/kernel.h> 32 #include <linux/module.h> 33 #include <linux/of.h> 34 #include <linux/of_device.h> 35 #include <linux/platform_device.h> 36 #include <linux/property.h> 37 #include <linux/sched.h> 38 #include <linux/interrupt.h> 39 #include <linux/delay.h> 40 #include <linux/iio/iio.h> 41 #include <linux/iio/sysfs.h> 42 43 struct ping_cfg { 44 unsigned long trigger_pulse_us; /* length of trigger pulse */ 45 int laserping_error; /* support error code in */ 46 /* pulse width of laser */ 47 /* ping sensors */ 48 s64 timeout_ns; /* timeout in ns */ 49 }; 50 51 struct ping_data { 52 struct device *dev; 53 struct gpio_desc *gpiod_ping; 54 struct mutex lock; 55 int irqnr; 56 ktime_t ts_rising; 57 ktime_t ts_falling; 58 struct completion rising; 59 struct completion falling; 60 const struct ping_cfg *cfg; 61 }; 62 63 static const struct ping_cfg pa_ping_cfg = { 64 .trigger_pulse_us = 5, 65 .laserping_error = 0, 66 .timeout_ns = 18500000, /* 3 meters */ 67 }; 68 69 static const struct ping_cfg pa_laser_ping_cfg = { 70 .trigger_pulse_us = 5, 71 .laserping_error = 1, 72 .timeout_ns = 15500000, /* 2 meters plus error codes */ 73 }; 74 75 static irqreturn_t ping_handle_irq(int irq, void *dev_id) 76 { 77 struct iio_dev *indio_dev = dev_id; 78 struct ping_data *data = iio_priv(indio_dev); 79 ktime_t now = ktime_get(); 80 81 if (gpiod_get_value(data->gpiod_ping)) { 82 data->ts_rising = now; 83 complete(&data->rising); 84 } else { 85 data->ts_falling = now; 86 complete(&data->falling); 87 } 88 89 return IRQ_HANDLED; 90 } 91 92 static int ping_read(struct iio_dev *indio_dev) 93 { 94 struct ping_data *data = iio_priv(indio_dev); 95 int ret; 96 ktime_t ktime_dt; 97 s64 dt_ns; 98 u32 time_ns, distance_mm; 99 struct platform_device *pdev = to_platform_device(data->dev); 100 101 /* 102 * just one read-echo-cycle can take place at a time 103 * ==> lock against concurrent reading calls 104 */ 105 mutex_lock(&data->lock); 106 107 reinit_completion(&data->rising); 108 reinit_completion(&data->falling); 109 110 gpiod_set_value(data->gpiod_ping, 1); 111 udelay(data->cfg->trigger_pulse_us); 112 gpiod_set_value(data->gpiod_ping, 0); 113 114 ret = gpiod_direction_input(data->gpiod_ping); 115 if (ret < 0) { 116 mutex_unlock(&data->lock); 117 return ret; 118 } 119 120 data->irqnr = gpiod_to_irq(data->gpiod_ping); 121 if (data->irqnr < 0) { 122 dev_err(data->dev, "gpiod_to_irq: %d\n", data->irqnr); 123 mutex_unlock(&data->lock); 124 return data->irqnr; 125 } 126 127 ret = request_irq(data->irqnr, ping_handle_irq, 128 IRQF_TRIGGER_RISING | IRQF_TRIGGER_FALLING, 129 pdev->name, indio_dev); 130 if (ret < 0) { 131 dev_err(data->dev, "request_irq: %d\n", ret); 132 mutex_unlock(&data->lock); 133 return ret; 134 } 135 136 /* it should not take more than 20 ms until echo is rising */ 137 ret = wait_for_completion_killable_timeout(&data->rising, HZ/50); 138 if (ret < 0) 139 goto err_reset_direction; 140 else if (ret == 0) { 141 ret = -ETIMEDOUT; 142 goto err_reset_direction; 143 } 144 145 /* it cannot take more than 50 ms until echo is falling */ 146 ret = wait_for_completion_killable_timeout(&data->falling, HZ/20); 147 if (ret < 0) 148 goto err_reset_direction; 149 else if (ret == 0) { 150 ret = -ETIMEDOUT; 151 goto err_reset_direction; 152 } 153 154 ktime_dt = ktime_sub(data->ts_falling, data->ts_rising); 155 156 free_irq(data->irqnr, indio_dev); 157 158 ret = gpiod_direction_output(data->gpiod_ping, GPIOD_OUT_LOW); 159 if (ret < 0) { 160 mutex_unlock(&data->lock); 161 return ret; 162 } 163 164 mutex_unlock(&data->lock); 165 166 dt_ns = ktime_to_ns(ktime_dt); 167 if (dt_ns > data->cfg->timeout_ns) { 168 dev_dbg(data->dev, "distance out of range: dt=%lldns\n", 169 dt_ns); 170 return -EIO; 171 } 172 173 time_ns = dt_ns; 174 175 /* 176 * read error code of laser ping sensor and give users chance to 177 * figure out error by using dynamic debuggging 178 */ 179 if (data->cfg->laserping_error) { 180 if ((time_ns > 12500000) && (time_ns <= 13500000)) { 181 dev_dbg(data->dev, "target too close or to far\n"); 182 return -EIO; 183 } 184 if ((time_ns > 13500000) && (time_ns <= 14500000)) { 185 dev_dbg(data->dev, "internal sensor error\n"); 186 return -EIO; 187 } 188 if ((time_ns > 14500000) && (time_ns <= 15500000)) { 189 dev_dbg(data->dev, "internal sensor timeout\n"); 190 return -EIO; 191 } 192 } 193 194 /* 195 * the speed as function of the temperature is approximately: 196 * 197 * speed = 331,5 + 0,6 * Temp 198 * with Temp in °C 199 * and speed in m/s 200 * 201 * use 343,5 m/s as ultrasonic speed at 20 °C here in absence of the 202 * temperature 203 * 204 * therefore: 205 * time 343,5 time * 232 206 * distance = ------ * ------- = ------------ 207 * 10^6 2 1350800 208 * with time in ns 209 * and distance in mm (one way) 210 * 211 * because we limit to 3 meters the multiplication with 232 just 212 * fits into 32 bit 213 */ 214 distance_mm = time_ns * 232 / 1350800; 215 216 return distance_mm; 217 218 err_reset_direction: 219 free_irq(data->irqnr, indio_dev); 220 mutex_unlock(&data->lock); 221 222 if (gpiod_direction_output(data->gpiod_ping, GPIOD_OUT_LOW)) 223 dev_dbg(data->dev, "error in gpiod_direction_output\n"); 224 return ret; 225 } 226 227 static int ping_read_raw(struct iio_dev *indio_dev, 228 struct iio_chan_spec const *channel, int *val, 229 int *val2, long info) 230 { 231 int ret; 232 233 if (channel->type != IIO_DISTANCE) 234 return -EINVAL; 235 236 switch (info) { 237 case IIO_CHAN_INFO_RAW: 238 ret = ping_read(indio_dev); 239 if (ret < 0) 240 return ret; 241 *val = ret; 242 return IIO_VAL_INT; 243 case IIO_CHAN_INFO_SCALE: 244 /* 245 * maximum resolution in datasheet is 1 mm 246 * 1 LSB is 1 mm 247 */ 248 *val = 0; 249 *val2 = 1000; 250 return IIO_VAL_INT_PLUS_MICRO; 251 default: 252 return -EINVAL; 253 } 254 } 255 256 static const struct iio_info ping_iio_info = { 257 .read_raw = ping_read_raw, 258 }; 259 260 static const struct iio_chan_spec ping_chan_spec[] = { 261 { 262 .type = IIO_DISTANCE, 263 .info_mask_separate = 264 BIT(IIO_CHAN_INFO_RAW) | 265 BIT(IIO_CHAN_INFO_SCALE), 266 }, 267 }; 268 269 static const struct of_device_id of_ping_match[] = { 270 { .compatible = "parallax,ping", .data = &pa_ping_cfg}, 271 { .compatible = "parallax,laserping", .data = &pa_laser_ping_cfg}, 272 {}, 273 }; 274 275 MODULE_DEVICE_TABLE(of, of_ping_match); 276 277 static int ping_probe(struct platform_device *pdev) 278 { 279 struct device *dev = &pdev->dev; 280 struct ping_data *data; 281 struct iio_dev *indio_dev; 282 283 indio_dev = devm_iio_device_alloc(dev, sizeof(struct ping_data)); 284 if (!indio_dev) { 285 dev_err(dev, "failed to allocate IIO device\n"); 286 return -ENOMEM; 287 } 288 289 data = iio_priv(indio_dev); 290 data->dev = dev; 291 data->cfg = of_device_get_match_data(dev); 292 293 mutex_init(&data->lock); 294 init_completion(&data->rising); 295 init_completion(&data->falling); 296 297 data->gpiod_ping = devm_gpiod_get(dev, "ping", GPIOD_OUT_LOW); 298 if (IS_ERR(data->gpiod_ping)) { 299 dev_err(dev, "failed to get ping-gpios: err=%ld\n", 300 PTR_ERR(data->gpiod_ping)); 301 return PTR_ERR(data->gpiod_ping); 302 } 303 304 if (gpiod_cansleep(data->gpiod_ping)) { 305 dev_err(data->dev, "cansleep-GPIOs not supported\n"); 306 return -ENODEV; 307 } 308 309 platform_set_drvdata(pdev, indio_dev); 310 311 indio_dev->name = "ping"; 312 indio_dev->info = &ping_iio_info; 313 indio_dev->modes = INDIO_DIRECT_MODE; 314 indio_dev->channels = ping_chan_spec; 315 indio_dev->num_channels = ARRAY_SIZE(ping_chan_spec); 316 317 return devm_iio_device_register(dev, indio_dev); 318 } 319 320 static struct platform_driver ping_driver = { 321 .probe = ping_probe, 322 .driver = { 323 .name = "ping-gpio", 324 .of_match_table = of_ping_match, 325 }, 326 }; 327 328 module_platform_driver(ping_driver); 329 330 MODULE_AUTHOR("Andreas Klinger <ak@it-klinger.de>"); 331 MODULE_DESCRIPTION("PING sensors for distance measuring using one GPIOs"); 332 MODULE_LICENSE("GPL"); 333 MODULE_ALIAS("platform:ping"); 334