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 : // Public data members:
70 : enum
71 : {
72 : kState_Ready = 0,
73 : kState_Connecting = 1,
74 : kState_Aborting = 2,
75 : kState_Connected = 3,
76 : kState_Closing = 4,
77 : kState_Closed = 5
78 : } mState; // [READ-ONLY] End point connection state. Refers to state of CHIP over
79 : // BLE transport protocol connection, not of underlying BLE connection.
80 :
81 : // Public function pointers:
82 : typedef void (*OnConnectCompleteFunct)(BLEEndPoint * endPoint, CHIP_ERROR err);
83 : OnConnectCompleteFunct OnConnectComplete;
84 :
85 : typedef void (*OnMessageReceivedFunct)(BLEEndPoint * endPoint, PacketBufferHandle && msg);
86 : OnMessageReceivedFunct OnMessageReceived;
87 :
88 : typedef void (*OnConnectionClosedFunct)(BLEEndPoint * endPoint, CHIP_ERROR err);
89 : OnConnectionClosedFunct OnConnectionClosed;
90 :
91 : // Public functions:
92 : CHIP_ERROR Send(PacketBufferHandle && data);
93 : CHIP_ERROR Receive(PacketBufferHandle && data);
94 : CHIP_ERROR StartConnect();
95 :
96 : bool IsUnsubscribePending() const;
97 1 : bool ConnectionObjectIs(BLE_CONNECTION_OBJECT connObj) { return connObj == mConnObj; }
98 : void Close();
99 : void Abort();
100 :
101 : private:
102 : BleLayer * mBle; ///< [READ-ONLY] Pointer to the BleLayer object that owns this object.
103 : BleLayerDelegate * mBleTransport;
104 :
105 : uint32_t mRefCount;
106 :
107 : void AddRef();
108 : void Release();
109 :
110 : // Private data members:
111 : enum class ConnectionStateFlag : uint8_t
112 : {
113 : kAutoClose = 0x01, // End point should close underlying BLE conn on BTP close.
114 : kCapabilitiesConfReceived = 0x02, // GATT confirmation received for sent capabilities req/resp.
115 : kCapabilitiesMsgReceived = 0x04, // Capabilities request or response message received.
116 : kDidBeginSubscribe = 0x08, // GATT subscribe request sent; must unsubscribe on close.
117 : kStandAloneAckInFlight = 0x10, // Stand-alone ack in flight, awaiting GATT confirmation.
118 : kGattOperationInFlight = 0x20 // GATT write, indication, subscribe, or unsubscribe in flight,
119 : // awaiting GATT confirmation.
120 : };
121 :
122 : enum class TimerStateFlag : uint8_t
123 : {
124 : kConnectTimerRunning = 0x01, // BTP connect completion timer running.
125 : kReceiveConnectionTimerRunning = 0x02, // BTP receive connection completion timer running.
126 : kAckReceivedTimerRunning = 0x04, // Ack received timer running due to unacked sent fragment.
127 : kSendAckTimerRunning = 0x08, // Send ack timer running; indicates pending ack to send.
128 : kUnsubscribeTimerRunning = 0x10, // Unsubscribe completion timer running.
129 : };
130 :
131 : // BLE connection to which an end point is uniquely bound. Type BLE_CONNECTION_OBJECT is defined by the platform or
132 : // void* by default. This object is passed back to the platform delegate with each call to send traffic over or
133 : // modify the state of the underlying BLE connection.
134 : BLE_CONNECTION_OBJECT mConnObj;
135 :
136 : // Queue of outgoing messages to send when current BtpEngine transmission completes.
137 : //
138 : // Re-used during connection setup to cache capabilities request and response payloads; payloads are freed when
139 : // connection is established.
140 : PacketBufferHandle mSendQueue;
141 :
142 : // Pending stand-alone BTP acknowledgement. Pre-empts regular send queue or fragmented message transmission in
143 : // progress.
144 : PacketBufferHandle mAckToSend;
145 :
146 : BtpEngine mBtpEngine;
147 : BleRole mRole;
148 : BitFlags<ConnectionStateFlag> mConnStateFlags;
149 : BitFlags<TimerStateFlag> mTimerStateFlags;
150 : SequenceNumber_t mLocalReceiveWindowSize;
151 : SequenceNumber_t mRemoteReceiveWindowSize;
152 : SequenceNumber_t mReceiveWindowMaxSize;
153 :
154 : // Private functions:
155 : BLEEndPoint() = delete;
156 : ~BLEEndPoint() = delete;
157 :
158 : CHIP_ERROR Init(BleLayer * bleLayer, BLE_CONNECTION_OBJECT connObj, BleRole role, bool autoClose);
159 : bool IsConnected(uint8_t state) const;
160 : void DoClose(uint8_t flags, CHIP_ERROR err);
161 :
162 : // Transmit path:
163 : CHIP_ERROR DriveSending();
164 : CHIP_ERROR DriveStandAloneAck();
165 : bool PrepareNextFragment(PacketBufferHandle && data, bool & sentAck);
166 : CHIP_ERROR SendNextMessage();
167 : CHIP_ERROR ContinueMessageSend();
168 : CHIP_ERROR DoSendStandAloneAck();
169 : CHIP_ERROR SendCharacteristic(PacketBufferHandle && buf);
170 : CHIP_ERROR SendIndication(PacketBufferHandle && buf);
171 : CHIP_ERROR SendWrite(PacketBufferHandle && buf);
172 :
173 : // Receive path:
174 : CHIP_ERROR HandleConnectComplete();
175 : CHIP_ERROR HandleReceiveConnectionComplete();
176 : void HandleSubscribeReceived();
177 : void HandleSubscribeComplete();
178 : void HandleUnsubscribeComplete();
179 : CHIP_ERROR HandleGattSendConfirmationReceived();
180 : CHIP_ERROR HandleHandshakeConfirmationReceived();
181 : CHIP_ERROR HandleFragmentConfirmationReceived();
182 : CHIP_ERROR HandleCapabilitiesRequestReceived(PacketBufferHandle && data);
183 : CHIP_ERROR HandleCapabilitiesResponseReceived(PacketBufferHandle && data);
184 : SequenceNumber_t AdjustRemoteReceiveWindow(SequenceNumber_t lastReceivedAck, SequenceNumber_t maxRemoteWindowSize,
185 : SequenceNumber_t newestUnackedSentSeqNum);
186 :
187 : // Timer control functions:
188 : CHIP_ERROR StartConnectTimer(); // Start connect timer.
189 : CHIP_ERROR StartReceiveConnectionTimer(); // Start receive connection timer.
190 : CHIP_ERROR StartAckReceivedTimer(); // Start ack-received timer if it's not already running.
191 : CHIP_ERROR RestartAckReceivedTimer(); // Restart ack-received timer.
192 : CHIP_ERROR StartSendAckTimer(); // Start send-ack timer if it's not already running.
193 : CHIP_ERROR StartUnsubscribeTimer();
194 : void StopConnectTimer(); // Stop connect timer.
195 : void StopReceiveConnectionTimer(); // Stop receive connection timer.
196 : void StopAckReceivedTimer(); // Stop ack-received timer.
197 : void StopSendAckTimer(); // Stop send-ack timer.
198 : void StopUnsubscribeTimer(); // Stop unsubscribe timer.
199 :
200 : // Timer expired callbacks:
201 : static void HandleConnectTimeout(chip::System::Layer * systemLayer, void * appState);
202 : static void HandleReceiveConnectionTimeout(chip::System::Layer * systemLayer, void * appState);
203 : static void HandleAckReceivedTimeout(chip::System::Layer * systemLayer, void * appState);
204 : static void HandleSendAckTimeout(chip::System::Layer * systemLayer, void * appState);
205 : static void HandleUnsubscribeTimeout(chip::System::Layer * systemLayer, void * appState);
206 :
207 : // Close functions:
208 : void DoCloseCallback(uint8_t state, uint8_t flags, CHIP_ERROR err);
209 : void FinalizeClose(uint8_t state, uint8_t flags, CHIP_ERROR err);
210 : void ReleaseBleConnection();
211 : void Free();
212 : void FreeBtpEngine();
213 :
214 : void QueueTx(PacketBufferHandle && data, PacketType_t type);
215 : };
216 :
217 : } /* namespace Ble */
218 : } /* namespace chip */
|
