Struct apigpio::Connection

source ·

pub struct Connection { /* private fields */ }

Expand description

Main struct which owns a connection to pigpiod. Start by creating one of these.

Most of the interesting methods are methods on ConnectionCore, which this derefs to.

Implementations

source

impl Connection

source

pub async fn new_at<A: ToSocketAddrs>(addr: &A) -> Result<Connection>

Connects to pigpiod, given specific socket address details.

source

pub async fn new() -> Result<Connection>

Connects to pigpiod using the default address and port.

source

impl Connection

source

pub async fn notify_subscribe(
 &self,
 pin: PPin,
 read_initially: bool,
 tick_keepalives: bool
) -> Result<Subscription>

Starts watching for changes to a GPIO pin

Change notifications are sent as GpioChange to the returned Subscription, which is a wrapper for a postage::watch::Receiver<GpioChange>.

If read_initially, reads the gpio once at the start, so that the subscription’s level starts out as Some.

If tick_keepalives, will send a GpioChange with unchanged Some(Level) and a fresh Some(Tick) at least every TICK_KEEPALIVE_US; this allows the receiver to spot when the tick wraps around.

Connections to pigpiod and the pigpiod connection limit

Behind the scenes, getting GPIO change notifications involves making a 2nd connection to pigpiod. This will be done the first time notify_subscribe is called; it will then be retained for future reuse.

So a Connection that has had notify_subscribe called uses up two pigpiod connections. This is relevant because pigpiod has a limit on the number of simultaneous connections.

Methods from Deref<Target = ConnectionCore>

source

pub async fn wave_create(&self) -> Result<WaveId>

Create a waveform (globally, in pigpiod)

Caller is responsible for not calling wave_* functions for multiple purposes concurrently - ie, for enforcing the concurrency control implied by pigpiod’s interface.

Getting this wrong is not a memory safety concern (hence the lack of unsafe) but would cause wrong behaviours.

Note that this applies even across multiple different pigpiod clients.

source

pub async unsafe fn wave_delete(&self, wave: WaveId) -> Result<()>

Delete a waveform (globally, in pigpiod)

Safety

This is safe if no-one in the whole system ever calls wave_send_using_mode with mode *SYNC*. See the pigpio documentation on wave_send_using_mode for full details.

It is usually easier to call the safe function wave_clear before startup, and during shutdown, than to worry about these questions.

source

pub async fn wave_send_once(&self, wave: WaveId) -> Result<Word>

source

pub async fn wave_send_repeat(&self, wave: WaveId) -> Result<Word>

source

pub async fn wave_tx_stop(&self) -> Result<()>

source

pub async fn wave_tx_at(&self) -> Result<Option<WaveId>>

source

pub async fn wave_tx_busy(&self) -> Result<bool>

source

pub async fn wave_add_generic(&self, pulses: &[Pulse]) -> Result<Word>

source

pub async fn wave_get_micros(&self) -> Result<Word>

source

pub async fn wave_get_high_micros(&self) -> Result<Word>

source

pub async fn wave_get_max_micros(&self) -> Result<Word>

source

pub async unsafe fn wave_send_using_mode(
 &self,
 wave: WaveId,
 txmode: Word
) -> Result<Word>

Start sending a waveform using a specified mode value

Safety

Caller must ensure that if txmode is *SYNC* the “bad things” described in the pigpio docs do not happen.

If any calls to this facility (whether via apigpio or any other way of talking to pigpiod) use *SYNC*, then wave_delete (and the equivalent function in other pigpiod bindings) is potentially unsafe and all calls to it must be checked. Note that because everything is shared amongst all clients of pigpiod, this might involve auditing your process handling etc.

Caller must also ensure that txmode is a known valid value, which represents a safe and sane mode. Unknown values are unsound because they might invoke some hazardous new feature of pigpiod.