BAOS SDK v2  1.0.1
An SDK providing access to IP-BAOS devices through BAOS binary protocol version 2.x
BaosDevice.h
Go to the documentation of this file.
1 //
2 // Copyright (c) 2002-2023 WEINZIERL ENGINEERING GmbH
3 // All rights reserved.
4 //
5 // THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
6 // IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
7 // FITNESS FOR A PARTICULAR PURPOSE, TITLE AND NON-INFRINGEMENT. IN NO EVENT
8 // SHALL THE COPYRIGHT HOLDERS BE LIABLE FOR ANY DAMAGES OR OTHER LIABILITY,
9 // WHETHER IN CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
10 // WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE
11 //
12 
13 #ifndef __BAOSLIB_INTERFACE_H__
14 #define __BAOSLIB_INTERFACE_H__
15 
16 #include "baos/config.h"
17 
18 #include "BlockReader.h"
21 #include "baos/protocol/Defines.h"
22 
23 #include "wzcpp/features/algorithm/append.h"
24 #include "wzcpp/features/logging.h"
25 #include "wzcpp/features/utils/ByteArray.h"
26 #include "wzcpp/features/utils/Memory.h"
27 
29 #include <memory>
30 #include <optional>
31 #include <utility>
33 
39 namespace wz::baos
40 {
41 // Forward declaration
42 class BaosConnection;
43 using BaosConnection_UPtr = std::unique_ptr<BaosConnection>;
44 
45 
46 /**************************************************
47  * BaosDevice
48  * ***********************************************/
49 
57 class BAOSLIB_EXPORT BaosDevice
58 {
59 public:
60  using ServerItemIndicationCb = std::function<void(
61  const protocol::ServerItems&)>;
62  using DatapointValueCb = std::function<void(
63  const protocol::DatapointValues&)>;
64 
65  BaosDevice() = default;
66  virtual ~BaosDevice() = default;
67 
68  virtual void close();
70  /************************ Information about the device ************************/
76 
83  DeviceStaticInfo getStaticInfo(bool reload = false);
84 
85 
93  DeviceConfigInfo getConfigInfo(bool reload = false);
94 
102  DeviceRuntimeInfo getRuntimeInfo(bool reload = false);
103 
111 
113 
114  /************************ Parameter bytes ***************************************/
120 
129  protocol::ParameterBytes getParameterBytes(std::uint16_t byteIndex = 1,
130  std::uint16_t numberOfBytes = UINT16_MAX,
131  bool reload = false);
132 
144 
145  /**************************** Datapoints *****************************************/
151  /*~~~~~~~~~~~~~~~~~~~~~~~~~~~ Datapoint configurations ~~~~~~~~~~~~~~~~~~~~~~~~~~*/
152 
161  std::optional<DatapointConfig> getDpConfiguration(std::uint16_t dpId = 1,
162  bool withDescStrings = true,
163  bool reload = false);
164 
174  DatapointConfigurations getDpConfigurations(std::uint16_t startDpId = 1,
175  std::uint16_t endDpId = UINT16_MAX,
176  bool withDescStrings = true,
177  bool reload = false);
178 
179 
189  /*~~~~~~~~~~~~~~~~~~~~~~~~~~~ Datapoint values ~~~~~~~~~~~~~~~~~~~~~~~~~~*/
190 
198  void setDpValue(std::uint16_t dpId,
199  Buffer dpData,
201 
208  void setDpValues(std::map<std::uint16_t, Buffer>&& values,
210 
216  void readDpValueFromBus(std::uint16_t dpId);
217 
223  void readDpValuesFromBus(std::vector<std::uint16_t>&& dpIds);
224 
225 
233  std::optional<protocol::DatapointValue> getDpValueRaw(std::uint16_t dpId, bool reload = false);
234 
242  template<class T>
243  std::optional<T> getDatapointValue(std::uint16_t dpId, bool reload = false)
244  {
245  auto value = getDpValueRaw(dpId);
246  if (value.has_value())
247  {
248  return T(value);
249  }
250  else
251  {
252  return {};
253  }
254  }
255 
263  protocol::DatapointValues getDpValuesRaw(std::vector<std::uint16_t> dpIds, bool reload = false);
264 
275  std::uint16_t startDpId,
276  std::uint16_t endDpId,
277  bool reload = false,
279 
291 
293  /*************************************** Configuration of this class *****************************/
294 
302 
311  bool enableCaching(bool state);
312 
318  bool isCachingEnabled() const
319  {
320  return config_.cacheEnabled;
321  };
322 
326  void clearCaches();
327 
333  bool wasCacheHit()
334  {
335  return cacheHit_;
336  }
337 
343  std::optional<DeviceMeta> getMetaInfo();
344 
354  void setMetaInfo(DeviceMeta&& meta);
355 
356 
357  /*************************************** Callbacks on events *************************************/
358 
363 
368 
369 
370  /************************************ Underlying BaosConnection *********************************/
371 
378 
380 
386  void setInternalConnection(BaosConnection_UPtr& conn)
387  {
388  baosCon_ = std::move(conn);
389  }
390 
397  BaosConnection& getInternalConnection()
398  {
399  if (!baosCon_)
400  {
401  throw WzSocketException(WZ_SL, "No internal connection available");
402  }
403  return *baosCon_;
404  }
406 
407 
408 protected:
414 
420  void onServerItemsUpdate(const protocol::ServerItems& serverItems);
421 
428 
434 
451 
463  template<class TGetter>
464  auto getElements(std::uint16_t start, std::uint16_t count, std::uint16_t maxLengthElement, TGetter cb)
465  {
466  if (config_.blockReadEnabled)
467  {
468  // Get current buffer size
469  if (!deviceInfoLoaded_)
470  {
471  getConfigInfo();
472  }
473  assert(configInfo_.currentBufferSize > 16);
474  std::uint16_t payloadAvailSize = (configInfo_.currentBufferSize - 16) /
475  maxLengthElement; // 10 Byte knxip header and 6 bytes BAOS header and
476  // maxLengthElement bytes per payload element
477  assert(payloadAvailSize > 0);
478  return utility::BlockReader::read(start, count, payloadAvailSize, cb);
479  }
480  else
481  {
482  return cb(start, count);
483  }
484  }
485 
486 
487 protected:
490  std::optional<DeviceMeta> metaInfo_;
491 
492  bool cacheHit_{false};
493 
494  // cached variables
495  bool deviceInfoLoaded_{false};
499 
500  std::map<std::uint16_t, Buffer> dpCache_;
501  bool dpCacheFilled_{false};
503 
505 
506  std::vector<ServerItemIndicationCb> serverItemsCallbacks;
507  std::vector<DatapointValueCb> dpValueCallbacks;
508 
510 
511  WZLOGGER("BaosDevice", LVL_DEBUG);
512 };
513 
514 } // namespace wz::baos
515 
516 #endif // __BAOSLIB_INTERFACE_H__
Specific datatypes used by the device classes.
Provides the structures for additional meta information regarding the various devices.
Global BAOS protocol defines and types.
Represents a connection to a BAOS device.
Definition: BaosConnection.h:69
This class represents a BAOS device.
Definition: BaosDevice.h:58
DeviceStaticInfo getStaticInfo(bool reload=false)
Get the information about a connected BAOS device that is never changed. Like serial number.
auto getElements(std::uint16_t start, std::uint16_t count, std::uint16_t maxLengthElement, TGetter cb)
Helper function to retrieve the elements(datapoint descriptions, string and parameter bytes) from the...
Definition: BaosDevice.h:464
protocol::ParameterBytes getParameterBytes(std::uint16_t byteIndex=1, std::uint16_t numberOfBytes=UINT16_MAX, bool reload=false)
Get the parameter bytes If caching is enabled, the result of this call will be stored in cache.
DeviceConfigInfo getConfigInfo(bool reload=false)
Get the information about a connected BAOS device that is typically only changed during configuration...
BaosConnection_UPtr baosCon_
The internal connection used to coomunicate with the BAOS device.
Definition: BaosDevice.h:509
DeviceRuntimeInfo getRuntimeInfo(bool reload=false)
Get the information about a connected BAOS device that may change during runtime.
protocol::DatapointValues getDpValuesRaw(std::vector< std::uint16_t > dpIds, bool reload=false)
Get the values of multiple datapoints as raw bytes.
DeviceRuntimeInfo runtimeInfo_
Runtime information about the BAOS device.
Definition: BaosDevice.h:498
virtual void close()
DeviceConfigInfo configInfo_
Config information about the BAOS device.
Definition: BaosDevice.h:497
bool enableCaching(bool state)
Enable or Disable the internal caching for datapoint and parameter bytes.
std::vector< DatapointValueCb > dpValueCallbacks
List of registered callback functions.
Definition: BaosDevice.h:507
void onServerItemsUpdate(const protocol::ServerItems &serverItems)
An update may occur as a response to a getServerItem request or via an indication.
void setDpValues(std::map< std::uint16_t, Buffer > &&values, protocol::DatapointSetCommand command=protocol::DatapointSetCommand::SetNewValueAndSendOnBus)
Set the value of multiple datapoints.
std::vector< ServerItemIndicationCb > serverItemsCallbacks
List of registered callback functions.
Definition: BaosDevice.h:506
std::map< std::uint16_t, Buffer > dpCache_
Cache to hold the last valid values for the datapoints.
Definition: BaosDevice.h:500
void readDpValueFromBus(std::uint16_t dpId)
Triggers a read request for the datapoint on the bus.
std::optional< DeviceMeta > metaInfo_
Meta information set by the user.
Definition: BaosDevice.h:490
DatapointConfigurations dpConfig_
Configuration information about the BAOS datapoints.
Definition: BaosDevice.h:504
void setBoolServerItem(protocol::ServerItemId id, bool value)
Set the a bool value to a server item.
std::function< void(const protocol::DatapointValues &)> DatapointValueCb
The function signature for the callback on changed datapoint values.
Definition: BaosDevice.h:63
protocol::DatapointValues getDpValuesRaw(std::uint16_t startDpId, std::uint16_t endDpId, bool reload=false, protocol::DatapointValueFilter filter=protocol::DatapointValueFilter::VALID)
Get the values of multiple datapoints as raw bytes.
std::optional< T > getDatapointValue(std::uint16_t dpId, bool reload=false)
Get the value of a single datapoint as type T.
Definition: BaosDevice.h:243
std::function< void(const protocol::ServerItems &)> ServerItemIndicationCb
The function signature for the callback on changed server items.
Definition: BaosDevice.h:61
void readDpValuesFromBus(std::vector< std::uint16_t > &&dpIds)
Triggers read requests for a set of datapoints on the bus.
void clearDeviceConfigs()
Reset the device information, retrieved from serveritems and meta data to their default values.
protocol::DatapointValues getAllDpValuesRaw(bool reload=false, protocol::DatapointValueFilter filter=protocol::DatapointValueFilter::VALID)
Load all the datapoint values and cache them.
void onDpValueUpdate(const protocol::DatapointValueStates &dpValueStates)
An update may occur as a response to a getDatapointValue request or via an indication.
protocol::ParameterBytes paramBytes_
Cache to hold the parameter bytes.
Definition: BaosDevice.h:502
void clearCaches()
Clear the internal caches for datapoints and parameter bytes.
DatapointConfigurations getDpConfigurations(std::uint16_t startDpId=1, std::uint16_t endDpId=UINT16_MAX, bool withDescStrings=true, bool reload=false)
Get the datapoint configurations If caching is enabled, the result of this call will be stored in cac...
protocol::ParameterBytes getAllParameterBytes(bool reload=false)
Load all the parameter bytes and cache them.
std::optional< protocol::DatapointValue > getDpValueRaw(std::uint16_t dpId, bool reload=false)
Get the value of a single datapoint as raw bytes.
DatapointConfigurations getAllDpConfigurations(bool reload=false)
Load all the datapoint configurations and cache them.
std::optional< DeviceMeta > getMetaInfo()
Get the metadata set for this device if available.
void setMetaInfo(DeviceMeta &&meta)
Set the meta data for this device.
virtual BaosConnection_UPtr getConnection()=0
Pure virtual function to get a BaosConnection to the device.
bool wasCacheHit()
Returns if the last request could be statisfied by the cache or not.
Definition: BaosDevice.h:333
void ensureConnection()
Make sure that a connection to the underlying device exists and is open or throw an exception if this...
bool isCachingEnabled() const
Return the current caching state.
Definition: BaosDevice.h:318
protocol::ServerItems getAllServerItems()
Get all the serveritem values from the device.
ServerItemReadStrategy setServerItemReadStrategy(ServerItemReadStrategy strategy)
Set the strategy to use for reading the serveritems.
WZLOGGER("BaosDevice", LVL_DEBUG)
The name for the logger of this class.
void registerServerItemCallback(ServerItemIndicationCb)
Register one or more functions ascallbacks, invoked on serveritem changes.
DeviceStaticInfo staticInfo_
Static information about the BAOS device.
Definition: BaosDevice.h:496
void setDpValue(std::uint16_t dpId, Buffer dpData, protocol::DatapointSetCommand command=protocol::DatapointSetCommand::SetNewValueAndSendOnBus)
Set the value of a single datapoint.
void registerDPValueCallback(DatapointValueCb)
Register one or more functions ascallbacks, invoked on datapoint value changes.
std::optional< DatapointConfig > getDpConfiguration(std::uint16_t dpId=1, bool withDescStrings=true, bool reload=false)
Get the datapoint configuration of a single datapoint If caching is enabled, the result of this call ...
Global types and configuration for the whole SDK.
std::map< std::uint16_t, DatapointValue > DatapointValues
A map with datapoint ids as keys and DatapointValue as values.
Definition: Defines.h:35
ServerItemId
An enum class to provide conveniant names to the serveritem ids.
Definition: Defines.h:198
std::map< std::uint16_t, DatapointValueState > DatapointValueStates
Definition: Defines.h:588
DatapointSetCommand
Setting a datapoint value there are different modes supported. This enum class gives those modes name...
Definition: Defines.h:60
@ SetNewValueAndSendOnBus
The default: Set the new value in the object server and send it to the bus.
std::vector< std::uint8_t > ParameterBytes
Strong type for a list of parameter bytes.
Definition: Defines.h:616
DatapointValueFilter
Requested datapoint value can be filtered by this criteria.
Definition: Defines.h:50
std::vector< ServerItem > ServerItems
Type for a list of ServerItems.
Definition: Defines.h:421
Global BAOS sdk namespace.
Definition: config.h:62
std::vector< std::uint8_t > Buffer
An alias type for a byte buffer.
Definition: config.h:64
std::map< std::uint16_t, DatapointConfig > DatapointConfigurations
Definition: BaosDeviceDataTypes.h:212
std::unique_ptr< BaosConnection > BaosConnection_UPtr
Alias for a std::unique pointer of a BaosConnection.
Definition: BaosDevice.h:43
ServerItemReadStrategy
Strategy type on how to handle reading the serveritems.
Definition: BaosDeviceDataTypes.h:216
Configuration options for the cpp device class behaviour.
Definition: BaosDeviceDataTypes.h:226
A collection of fields representing those serveritems which may change if the configuration of the de...
Definition: BaosDeviceDataTypes.h:94
Meta information about a device group, which is required be the device class.
Definition: BaosDevicesMeta.h:98
A collection of fields representing those serveritems which may change during "normal" operation of t...
Definition: BaosDeviceDataTypes.h:174
A collection of fields representing those serveritems which won't ever change in a device.
Definition: BaosDeviceDataTypes.h:49