TMF882X (tmf882x v0.1.0)

Interface with tmf8820/tmf8821 direct time-of-flight (dToF) sensor ([https://ams.com/en/tmf8820]).

starting

Starting

Start a TMF882X it directly from another process (See Options section below for more info):

{:ok, pid} = TMF882X.start_link(bus: "i2c-1")

configuration

Configuration

A configuration keyword list can be passed to the start_link function containing the following parameters:

  • bus - Name of the I2C bus that the sensor is attached to.

  • interrupt_gpio - If the interrupt pin of the sensor is connected, the GPIO number can be specified here. If not interrupt

            pin is specified, then the library will use I2C to poll when a new measurement packet is ready.
  • enable_gpio - If the enable pin is connected, the GPIO number can be specified here. If connected, calling reset/1 will

            use this pin to reset the device.  Otherwise, I2C commands will be issued to reset the device. (default: `nil`)
  • auto_start - If set to true, the device will immediately start taking measurements once the app_ready status is true.

                If set to `false`, the device will wait for a call to `start_measuring/1` before taking any measurements. (default: `true`)
  • measure_interval - Target interval (in milliseconds) between measurements. If set to 0, as soon as a measurement is received, another

                      will start.
  • device_config - The configuration to be sent to the device on startup. See Configuration section below.

results

Results

The calling process will receive messages of the format {:tmf882x, %TMF882X.Result{}}:

def handle_info({:tmf882x, %TMF882X.Result{} = result}) do
...
end

The TMF882X.Result struct contains a list of measurements from each channel. Each measurement is a tuple containing a distance (in millimeters) and confidence (out of 255) value:

%TMF882X.Result{
tid: 200,
size: 128,
number: 200,
temperature: 41,
valid_results: 11,
ambient: 283,
photon_count: 16971,
reference_count: 60573,
sys_tick: 1215866837,
measurements: [
  {844, 61},
  {841, 106},
  {1010, 56},
  ...
]
}

Other fields in the Result struct are directly from the decode of the Result register.

Link to this section Summary

Functions

Returns true if the application on the device has been initialized. Measurements cannot be started until the app_ready flag is true.

Returns a specification to start this module under a supervisor.

Queries the device for its current configuration and returns it.

Queries the device for the current custom spad_map and returns it.

Returns the status of the device gathered from the 0xE0 register.

Applies the given configuration values to the device. This will temporarily stop the measurements and resume them after the configuration if written (if they were running before).

Resets the device including resetting the enable pin (if configured).

Returns true if the process is measuring actively.

Sets the custom spad to the one provided.

Starts the measurement process for the given device. Once started, the process will send {:tmf882x, %TMF882X.Result{}} messages each time a measurement is completed.

Stops the measurement process for the given device.

Link to this section Types

@type server() :: atom() | pid() | {atom(), any()} | {:via, atom(), any()}

Link to this section Functions

Link to this function

app_ready?(pid)

@spec app_ready?(server()) :: boolean()

Returns true if the application on the device has been initialized. Measurements cannot be started until the app_ready flag is true.

Link to this function

calc_measure_delay(state)

Link to this function

child_spec(init_arg)

Returns a specification to start this module under a supervisor.

See Supervisor.

Link to this function

get_config(pid)

@spec get_config(server()) :: map()

Queries the device for its current configuration and returns it.

Link to this function

get_custom_spad(pid)

@spec get_custom_spad(server()) :: map()

Queries the device for the current custom spad_map and returns it.

Link to this function

get_status(pid)

@spec get_status(server()) :: %{active: boolean(), enabled: boolean()}

Returns the status of the device gathered from the 0xE0 register.

Link to this function

put_config(pid, config)

@spec put_config(server(), map()) :: :ok

Applies the given configuration values to the device. This will temporarily stop the measurements and resume them after the configuration if written (if they were running before).

@spec reset(server()) :: :ok

Resets the device including resetting the enable pin (if configured).

@spec running?(server()) :: boolean()

Returns true if the process is measuring actively.

Link to this function

set_custom_spad(pid, spad)

@spec set_custom_spad(server(), TMF882X.SPAD.t()) :: :ok

Sets the custom spad to the one provided.

NOTE: the device configuration must be set with spad_map_id set to 14 before the custom spad map can be written. Otherwise, the custom spad command will silently fail.

Link to this function

start_link(opts \\ [])

@spec start_link(keyword()) :: GenServer.on_start()
Link to this function

start_measuring(pid)

@spec start_measuring(server()) :: :ok

Starts the measurement process for the given device. Once started, the process will send {:tmf882x, %TMF882X.Result{}} messages each time a measurement is completed.

Link to this function

stop_measuring(pid)

@spec stop_measuring(server()) :: :ok

Stops the measurement process for the given device.