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 /** @addtogroup nfc
00035  * @{
00036  */
00037 
00038 class NFCRemoteInitiator;
00039 class NFCRemoteTarget;
00040 class NFCControllerDriver;
00041 
00042 /**
00043  * This class represents a NFC Controller.
00044  *
00045  * A controller can be in one of three different states:
00046  *  * Idle/sleep state
00047  *  * Discovery state: The controller tries to discover a remote endpoint (initiator or target)
00048  *  * Connected state: The controller exchanges data with an endpoint (initiator or target)
00049  *
00050  * A NFCController instance needs to be initialized with a NFCControllerDriver instance which abstracts the specific controller being used.
00051  * A delegate needs to be set by the user to receive discovery events.
00052  */
00053 class NFCController : private NFCControllerDriver::Delegate {
00054 public:
00055 
00056     /**
00057      * The NFCController delegate. Users of the NFCController class need to implement this delegate's methods to receive events.
00058      */
00059     struct Delegate {
00060         /**
00061          * A enumeration of causes for the discovery process terminating.
00062          */
00063         enum nfc_discovery_terminated_reason_t {
00064             nfc_discovery_terminated_completed = 0, ///< Process completed, at least one endpoint was discovered
00065             nfc_discovery_terminated_canceled, ///< Process was canceled by the user
00066             nfc_discovery_terminated_rf_error ///< An unexpected error was encountered during an exchange on the air interface
00067         };
00068 
00069         /**
00070          * The discovery process terminated.
00071          * @param[in] reason the cause for the termination
00072          */
00073         virtual void on_discovery_terminated(nfc_discovery_terminated_reason_t reason) {}
00074 
00075         /**
00076          * A remote initiator was discovered (the local controller is in target mode).
00077          * @param[in] nfc_initiator the NFCRemoteInitiator instance
00078          */
00079         virtual void on_nfc_initiator_discovered(const SharedPtr<NFCRemoteInitiator> &nfc_initiator) {}
00080 
00081         /**
00082          * A remote target was discovered (the local controller is in initiator mode).
00083          * @param[in] nfc_target the NFCRemoteTarget instance
00084          */
00085         virtual void on_nfc_target_discovered(const SharedPtr<NFCRemoteTarget> &nfc_target) {}
00086 
00087     protected:
00088         ~Delegate() { }
00089     };
00090 
00091     /**
00092      * Construct a NFCController instance.
00093      *
00094      * @param[in] driver a pointer to a NFCControllerDriver instance
00095      * @param[in] queue a pointer to the events queue to use
00096      * @param[in] ndef_buffer a bytes array used to store NDEF messages
00097      */
00098     NFCController(NFCControllerDriver *driver, events::EventQueue *queue, const Span<uint8_t>  &ndef_buffer);
00099 
00100     /**
00101      * Initialize the NFC controller
00102      *
00103      * This method must be called before any other method call.
00104      *
00105      * @return NFC_OK, or an error.
00106      */
00107     nfc_err_t initialize();
00108 
00109     /**
00110      * Set the delegate that will receive events generated by this controller.
00111      *
00112      * @param[in] delegate the delegate instance to use
00113      */
00114     void set_delegate(Delegate *delegate);
00115 
00116     /**
00117      * Get the list of RF protocols supported by this controller.
00118      *
00119      * @return a bitmask of RF protocols supported by the controller
00120      */
00121     nfc_rf_protocols_bitmask_t get_supported_rf_protocols() const;
00122 
00123     /**
00124      * Set the list of RF protocols to look for during discovery.
00125      *
00126      * @param[in] rf_protocols the relevant bitmask
00127      * @return NFC_OK on success, or
00128      *  NFC_ERR_UNSUPPORTED if a protocol is not supported by the controller,
00129      *  NFC_ERR_BUSY if the discovery process is already running
00130      */
00131     nfc_err_t configure_rf_protocols(nfc_rf_protocols_bitmask_t rf_protocols);
00132 
00133     /**
00134      * Start the discovery process using the protocols configured previously.
00135      *
00136      * If remote endpoints are connected when this is called, they will be disconnected.
00137      *
00138      * @return NFC_OK on success, or
00139      *  NFC_ERR_BUSY if the discovery process is already running
00140      */
00141     nfc_err_t start_discovery();
00142 
00143     /**
00144      * Cancel/stop a running discovery process.
00145      *
00146      * @return NFC_OK
00147      */
00148     nfc_err_t cancel_discovery();
00149 
00150 private:
00151     // These two classes need to be friends to access the following transceiver() method
00152     friend class NFCRemoteEndpoint;
00153     friend class Type4RemoteInitiator;
00154     nfc_transceiver_t *transceiver() const;
00155 
00156     void polling_callback(nfc_err_t ret);
00157 
00158     // NFC Stack scheduler
00159     void scheduler_process(bool hw_interrupt);
00160 
00161     // Callbacks from NFC stack
00162     static void s_polling_callback(nfc_transceiver_t *pTransceiver, nfc_err_t ret, void *pUserData);
00163 
00164     // Implementation of NFCControllerDriver::Delegate
00165     virtual void on_hw_interrupt();
00166 
00167     // Triggers when scheduler must be run again
00168     void on_timeout();
00169 
00170     NFCControllerDriver *_driver;
00171     events::EventQueue *_queue;
00172     nfc_transceiver_t *_transceiver;
00173     nfc_scheduler_t *_scheduler;
00174     Timer _timer;
00175     Timeout _timeout;
00176     Delegate *_delegate;
00177     bool _discovery_running;
00178     Span<uint8_t>  _ndef_buffer;
00179 };
00180 /** @}*/
00181 } // namespace nfc
00182 } // namespace mbed
00183 
00184 #endif