Class pn532::channel

Inheritance Relationships

Derived Types

Class Documentation

class channel

Abstract class for the PN532 communication channel.

Each channel class must support send and receive over a hardware channel. Only one operation among comm_dir::send and comm_dir::receive can be performed at a given time. Before another communication operation is performed, the previous one is guaranteed to be completed. The PN532 always uses half-duplex communication mode.

Subclasses must implement the following methods:

Use comm_operation to manage firing events correctly.

Note

Subclasses should never directly call any of on_receive_prepare, on_receive_complete, on_send_prepare, on_send_complete. These are managed by comm_operation. Moreover, subclasses should never call raw_send or raw_receive without a comm_operation in place.

Subclassed by pn532::esp32::hsu_channel, pn532::esp32::i2c_channel, pn532::esp32::spi_channel

Channel events

These methods are paired on_*_prepare/on_*_complete. They are guaranteed to be called in pairs, each prepare is followed by one complete. If raw_receive_mode is true, then multiple raw_receive calls may be performed subsequently in-between a on_receive_prepare and a on_receive_complete; otherwise, at most one call is performed. For sending data, there is always a single call to raw_send in-between on_send_prepare and its counterpart on_send_complete.

inline virtual bool on_receive_prepare(ms timeout)

Prepares the underlying channel for data reception. The default implementation does nothing.

Parameters:

timeout – Maximum time that can be used to set the channel up.

Returns:

A boolean representing whether setup has been completed within the given timeout.

inline virtual void on_receive_complete(result<> const &outcome)

Signals that the reception has been completed. The default implementation does nothing.

Parameters:

outcome – Result of the raw_receive operation.

inline virtual bool on_send_prepare(ms timeout)

Prepares the underlying channel for data trasmission. The default implementation does nothing.

Parameters:

timeout – Maximum time that can be used to set the channel up.

Returns:

A boolean representing whether setup has been completed within the given timeout.

inline virtual void on_send_complete(result<> const &outcome)

Signals that the transmission has been completed. The default implementation does nothing.

Parameters:

outcome – Result of the raw_send operation.

Public Functions

virtual ~channel() = default
virtual bool wake() = 0

Pure virtual: wakes up the PN532 from slumber. This usually corresponds to sending some trigger garbage bytes over the channel, or raising/lowering some interrupt line.

Returns:

A boolean representing whether the wake up operation has succeeded.

result send_ack(bool ack_value, ms timeout)

Sends a frame_type::ack or a frame_type::nack frame.

Parameters:
Returns:

Either mlab::result_success, or one of

result receive_ack(bool ack_value, ms timeout)

Waits until a frame_type::ack or a frame_type::nack frame is received..

Parameters:
Returns:

mlab::result_success if the specified frame has been received, otherwise one of

result command(command_code cmd, bin_data data, ms timeout)

Sends a command without waiting for a response.

Parameters:

  • cmd – Command code.

  • data – Max 263 bytes, will be truncated.

  • timeout – Maximum time for sending the frame.

Returns:

mlab::result_success or any channel_error.

result<bin_data> response(command_code cmd, ms timeout)

Waits for a response frame of a specific command.

Parameters:

  • cmd – Command code.

  • timeout – Maximum time for getting a response.

Returns:

Either the received data, or one of

result<bin_data> command_response(command_code cmd, bin_data data, ms timeout)

Command with response. This calls subsequently command and response.

Parameters:

  • cmd – Command code.

  • data – Max 263 bytes, will be truncated.

  • timeout – Maximum time for sending the frame and getting a response.

Returns:

Either the received data, or any channel_error (including channel_error::malformed if the frame received is not an frame_type::info frame).

template<mlab::is_extractable Data>
result<Data> command_parse_response(command_code cmd, bin_data data, ms timeout)

Command with a typed response which can be extracted from a bin_stream.

Template Parameters:

Data – A type that supports mlab::bin_stream &operator>>(mlab::bin_stream &, Data &).

Parameters:

  • cmd – Command code.

  • data – Max 263 bytes, will be truncated.

  • timeout – Maximum time for sending the frame and getting a response.

Returns:

Either the received data, or any channel_error (including channel_error::malformed if the frame received is not an frame_type::info frame or if the data cannot be parsed.).

Protected Functions

virtual result raw_send(mlab::range<bin_data::const_iterator> buffer, ms timeout) = 0

Pure virtual: sends the data in buffer over the channel, synchronously.

Warning

Always call this with a suitable comm_operation in scope to guarantee the correct event firing.

Parameters:

  • buffer – Data to be sent.

  • timeout – Maximum timeout for the underlying implementation to complete sending the data.

Returns:

Either mlab::result_success, or one of

virtual result raw_receive(mlab::range<bin_data::iterator> buffer, ms timeout) = 0

Pure virtual: fills buffer with data from the underlying channel, synchronously.

See also

comm_rx_mode

Note

in comm_rx_mode::buffered, the caller may request to fill a buffer that is larger than the actual frame data. Subclasses must be prepared for this and not crash. It is not relevant what the buffer contains past the frame boundary (i.e. it could be garbage data), however we suggest setting that to something deterministic. The buffer will come prefilled with zeroes.

Warning

Always call this with a suitable comm_operation in scope to guarantee the correct event firing.

Parameters:

  • buffer – Buffer to fill (it is expected to be already appropriately sized).

  • timeout – Maximum timeout for the underlying implementation to complete sending the data.

Returns:

Either mlab::result_success, or one of

virtual comm_rx_mode raw_receive_mode() const = 0

Determines whether multiple calls to raw_receive can be performed as part of a single receive operation (in-between on_receive_prepare and on_receive_complete).

result send(any_frame const &frame, ms timeout)

Transmits the given frame to the PN532 in at most timeout milliseconds.

Parameters:

  • frame – Frame to transmit.

  • timeout – Maximum time allowed for the send operation.

Returns:

Either mlab::result_success, or one of

result<any_frame> receive(ms timeout)

Reads one frame sent by the PN532 to the host in at most timeout milliseconds. This method will appropriately call raw_receive the suitable number of times in order to receive a frame, according to raw_receive_mode.

Parameters:

timeout – Maximum time allowed for the entire receive operation (this time might cover multiple calls to raw_receive).

Returns:

Either the received frame, or one of

Friends

friend class comm_operation