Skip to content

Commit 1698a4e

Browse files
RobTillaartRobTillaart
committed
0.1.0 US500
1 parent bf09f2c commit 1698a4e

18 files changed

Lines changed: 781 additions & 0 deletions

‎libraries/US500/.arduino-ci.yml‎

Lines changed: 30 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,30 @@
1+
platforms:
2+
rpipico:
3+
board: rp2040:rp2040:rpipico
4+
package: rp2040:rp2040
5+
gcc:
6+
features:
7+
defines:
8+
- ARDUINO_ARCH_RP2040
9+
warnings:
10+
flags:
11+
12+
packages:
13+
rp2040:rp2040:
14+
url: https://github.com/earlephilhower/arduino-pico/releases/download/global/package_rp2040_index.json
15+
16+
compile:
17+
# Choosing to run compilation tests on 2 different Arduino platforms
18+
platforms:
19+
# - uno
20+
# - due
21+
# - zero
22+
# - leonardo
23+
- m4
24+
- esp32
25+
- esp8266
26+
# - mega2560
27+
- rpipico
28+
29+
libraries:
30+
- "printHelpers"

‎libraries/US500/.github/FUNDING.yml‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,4 @@
1+
# These are supported funding model platforms
2+
3+
github: RobTillaart
4+
custom: "https://www.paypal.me/robtillaart"

‎libraries/US500/.github/workflows/arduino-lint.yml‎

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,13 @@
1+
name: Arduino-lint
2+
3+
on: [push, pull_request]
4+
jobs:
5+
lint:
6+
runs-on: ubuntu-latest
7+
timeout-minutes: 5
8+
steps:
9+
- uses: actions/checkout@v6
10+
- uses: arduino/arduino-lint-action@v2
11+
with:
12+
library-manager: update
13+
compliance: strict

‎libraries/US500/.github/workflows/arduino_test_runner.yml‎

Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,16 @@
1+
name: Arduino CI
2+
3+
on: [push, pull_request]
4+
5+
jobs:
6+
runTest:
7+
runs-on: ubuntu-latest
8+
timeout-minutes: 20
9+
steps:
10+
- uses: actions/checkout@v6
11+
- uses: ruby/setup-ruby@v1
12+
with:
13+
ruby-version: 2.6
14+
- run: |
15+
gem install arduino_ci
16+
arduino_ci.rb

‎libraries/US500/.github/workflows/jsoncheck.yml‎

Lines changed: 20 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,20 @@
1+
name: JSON check
2+
3+
on:
4+
push:
5+
paths:
6+
- '**.json'
7+
pull_request:
8+
paths:
9+
- '**.json'
10+
11+
jobs:
12+
test:
13+
runs-on: ubuntu-latest
14+
timeout-minutes: 5
15+
steps:
16+
- uses: actions/checkout@v6
17+
- name: json-syntax-check
18+
uses: limitusus/json-syntax-check@v2
19+
with:
20+
pattern: "\\.json$"

‎libraries/US500/CHANGELOG.md‎

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,13 @@
1+
# Change Log US500
2+
3+
All notable changes to this project will be documented in this file.
4+
5+
The format is based on [Keep a Changelog](http://keepachangelog.com/)
6+
and this project adheres to [Semantic Versioning](http://semver.org/).
7+
8+
9+
## [0.1.0] - 2026-04-29
10+
- initial version
11+
12+
13+

‎libraries/US500/LICENSE‎

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
MIT License
2+
3+
Copyright (c) 2026-2026 Rob Tillaart
4+
5+
Permission is hereby granted, free of charge, to any person obtaining a copy
6+
of this software and associated documentation files (the "Software"), to deal
7+
in the Software without restriction, including without limitation the rights
8+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9+
copies of the Software, and to permit persons to whom the Software is
10+
furnished to do so, subject to the following conditions:
11+
12+
The above copyright notice and this permission notice shall be included in all
13+
copies or substantial portions of the Software.
14+
15+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21+
SOFTWARE.

‎libraries/US500/README.md‎

Lines changed: 211 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,211 @@
1+
2+
[![Arduino CI](https://github.com/RobTillaart/US500/workflows/Arduino%20CI/badge.svg)](https://github.com/marketplace/actions/arduino_ci)
3+
[![Arduino-lint](https://github.com/RobTillaart/US500/actions/workflows/arduino-lint.yml/badge.svg)](https://github.com/RobTillaart/US500/actions/workflows/arduino-lint.yml)
4+
[![JSON check](https://github.com/RobTillaart/US500/actions/workflows/jsoncheck.yml/badge.svg)](https://github.com/RobTillaart/US500/actions/workflows/jsoncheck.yml)
5+
[![GitHub issues](https://img.shields.io/github/issues/RobTillaart/US500.svg)](https://github.com/RobTillaart/US500/issues)
6+
7+
[![License: MIT](https://img.shields.io/badge/license-MIT-green.svg)](https://github.com/RobTillaart/US500/blob/master/LICENSE)
8+
[![GitHub release](https://img.shields.io/github/release/RobTillaart/US500.svg?maxAge=3600)](https://github.com/RobTillaart/US500/releases)
9+
[![PlatformIO Registry](https://badges.registry.platformio.org/packages/robtillaart/library/US500.svg)](https://registry.platformio.org/libraries/robtillaart/US500)
10+
11+
12+
# US500
13+
14+
Arduino library for US500 underwater distance sensor.
15+
16+
17+
## Description
18+
19+
**Experimental**
20+
21+
This library is to use the US500 underwater (IP67) distance sensor.
22+
The sensor communicates over Serial at 9600 baud.
23+
The MCU sends a command and depending on the command the device answers.
24+
25+
The device can read a distance in the range from 0.5 to 50 centimetre (0.2 - 20 inch).
26+
The accuracy is ±2mm (~0.1 inch).
27+
The field of view is ±5°.
28+
The US500 can also read the temperature of the water typical 0-100°C.
29+
Furthermore the device has a start and stop function.
30+
These functions are straight forward.
31+
32+
The library is not tested with hardware (order pending).
33+
34+
It is unknown how the device behaves in other liquids, at least the distance
35+
measurements are expected to be incorrect (other speed of sound).
36+
37+
The device might need a separate power supply (75mW @ 5V).
38+
39+
Feedback, as always is welcome.
40+
41+
42+
### Connections US500
43+
44+
The US500 device is connected to a controller board (which is NOT waterproof).
45+
46+
| Colour | Connection | Notes |
47+
|:--------------|:-------------|:--------|
48+
| Gray core | D signal + | polarity !!
49+
| Gray shield | D signal - | polarity !!
50+
| Black | Temp NTC |
51+
| Black | Temp NTC |
52+
53+
The temperature sensor has no preferred orientation, however the GRAY
54+
distance cable can only be connected in one way.
55+
56+
57+
### Compatible
58+
59+
The US4000 (up to 4 meter, IP68) is almost compatible with the US500.
60+
Main difference is the address and the setDistance() call is not supported.
61+
A future update is planned to support the US4000.
62+
63+
64+
### About hardware
65+
66+
It is not know what the resistance of the NTC is, otherwise it might be connected
67+
with voltage divider to an analog port (possible improve resolution?).
68+
69+
It is also not clear what the protocol of the distance sensor is.
70+
The transducer operates with a 3.3 MHz frequency.
71+
Assumption is it will send a short pulse and waits for the echo.
72+
73+
74+
### Speed of sound in water
75+
76+
It is unknown if the US500 compensates for the temperature of the water.
77+
One may assume it does.
78+
79+
From - https://www.engineeringtoolbox.com/sound-speed-water-d_598.html
80+
(has also a Fahrenheit => feet/sec table)
81+
82+
| temp °C | Speed m/s | Speed m/s | Diff % |
83+
|:---------:|:------------:|:------------:|:--------:|
84+
| | WATER | SEAWATER | |
85+
| 0 | 1403 | 1449 | 3.28 |
86+
| 5 | 1427 | | |
87+
| 10 | 1447 | 1490 | 2.97 |
88+
| 20 | 1481 | 1522 | 2.77 |
89+
| 30 | 1507 | 1546 | 2.59 |
90+
| 40 | 1526 | 1563 | 2.63 |
91+
| 50 | 1541 | | |
92+
| 60 | 1552 | | |
93+
| 70 | 1555 | | |
94+
| 80 | 1555 | | |
95+
| 90 | 1550 | | |
96+
| 100 | 1543 | | |
97+
98+
Values in between can be interpolated.
99+
100+
Assumption is that the distance can be adjusted to other liquids
101+
by using right formula.
102+
103+
104+
### Warnings from datasheet
105+
106+
1. Please make sure the Ultrasonic sensor probe unite perpendicular to the object( around 90°±5°)
107+
When the ultrasonic sensor measure the object. If the angle bigger than 90°±5°,the signal will lose.
108+
2. Please keep the sensor probe fixed for the test and do not hold it with your hand.That would affect
109+
the signal.
110+
3. The controller is not waterproof. Please do not submerge the controller in water.
111+
4. This sensor is calibrated based on underwater measurement scenarios.
112+
Cannot be use in air measurement scenarios.
113+
114+
115+
### Related
116+
117+
Supplier
118+
- https://www.positive-inno.com - supplier of the US500 (US4000 and more).
119+
- https://positive-inno.com/wp-content/uploads/2026/04/US500-Manual.pdf - datasheet
120+
- https://positive-inno.com/wp-content/uploads/2026/04/US4000LSG-M20-TTL-Manual.pdf - datasheet
121+
122+
Libraries:
123+
- https://github.com/RobTillaart/US500 - this library
124+
- https://github.com/RobTillaart/SRF05 - library for SRF05 distance sensor with temperature and humidity compensation.
125+
- https://www.tinytronics.nl/nl/sensoren/afstand/pono-us500-hx-onderwater-ultrasone-afstandssensor-uart-50cm
126+
127+
128+
### Tested
129+
130+
TODO test with hardware.
131+
132+
133+
## Interface
134+
135+
```cpp
136+
#include "US500.h"
137+
```
138+
139+
### Constructor
140+
141+
- **US500(Stream \* str)** Typical Serial1 or Serial2.
142+
It is not known if software serial will work (not tested).
143+
- **uint16_t getAddress()** returns 0x0005. Convenience function.
144+
145+
146+
### Core
147+
148+
If the functions return a value < 0, it is an error code.
149+
150+
- **float getDistance()** returns the distance in cm (or error code).
151+
- **int setMaxDistance(uint16_t distance)** set the maximum range in 0.1 mm
152+
Must be between 1500 and 5000.
153+
returns 0 = false or 1 = true (or error code).
154+
- **float getTemperature()** returns the temperature in degrees Celsius.
155+
(or error code).
156+
The resolution is in steps of 0.1 degree, supports negative values.
157+
- **void startMeasurement()** idem.
158+
- **void stopMeasurement()** idem.
159+
160+
161+
### Error codes
162+
163+
| name | value |
164+
|:----------------------|:-------:|
165+
| US500_CMD_ERROR | -1 |
166+
| US500_CRC_ERROR | -2 |
167+
| US500_TIMEOUT_ERROR | -3 |
168+
169+
170+
### Helper
171+
172+
- **void flush()** if communication is out of sync,
173+
one can flush int input buffer.
174+
175+
176+
## Future
177+
178+
#### Must
179+
180+
- improve documentation
181+
- get hardware
182+
- test, test, test
183+
184+
#### Should
185+
186+
- support US4000
187+
- improve error handling
188+
- add range check for setMaxDistance or constrain.
189+
- verify software serial works / not.
190+
- test temperature range (water is typical > 0).
191+
- do we need to compensate distance for temperature?
192+
or is this done in the factory / device.
193+
- time for measurement after start.
194+
- performance indication. per function.
195+
196+
#### Could
197+
198+
- create unit tests if possible
199+
200+
#### Wont
201+
202+
203+
## Support
204+
205+
If you appreciate my libraries, you can support the development and maintenance.
206+
Improve the quality of the libraries by providing issues and Pull Requests, or
207+
donate through PayPal or GitHub sponsors.
208+
209+
Thank you,
210+
211+

0 commit comments

Comments
 (0)