{"id":20989883,"url":"https://github.com/robtillaart/srf05","last_synced_at":"2025-05-14T18:32:18.111Z","repository":{"id":45243151,"uuid":"368482495","full_name":"RobTillaart/SRF05","owner":"RobTillaart","description":"Arduino library for SRF05 distance sensor","archived":false,"fork":false,"pushed_at":"2024-04-13T09:12:44.000Z","size":27,"stargazers_count":7,"open_issues_count":0,"forks_count":1,"subscribers_count":3,"default_branch":"master","last_synced_at":"2024-08-07T18:27:06.978Z","etag":null,"topics":["arduino","distance","pulse","sound"],"latest_commit_sha":null,"homepage":"","language":"C++","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/RobTillaart.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null},"funding":{"github":"RobTillaart","custom":"https://www.paypal.me/robtillaart"}},"created_at":"2021-05-18T10:03:32.000Z","updated_at":"2024-02-10T06:26:11.000Z","dependencies_parsed_at":"2024-04-13T10:27:35.929Z","dependency_job_id":null,"html_url":"https://github.com/RobTillaart/SRF05","commit_stats":null,"previous_names":[],"tags_count":8,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/RobTillaart%2FSRF05","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/RobTillaart%2FSRF05/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/RobTillaart%2FSRF05/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/RobTillaart%2FSRF05/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/RobTillaart","download_url":"https://codeload.github.com/RobTillaart/SRF05/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":225305753,"owners_count":17453441,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["arduino","distance","pulse","sound"],"created_at":"2024-11-19T06:26:35.509Z","updated_at":"2025-05-14T18:32:18.100Z","avatar_url":"https://github.com/RobTillaart.png","language":"C++","funding_links":["https://github.com/sponsors/RobTillaart","https://www.paypal.me/robtillaart"],"categories":[],"sub_categories":[],"readme":"\n[![Arduino CI](https://github.com/RobTillaart/SRF05/workflows/Arduino%20CI/badge.svg)](https://github.com/marketplace/actions/arduino_ci)\n[![Arduino-lint](https://github.com/RobTillaart/SRF05/actions/workflows/arduino-lint.yml/badge.svg)](https://github.com/RobTillaart/SRF05/actions/workflows/arduino-lint.yml)\n[![JSON check](https://github.com/RobTillaart/SRF05/actions/workflows/jsoncheck.yml/badge.svg)](https://github.com/RobTillaart/SRF05/actions/workflows/jsoncheck.yml)\n[![GitHub issues](https://img.shields.io/github/issues/RobTillaart/SRF05.svg)](https://github.com/RobTillaart/SRF05/issues)\n\n[![License: MIT](https://img.shields.io/badge/license-MIT-green.svg)](https://github.com/RobTillaart/SRF05/blob/master/LICENSE)\n[![GitHub release](https://img.shields.io/github/release/RobTillaart/SRF05.svg?maxAge=3600)](https://github.com/RobTillaart/SRF05/releases)\n[![PlatformIO Registry](https://badges.registry.platformio.org/packages/robtillaart/library/SRF05.svg)](https://registry.platformio.org/libraries/robtillaart/SRF05)\n\n\n# SRF05\n\nArduino library for the SRF05 distance sensor and compatibles.\n\n\n## Description\n\nThis library implements a API for a PING type of sensor.\nIt is expected to work for quite a range of them.\nTill version 0.2.0 of the library, it only supported the SRF04 compatibility mode which uses a\nseparate **TRIGGER** and **ECHO** pin.\n\nVersion 0.3.0 implements support for the SRF05 mode in which **TRIGGER** and **ECHO** are the same.\nOne need to connect the MODE pin to GND to select this mode in the device.\nNote that not all PING type of sensors will support the single pin mode.\nSee also Connection section below.\n\nAn important feature of this library is that it allows to adjust the speed of sound (SOS).\nReasons to use a different value for the speed of sound is that it varies depending on\ntemperature, humidity, composition of the air, air pressure, other type of gas, etc.\n\nDefault value for the speed of sound is set to **340 m/s**. (air, ~15°C, sea level pressure)\n\nSince the version 0.2.0 the library has an interpolation formula to calculate the speed of sound\ngiven a temperature and humidity.\n\nThe library has several ways to adjust / improve the quality of the measurements.\nE.g. by taking the average or the median of multiple readings, there will be less noise.\nThis can be set with the different mode commands.\n\nThe library allows to set a correction factor to compensate for the timing of\nthe **pulseIn()** function. This has in the end the same effect as changing the\nspeed of sound however it is technically more correct to keep the two separated.\n\n\n### Compatibles\n\n|  device     |  works  |  notes  |\n|:------------|:-------:|:--------|\n|  HC-SR04    |    Y    |  separate echo and trigger only.\n|  JSN-SR04T  |    Y    |  separate echo and trigger only.\n|  SRF04      |    Y    |  separate echo and trigger only.\n|             |         |\n|  SRF05      |    Y    |\n|  RCWL-1604  |    Y    |\n|  RCWL-1605  |    Y    |  has transducer / receiver combined.\n|  RCWL-1633  |    Y    |  single pin mode echo / trigger combined.\n|  RCWL-1670  |    Y    |  needs grove cable, warning check colours!\n|             |         |\n|  US-100     |    -    |  not tested yet\n\n\n### Effect temperature and humidity\n\nSeveral correction formulas for the speed of sound are available on the internet\nto adjust the speed for temperature (°C) and humidity (%RH).\n\n```\n// temperature in °C\nv = 331.3 + 0.606 * temperature (m/s)\nv = 331.4 + 0.606 * temperature + 0.0124 * rel_humidity (m/s)\nv = 20.05 * sqrt(273.16 + temperature) (m/s)\n```\n\nIn fact humidity has an effect which increases with temperature so the formula is more complex.\nSee discussion - https://forum.arduino.cc/t/ultrasonic-sensor-to-determine-water-level/64890/12\n\nNote that the speed of sound is also altered by air pressure (sea level .. high in sky)\nand wind speed. The latter is a bit compensated for, as the acoustic pulse will go one time\n\"against\" the wind and one time \"with\" the wind.\n\n\n### Table speed of sound for temperature and humidity in air at sea level.\n\n(table redone completely in 0.2.0)\n\nTemperature in Celsius, Humidity in %, constant pressure == 1013 mBar, SOS in m/s.\n\n| temp |    0%  |   10%  |   20%  |   30%  |   40%  |   50%  |   60%  |   70%  |   80%  |   90%  |  100%  |\n|:----:|:------:|:------:|:------:|:------:|:------:|:------:|:------:|:------:|:------:|:------:|:------:|\n| -40  | 306.22 | 306.23 | 306.24 | 306.25 | 306.26 | 306.26 | 306.27 | 306.28 | 306.29 | 306.30 | 306.31 |\n| -35  | 309.49 | 309.50 | 309.50 | 309.51 | 309.52 | 309.52 | 309.53 | 309.54 | 309.54 | 309.55 | 309.56 |\n| -30  | 312.72 | 312.73 | 312.73 | 312.74 | 312.74 | 312.75 | 312.75 | 312.76 | 312.76 | 312.77 | 312.78 |\n| -25  | 315.92 | 315.93 | 315.93 | 315.94 | 315.94 | 315.95 | 315.95 | 315.96 | 315.96 | 315.97 | 315.98 |\n| -20  | 319.09 | 319.10 | 319.10 | 319.11 | 319.12 | 319.12 | 319.13 | 319.14 | 319.14 | 319.15 | 319.16 |\n| -15  | 322.22 | 322.23 | 322.24 | 322.25 | 322.26 | 322.27 | 322.28 | 322.29 | 322.30 | 322.31 | 322.32 |\n| -10  | 325.33 | 325.34 | 325.36 | 325.37 | 325.39 | 325.40 | 325.42 | 325.43 | 325.45 | 325.46 | 325.47 |\n|  -5  | 328.40 | 328.42 | 328.44 | 328.47 | 328.49 | 328.51 | 328.53 | 328.56 | 328.58 | 328.60 | 328.62 |\n|   0  | 331.45 | 331.48 | 331.51 | 331.54 | 331.57 | 331.61 | 331.64 | 331.67 | 331.70 | 331.73 | 331.76 |\n|   5  | 334.47 | 334.52 | 334.56 | 334.61 | 334.65 | 334.70 | 334.74 | 334.79 | 334.83 | 334.88 | 334.93 |\n|  10  | 337.46 | 337.52 | 337.58 | 337.64 | 337.70 | 337.76 | 337.82 | 337.88 | 337.94 | 338.00 | 338.06 |\n|  15  | 340.43 | 340.52 | 340.61 | 340.70 | 340.79 | 340.88 | 340.97 | 341.06 | 341.15 | 341.24 | 341.33 |\n|  20  | 343.37 | 343.49 | 343.62 | 343.74 | 343.87 | 343.99 | 344.12 | 344.24 | 344.37 | 344.49 | 344.61 |\n|  25  | 346.29 | 346.46 | 346.63 | 346.80 | 346.97 | 347.14 | 347.31 | 347.48 | 347.65 | 347.82 | 347.99 |\n|  30  | 349.18 | 349.41 | 349.64 | 349.87 | 350.10 | 350.32 | 350.55 | 350.78 | 351.01 | 351.24 | 351.47 |\n|  35  | 352.04 | 352.35 | 352.65 | 352.96 | 353.27 | 353.57 | 353.88 | 354.19 | 354.49 | 354.80 | 355.11 |\n|  40  | 354.89 | 355.29 | 355.70 | 356.10 | 356.50 | 356.91 | 357.31 | 357.71 | 358.12 | 358.52 | 358.92 |\n|  45  | 357.71 | 358.24 | 358.76 | 359.29 | 359.82 | 360.34 | 360.87 | 361.40 | 361.92 | 362.45 | 362.98 |\n|  50  | 360.51 | 361.19 | 361.87 | 362.55 | 363.23 | 363.92 | 364.60 | 365.28 | 365.96 | 366.64 | 367.32 |\n|  55  | 363.29 | 364.16 | 365.04 | 365.91 | 366.78 | 367.66 | 368.53 | 369.40 | 370.28 | 371.15 | 372.02 |\n|  60  | 366.05 | 367.16 | 368.27 | 369.38 | 370.49 | 371.59 | 372.70 | 373.81 | 374.92 | 376.03 | 377.14 |\n\n\n**Notes on table**\n- values for 0% are calculated with ```sos = 331.45 * sqrt(1 + T/273.16);  //  T in Celsius```\n- values for 90% are calculated with - https://sengpielaudio.com/calculator-airpressure.htm\n  - these match - https://www.engineeringtoolbox.com/air-speed-sound-d_603.html\n- the other values are linear interpolated between the 0 and 90 column (100% is extrapolated)\n- the table range is from -40 to +60 as that covers 99% of the \"normal\" temperatures occuring.\n\nFor temperatures under 0°C the effect of humidity goes to zero as we look how the difference\nbetween 90% and 0% decreases when temperature drops.\n\nThe function **float calculateSpeedOfSound()** uses two interpolations derived from the table above.\nThe function has no look-up table and uses no lookup table / RAM.\nThis function returns a speed of sound with an overall error margin less than 1%, and mostly even\nlower than 0.5% compared to the numbers above.\n\n\n### Related\n\n- https://www.robot-electronics.co.uk/htm/srf05tech.htm Good documentation including how to connect.\n- https://randomnerdtutorials.com/complete-guide-for-ultrasonic-sensor-hc-sr04/ good guide.\n- https://github.com/stoduk/PingSerial  Serial IO with distance sensors e.g. US-100\n\n\n## Interface\n\n```cpp\n#include \"SRF05.h\"\n```\n\n### Constructor\n\n- **SRF05(const uint8_t trigger, const uint8_t echo = 0)** constructor to set the trigger and echo pin.\nThe echo pin can be left out, or set to the same as the trigger pin.\nIn total one can do it in three ways.\n\n```cpp\nconst int trigger = 7;\nconst int echo    = trigger;\n\nSRF05 SRF(trigger, echo);\nSRF05 SRF(trigger, trigger);\nSRF05 SRF(trigger);\n```\n\nTo select single pin mode in the hardware the MODE pin of the device must be connected to GND.\nFor the two pin (compatibility) mode the MODE pin must be left floating.\n\n\n### Configuration\n\n- **void setSpeedOfSound(float sos = 340)** adjust the speed of sound in meters per second (m/s).\nSee table above.\nThe function has **no range check** and accepts even negative values.\nThis will cause a negative sign in the distances which can be useful sometimes when you have\ntwo sensors in opposite directions.\n- **float getSpeedOfSound()** return set value (m/s)\n- **bool setCorrectionFactor(float factor = 1)** adjust the timing by a few percentage e.g. to adjust clocks.\nTypical values are between 0.95 and 1.05 to correct up to 5%.\nShould not be used to correct the speed of sound :)\nReturns false if factor is negative, \u003c= 0.\n- **float getCorrectionFactor()** returns the current correction factor.\n\n\n### Operational mode\n\nNormally a single read should be sufficient, but the library has more modi.\n\n- **void setModeSingle()** read a single time.\nThis is the default and typical the fastest.\n- **void setModeAverage(uint8_t count)** read count times and take the average.\nNote: between the reads there is a default delay of 1000 microseconds.\n- **void setModeMedian(uint8_t count)** read count times and take the median.\ncount must between 3 and 15 otherwise it is clipped.\nNote: between the reads there is a default delay of 1000 microseconds.\n- **void setModeRunningAverage(float alpha)** use a running average algorithm\nwith a weight alpha. Value for alpha depends on your application.\nAlpha must be larger than zero and smaller or equal to one. Alpha == \u003c0..1]\nLower alpha averages great for static distances, a higher alpha is better\nsuited for changing distances.\n- **uint8_t getOperationalMode()** returns the operational mode 0..3.\nSee table below.\n- **void setSampleInterval(uint16_t microSeconds = 1000)** changes the interval used\nin **SRF05_MODE_AVERAGE** and **SRF05_MODE_MEDIAN**.\nDefault is 1000 us == 1 milliSecond. Maximum is 65535 microseconds.\n- **uint16_t getSampleInterval()** return set interval.\n\n|  Operational mode        |  Value  |  Notes  |\n|:-------------------------|:-------:|:--------|\n|  SRF05_MODE_SINGLE       |    0    |  default mode\n|  SRF05_MODE_AVERAGE      |    1    |  default sample interval 1000 us\n|  SRF05_MODE_MEDIAN       |    2    |  default sample interval 1000 us\n|  SRF05_MODE_RUN_AVERAGE  |    3    |\n|                          |  other  |  error\n\nIf other modi are needed, please open an issue and I see if it fits.\nOf course one can create more elaborated processing of measurements\noutside the library.\n\n\n### Get distance\n\n- **uint32_t getTime()** returns distance in microseconds.\nThis is the core measurement function, the next five are wrappers\naround this one.\n- **uint32_t getMillimeter()** returns distance in millimetre.\n- **float getCentimeter()** returns distance in centimetre.\n- **float getMeter()** returns distance in meter.\n- **float getInch()** returns distance in inches. (1 inch = 2.54 cm).\n- **float getFeet()** returns distance in feet. (1 feet = 12 inch).\n- **float getYards()** returns distance in yards. (1 yard = 3 feet = 36 inch).\n\n\n### Experimental - setTriggerLength\n\nSince 0.1.4 two experimental functions are added to tune the length\nof the trigger signal.\nThe idea is that shorter triggers can be used with harder surfaces\nor short distances. Longer trigger thus for longer distances.\n\nThe effects and value of adjusting trigger length needs investigation.\nExperiences are welcome.\n\n- **void setTriggerLength(uint8_t length = 10)** default length == 10 us.\n- **uint8_t getTriggerLength()** returns set length.\n\n\n### Experimental - calibration\n\nPut the sensor at exactly 1.00 meter from a wall, and based\nupon the timing it will give an estimate for the speed of sound.\n0.1.2 version seems to be accurate within 5 %.\n\n- **float determineSpeedOfSound(float distance, uint8_t count = 64)** distance is between\nsensor and the wall, single trip, not forth and back.\nThe distance is in meters, returns meters/second.\nThe distance is averaged over count measurements.\n\nThis function can be used to compensate for temperature, humidity\nor even other types of gas (e.g. N2 only)\n\n\n### Experimental - calculateSpeedOfSound\n\n- **float calculateSpeedOfSound(float temperature, float humidity)**\nCalculates the speed of sound given a temperature in Celsius (-40..60)\nand relative humidity (0..100).\n\nThe function uses an interpolation formula derived from the table above.\nThis returns a speed with an error margin less than 1%, and for the most\npart it is even better than 0.5%.\n\nBe aware that especially humidity sensors have an accuracy, often in the\nrange from two to five percent. So it won't get much better.\n\n\n### Performance\n\nAssumes speed of sound of 340 m/sec.\n\nIndicative pulse timing, note round trip is double distance!\n\n| distance (cm) | time (us) |  Notes  |\n|:-------------:|----------:|:--------|\n|        1      |     29.4  |\n|        2      |     58.8  |\n|        5      |    147.1  |\n|       10      |    294.1  |\n|       20      |    588.2  |\n|               |           |\n|       50      |     1471  |\n|      100      |     2941  |\n|      200      |     5882  |  blocks for approx. 6ms !\n|      300      |     8824  |\n|      400      |    11765  |\n|      500      |    14706  |\n\nTo be elaborated, precission is only 3 or 4 digits max.\n\n\n## Operational\n\nSee examples.\n\n\n## Future\n\n#### Must\n\n- investigate purpose/possibilities of the OUT pin.\n\n#### Should\n\n- add examples\n  - DHT22 and the formula for SOS\n- investigate effect of wind (speed of air) on the speed of sound.\n- investigate\n  - value of **setTriggerLength()**\n- investigate \"guard time\" between reads of 50 ms (20x /sec max).\n\n\n#### Could\n\n- look into ARDEN-BUCK equation.\n- set default SOS to an SOS from the table instead of 340.\n  - function **begin(T, H)** ?\n- add example to determine the correction factor?\n- add uint16_t **PulseTimeOut** = 200;  //  milliSeconds?\n  - void setPulseTimeOut(uint16_t milliSeconds = 200);\n  - uint16_t getPulseTimeOut();\n\n\n#### Wont\n\n- should **setSpeedOfSound(float sos)** return bool if sos \u003c=0 ?\n- print feet as 3'2\" or  3-7/8 feet (is that needed in this lib)\n  - see printHelpers lib **printFeet(float feet)**\n- fix magic conversion numbers.\n- add ```float lastValue()``` ?\n  - not all paths update this variable.\n- add ```float delta()``` difference with last value.\n  - how to handle different units? or only time?\n\n\n## Support\n\nIf you appreciate my libraries, you can support the development and maintenance.\nImprove the quality of the libraries by providing issues and Pull Requests, or\ndonate through PayPal or GitHub sponsors.\n\nThank you,\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frobtillaart%2Fsrf05","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Frobtillaart%2Fsrf05","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frobtillaart%2Fsrf05/lists"}