# hcsr04

HC-SR04 Ultrasonic Ranging Module Library.

Author | Rob Jansen, Copyright © 2023..2023, all rights reserved.
Adapted-by |
Compiler | 2.5r8

Description

    Library for the HC-SR04 Ultrasonic Ranging Module.
                 The library can be configured to use either the external
                 interrupt or an IOC interrupt to measure the echo signal
                 from the module using Timer 1.
                 The default is using an external interrupt. In order to switch
                 to using an IOC interrupt the user must initialize the IOC
                 to be active on both the rising and falling edge and must
                 define the following alias (example for IOC on pin A2):
                 -) alias hcsr04_ioc_flag is IOCAF_IOCAF2

Sources

    Datasheet Ultrasonic ranging module : HC-SR04.

Notes

    The echo signal ranges from about 150 us to 25 ms. In case
                 there is no object, the echo signal is about 38 ms. If
                 no echo signal is received, the library will timeout after
                 65 ms when Timer 1 runs at 1 MHz.

Dependencies

No dependency found

## Summary

### Global variables/contants

- `const _HCSR04_EDGE_FALLING = FALSE`
- `var byte _hcsr04_state`
- `var bit _hcsr04_timer1_expired`
- `const byte _HCSR04_IDLE = 0`
- `const dword _HCSR04_MIN = (100 * HCSR04_SCALING) / 100`
- `const byte _HCSR04_ECHO_END = 2`
- `var bit _hcsr04_measurement_done, _hcsr04_measurement_error`
- `const byte _HCSR04_ECHO_START = 1`
- `const dword _HCSR04_MAX = (30_000 * HCSR04_SCALING) / 100`
- `var word _hcsr04_echo_time`
- `const _HCSR04_EDGE_RISING = TRUE`
- `const word _HCSR04_OVERFLOW = 65535`

### Procedures

- `hcsr04_start_measurement()`
- `hcsr04_init()`

Private

- `_hcsr04_timer1_interrupt()`
- `_hcsr04_interrupt()`
- `_hcsr04_timer1_reset()`

### Functions

- `hcsr04_get_distance_mil() return dword`
- `hcsr04_measurement_done() return bit`
- `hcsr04_get_distance_mm() return word`
- `hcsr04_measurement_error() return bit`

Private

- `_hcsr04_get_timer1_value() return word`
- `_hcsr04_handle_interrupt_flag() return bit`

## API details

### Global variables/contants

- `const _HCSR04_EDGE_FALLING = FALSE`

  No documentation found

- `var byte _hcsr04_state`

  No documentation found

- `var bit _hcsr04_timer1_expired`

  No documentation found

- `const byte _HCSR04_IDLE = 0`

      Measurement states.

- `const dword _HCSR04_MIN = (100 * HCSR04_SCALING) / 100`

      Bit-time for normal operation is between 150 us and 25 ms. Time is in us.
      We take some margin here.

- `const byte _HCSR04_ECHO_END = 2`

  No documentation found

- `var bit _hcsr04_measurement_done, _hcsr04_measurement_error`

  No documentation found

- `const byte _HCSR04_ECHO_START = 1`

  No documentation found

- `const dword _HCSR04_MAX = (30_000 * HCSR04_SCALING) / 100`

  No documentation found

- `var word _hcsr04_echo_time`

      Internal variables.

- `const _HCSR04_EDGE_RISING = TRUE`

      We need to capture the pulse on edges (external interrupt only).

- `const word _HCSR04_OVERFLOW = 65535`

      Max value of timer 1 before overflow.

### Procedures

- `hcsr04_start_measurement()`

      Start an ultrasonic distance measurement.

- `hcsr04_init()`

      Initialize the HCSR04 library. This will enable the required interrupts.

Private

- `_hcsr04_timer1_interrupt()`

      Timer1 interrupt. Occurs when the timer overflows after 65 ms (1 MHz clock)
      which means that no measurement could be done. We need to trigger the
      interrupt to activate the state machine and handle the overflow.

- `_hcsr04_interrupt()`

      Interrupt routine, triggerd by INT or IOC.

- `_hcsr04_timer1_reset()`

      Reset Timer 1 and start the timer.

### Functions

- `hcsr04_get_distance_mil() return dword`

      Returns the last measured distance in mil.

- `hcsr04_measurement_done() return bit`

      Returns TRUE when a distance measurement was done.

- `hcsr04_get_distance_mm() return word`

      Returns the last measured distance in milimeter.

- `hcsr04_measurement_error() return bit`

      Returns TRUE when a distance measurement error was encountered. This error
      occurs when the measured time is too long. This can occur when the object.
      is out of reach or the module is not connected.

Private

- `_hcsr04_get_timer1_value() return word`

       ----------------------------------------------------------------------------
      Stop Timer 1 and return the value of Timer 1. We return the Timer value if
      it has not overflown otherwise this function returns the overflow value.

- `_hcsr04_handle_interrupt_flag() return bit`

      This procedure handles the interupt flag. Reason for this procedure is to be
      able to use two differnt interrupt types, IOC and external.

## Related samples

Here are the list of samples which use this library:

16f1825 | 16f1825_hcsr04_led.jal
16f1825 | 16f1825_hcsr04_serial.jal