Line data Source code
1 : /*
2 : *
3 : * Copyright (c) 2020-2021 Project CHIP Authors
4 : * Copyright (c) 2014-2017 Nest Labs, Inc.
5 : *
6 : * Licensed under the Apache License, Version 2.0 (the "License");
7 : * you may not use this file except in compliance with the License.
8 : * You may obtain a copy of the License at
9 : *
10 : * http://www.apache.org/licenses/LICENSE-2.0
11 : *
12 : * Unless required by applicable law or agreed to in writing, software
13 : * distributed under the License is distributed on an "AS IS" BASIS,
14 : * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
15 : * See the License for the specific language governing permissions and
16 : * limitations under the License.
17 : */
18 :
19 : /**
20 : * @file
21 : * This file defines a Bluetooth Low Energy (BLE) connection
22 : * endpoint abstraction for the byte-streaming,
23 : * connection-oriented CHIP over Bluetooth Low Energy (CHIPoBLE)
24 : * Bluetooth Transport Protocol (BTP).
25 : *
26 : */
27 :
28 : #pragma once
29 :
30 : #ifndef _CHIP_BLE_BLE_H
31 : #error "Please include <ble/Ble.h> instead!"
32 : #endif
33 :
34 : #include <cstdint>
35 :
36 : #include <lib/core/CHIPError.h>
37 : #include <lib/support/BitFlags.h>
38 : #include <lib/support/DLLUtil.h>
39 : #include <system/SystemLayer.h>
40 : #include <system/SystemPacketBuffer.h>
41 :
42 : #include "BleConnectionDelegate.h"
43 : #include "BleLayerDelegate.h"
44 : #include "BlePlatformDelegate.h"
45 : #include "BleRole.h"
46 : #include "BtpEngine.h"
47 :
48 : namespace chip {
49 : namespace Ble {
50 :
51 : using ::chip::System::PacketBufferHandle;
52 :
53 : enum
54 : {
55 : kBleCloseFlag_SuppressCallback = 0x01,
56 : kBleCloseFlag_AbortTransmission = 0x02
57 : };
58 :
59 : // Forward declarations
60 : class BleLayer;
61 : class BleEndPointPool;
62 :
63 : class DLL_EXPORT BLEEndPoint
64 : {
65 : friend class BleLayer;
66 : friend class BleEndPointPool;
67 :
68 : public:
69 : typedef uint64_t AlignT;
70 :
71 : // Public data members:
72 : enum
73 : {
74 : kState_Ready = 0,
75 : kState_Connecting = 1,
76 : kState_Aborting = 2,
77 : kState_Connected = 3,
78 : kState_Closing = 4,
79 : kState_Closed = 5
80 : } mState; // [READ-ONLY] End point connection state. Refers to state of CHIP over
81 : // BLE transport protocol connection, not of underlying BLE connection.
82 :
83 : // Public function pointers:
84 : typedef void (*OnConnectCompleteFunct)(BLEEndPoint * endPoint, CHIP_ERROR err);
85 : OnConnectCompleteFunct OnConnectComplete;
86 :
87 : typedef void (*OnMessageReceivedFunct)(BLEEndPoint * endPoint, PacketBufferHandle && msg);
88 : OnMessageReceivedFunct OnMessageReceived;
89 :
90 : typedef void (*OnConnectionClosedFunct)(BLEEndPoint * endPoint, CHIP_ERROR err);
91 : OnConnectionClosedFunct OnConnectionClosed;
92 :
93 : // Public functions:
94 : CHIP_ERROR Send(PacketBufferHandle && data);
95 : CHIP_ERROR Receive(PacketBufferHandle && data);
96 : CHIP_ERROR StartConnect();
97 :
98 : bool IsUnsubscribePending() const;
99 1 : bool ConnectionObjectIs(BLE_CONNECTION_OBJECT connObj) { return connObj == mConnObj; }
100 : void Close();
101 : void Abort();
102 :
103 : private:
104 : BleLayer * mBle; ///< [READ-ONLY] Pointer to the BleLayer object that owns this object.
105 : BleLayerDelegate * mBleTransport;
106 :
107 : uint32_t mRefCount;
108 :
109 : void AddRef();
110 : void Release();
111 :
112 : // Private data members:
113 : enum class ConnectionStateFlag : uint8_t
114 : {
115 : kAutoClose = 0x01, // End point should close underlying BLE conn on BTP close.
116 : kCapabilitiesConfReceived = 0x02, // GATT confirmation received for sent capabilities req/resp.
117 : kCapabilitiesMsgReceived = 0x04, // Capabilities request or response message received.
118 : kDidBeginSubscribe = 0x08, // GATT subscribe request sent; must unsubscribe on close.
119 : kStandAloneAckInFlight = 0x10, // Stand-alone ack in flight, awaiting GATT confirmation.
120 : kGattOperationInFlight = 0x20 // GATT write, indication, subscribe, or unsubscribe in flight,
121 : // awaiting GATT confirmation.
122 : };
123 :
124 : enum class TimerStateFlag : uint8_t
125 : {
126 : kConnectTimerRunning = 0x01, // BTP connect completion timer running.
127 : kReceiveConnectionTimerRunning = 0x02, // BTP receive connection completion timer running.
128 : kAckReceivedTimerRunning = 0x04, // Ack received timer running due to unacked sent fragment.
129 : kSendAckTimerRunning = 0x08, // Send ack timer running; indicates pending ack to send.
130 : kUnsubscribeTimerRunning = 0x10, // Unsubscribe completion timer running.
131 : };
132 :
133 : // BLE connection to which an end point is uniquely bound. Type BLE_CONNECTION_OBJECT is defined by the platform or
134 : // void* by default. This object is passed back to the platform delegate with each call to send traffic over or
135 : // modify the state of the underlying BLE connection.
136 : BLE_CONNECTION_OBJECT mConnObj;
137 :
138 : // Queue of outgoing messages to send when current BtpEngine transmission completes.
139 : //
140 : // Re-used during connection setup to cache capabilities request and response payloads; payloads are freed when
141 : // connection is established.
142 : PacketBufferHandle mSendQueue;
143 :
144 : // Pending stand-alone BTP acknowledgement. Pre-empts regular send queue or fragmented message transmission in
145 : // progress.
146 : PacketBufferHandle mAckToSend;
147 :
148 : BtpEngine mBtpEngine;
149 : BleRole mRole;
150 : BitFlags<ConnectionStateFlag> mConnStateFlags;
151 : BitFlags<TimerStateFlag> mTimerStateFlags;
152 : SequenceNumber_t mLocalReceiveWindowSize;
153 : SequenceNumber_t mRemoteReceiveWindowSize;
154 : SequenceNumber_t mReceiveWindowMaxSize;
155 :
156 : // Private functions:
157 : BLEEndPoint() = delete;
158 : ~BLEEndPoint() = delete;
159 :
160 : CHIP_ERROR Init(BleLayer * bleLayer, BLE_CONNECTION_OBJECT connObj, BleRole role, bool autoClose);
161 : bool IsConnected(uint8_t state) const;
162 : void DoClose(uint8_t flags, CHIP_ERROR err);
163 :
164 : // Transmit path:
165 : CHIP_ERROR DriveSending();
166 : CHIP_ERROR DriveStandAloneAck();
167 : bool PrepareNextFragment(PacketBufferHandle && data, bool & sentAck);
168 : CHIP_ERROR SendNextMessage();
169 : CHIP_ERROR ContinueMessageSend();
170 : CHIP_ERROR DoSendStandAloneAck();
171 : CHIP_ERROR SendCharacteristic(PacketBufferHandle && buf);
172 : CHIP_ERROR SendIndication(PacketBufferHandle && buf);
173 : CHIP_ERROR SendWrite(PacketBufferHandle && buf);
174 :
175 : // Receive path:
176 : CHIP_ERROR HandleConnectComplete();
177 : CHIP_ERROR HandleReceiveConnectionComplete();
178 : void HandleSubscribeReceived();
179 : void HandleSubscribeComplete();
180 : void HandleUnsubscribeComplete();
181 : CHIP_ERROR HandleGattSendConfirmationReceived();
182 : CHIP_ERROR HandleHandshakeConfirmationReceived();
183 : CHIP_ERROR HandleFragmentConfirmationReceived();
184 : CHIP_ERROR HandleCapabilitiesRequestReceived(PacketBufferHandle && data);
185 : CHIP_ERROR HandleCapabilitiesResponseReceived(PacketBufferHandle && data);
186 : SequenceNumber_t AdjustRemoteReceiveWindow(SequenceNumber_t lastReceivedAck, SequenceNumber_t maxRemoteWindowSize,
187 : SequenceNumber_t newestUnackedSentSeqNum);
188 :
189 : // Timer control functions:
190 : CHIP_ERROR StartConnectTimer(); // Start connect timer.
191 : CHIP_ERROR StartReceiveConnectionTimer(); // Start receive connection timer.
192 : CHIP_ERROR StartAckReceivedTimer(); // Start ack-received timer if it's not already running.
193 : CHIP_ERROR RestartAckReceivedTimer(); // Restart ack-received timer.
194 : CHIP_ERROR StartSendAckTimer(); // Start send-ack timer if it's not already running.
195 : CHIP_ERROR StartUnsubscribeTimer();
196 : void StopConnectTimer(); // Stop connect timer.
197 : void StopReceiveConnectionTimer(); // Stop receive connection timer.
198 : void StopAckReceivedTimer(); // Stop ack-received timer.
199 : void StopSendAckTimer(); // Stop send-ack timer.
200 : void StopUnsubscribeTimer(); // Stop unsubscribe timer.
201 :
202 : // Timer expired callbacks:
203 : static void HandleConnectTimeout(chip::System::Layer * systemLayer, void * appState);
204 : static void HandleReceiveConnectionTimeout(chip::System::Layer * systemLayer, void * appState);
205 : static void HandleAckReceivedTimeout(chip::System::Layer * systemLayer, void * appState);
206 : static void HandleSendAckTimeout(chip::System::Layer * systemLayer, void * appState);
207 : static void HandleUnsubscribeTimeout(chip::System::Layer * systemLayer, void * appState);
208 :
209 : // Close functions:
210 : void DoCloseCallback(uint8_t state, uint8_t flags, CHIP_ERROR err);
211 : void FinalizeClose(uint8_t state, uint8_t flags, CHIP_ERROR err);
212 : void ReleaseBleConnection();
213 : void Free();
214 : void FreeBtpEngine();
215 :
216 : void QueueTx(PacketBufferHandle && data, PacketType_t type);
217 : };
218 :
219 : } /* namespace Ble */
220 : } /* namespace chip */
|
