NFCController.h

00001 /* mbed Microcontroller Library
00002  * Copyright (c) 2018 ARM Limited
00003  *
00004  * Licensed under the Apache License, Version 2.0 (the "License");
00005  * you may not use this file except in compliance with the License.
00006  * You may obtain a copy of the License at
00007  *
00008  *     http://www.apache.org/licenses/LICENSE-2.0
00009  *
00010  * Unless required by applicable law or agreed to in writing, software
00011  * distributed under the License is distributed on an "AS IS" BASIS,
00012  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
00013  * See the License for the specific language governing permissions and
00014  * limitations under the License.
00015  */
00016 
00017 #ifndef MBED_NFC_CONTROLLER_H
00018 #define MBED_NFC_CONTROLLER_H
00019 
00020 #include <stdint.h>
00021 #include "events/EventQueue.h"
00022 #include "platform/SharedPtr.h"
00023 #include "drivers/Timer.h"
00024 #include "drivers/Timeout.h"
00025 
00026 #include "NFCDefinitions.h"
00027 #include "NFCControllerDriver.h"
00028 
00029 #include "platform/Span.h"
00030 
00031 namespace mbed {
00032 namespace nfc {
00033 
00034 class NFCRemoteInitiator;
00035 class NFCRemoteTarget;
00036 class NFCControllerDriver;
00037 
00038 /**
00039  * @addtogroup nfc
00040  * @{
00041  */
00042 
00043 /**
00044  * This class represents a NFC Controller.
00045  *
00046  * A controller can be in one of three different states:
00047  *  * Idle/sleep state
00048  *  * Discovery state: The controller tries to discover a remote endpoint (initiator or target)
00049  *  * Connected state: The controller exchanges data with an endpoint (initiator or target)
00050  *
00051  * A NFCController instance needs to be initialized with a NFCControllerDriver instance which abstracts the specific controller being used.
00052  * A delegate needs to be set by the user to receive discovery events.
00053  */
00054 class NFCController : private NFCControllerDriver::Delegate {
00055 public:
00056 
00057     /**
00058      * The NFCController delegate. Users of the NFCController class need to implement this delegate's methods to receive events.
00059      */
00060     struct Delegate {
00061         /**
00062          * A enumeration of causes for the discovery process terminating.
00063          */
00064         enum nfc_discovery_terminated_reason_t {
00065             nfc_discovery_terminated_completed = 0, ///< Process completed, at least one endpoint was discovered
00066             nfc_discovery_terminated_canceled, ///< Process was canceled by the user
00067             nfc_discovery_terminated_rf_error ///< An unexpected error was encountered during an exchange on the air interface
00068         };
00069 
00070         /**
00071          * The discovery process terminated.
00072          * @param[in] reason the cause for the termination
00073          */
00074         virtual void on_discovery_terminated(nfc_discovery_terminated_reason_t reason) {}
00075 
00076         /**
00077          * A remote initiator was discovered (the local controller is in target mode).
00078          * @param[in] nfc_initiator the NFCRemoteInitiator instance
00079          */
00080         virtual void on_nfc_initiator_discovered(const SharedPtr<NFCRemoteInitiator> &nfc_initiator) {}
00081 
00082         /**
00083          * A remote target was discovered (the local controller is in initiator mode).
00084          * @param[in] nfc_target the NFCRemoteTarget instance
00085          */
00086         virtual void on_nfc_target_discovered(const SharedPtr<NFCRemoteTarget> &nfc_target) {}
00087 
00088     protected:
00089         ~Delegate() { }
00090     };
00091 
00092     /**
00093      * Construct a NFCController instance.
00094      *
00095      * @param[in] driver a pointer to a NFCControllerDriver instance
00096      * @param[in] queue a pointer to the events queue to use
00097      * @param[in] ndef_buffer a bytes array used to store NDEF messages
00098      */
00099     NFCController(NFCControllerDriver *driver, events::EventQueue *queue, const Span<uint8_t>  &ndef_buffer);
00100 
00101     /**
00102      * Initialize the NFC controller
00103      *
00104      * This method must be called before any other method call.
00105      *
00106      * @return NFC_OK, or an error.
00107      */
00108     nfc_err_t initialize();
00109 
00110     /**
00111      * Set the delegate that will receive events generated by this controller.
00112      *
00113      * @param[in] delegate the delegate instance to use
00114      */
00115     void set_delegate(Delegate *delegate);
00116 
00117     /**
00118      * Get the list of RF protocols supported by this controller.
00119      *
00120      * @return a bitmask of RF protocols supported by the controller
00121      */
00122     nfc_rf_protocols_bitmask_t get_supported_rf_protocols() const;
00123 
00124     /**
00125      * Set the list of RF protocols to look for during discovery.
00126      *
00127      * @param[in] rf_protocols the relevant bitmask
00128      * @return NFC_OK on success, or
00129      *  NFC_ERR_UNSUPPORTED if a protocol is not supported by the controller,
00130      *  NFC_ERR_BUSY if the discovery process is already running
00131      */
00132     nfc_err_t configure_rf_protocols(nfc_rf_protocols_bitmask_t rf_protocols);
00133 
00134     /**
00135      * Start the discovery process using the protocols configured previously.
00136      *
00137      * If remote endpoints are connected when this is called, they will be disconnected.
00138      *
00139      * @return NFC_OK on success, or
00140      *  NFC_ERR_BUSY if the discovery process is already running
00141      */
00142     nfc_err_t start_discovery();
00143 
00144     /**
00145      * Cancel/stop a running discovery process.
00146      *
00147      * @return NFC_OK
00148      */
00149     nfc_err_t cancel_discovery();
00150 
00151 private:
00152     // These two classes need to be friends to access the following transceiver() method
00153     friend class NFCRemoteEndpoint;
00154     friend class Type4RemoteInitiator;
00155     nfc_transceiver_t *transceiver() const;
00156 
00157     void polling_callback(nfc_err_t ret);
00158 
00159     // NFC Stack scheduler
00160     void scheduler_process(bool hw_interrupt);
00161 
00162     // Callbacks from NFC stack
00163     static void s_polling_callback(nfc_transceiver_t *pTransceiver, nfc_err_t ret, void *pUserData);
00164 
00165     // Implementation of NFCControllerDriver::Delegate
00166     virtual void on_hw_interrupt();
00167 
00168     // Triggers when scheduler must be run again
00169     void on_timeout();
00170 
00171     NFCControllerDriver *_driver;
00172     events::EventQueue *_queue;
00173     nfc_transceiver_t *_transceiver;
00174     nfc_scheduler_t *_scheduler;
00175     Timer _timer;
00176     Timeout _timeout;
00177     Delegate *_delegate;
00178     bool _discovery_running;
00179     Span<uint8_t>  _ndef_buffer;
00180 };
00181 
00182 /**
00183  * @}
00184  */
00185 
00186 } // namespace nfc
00187 } // namespace mbed
00188 
00189 #endif