diff options
Diffstat (limited to 'src/components/policy/policy_external/doc')
45 files changed, 1073 insertions, 0 deletions
diff --git a/src/components/policy/policy_external/doc/doxygen/components/AppMgr/index.txt b/src/components/policy/policy_external/doc/doxygen/components/AppMgr/index.txt new file mode 100644 index 0000000000..17584b09e1 --- /dev/null +++ b/src/components/policy/policy_external/doc/doxygen/components/AppMgr/index.txt @@ -0,0 +1,5 @@ +/*! \page components_appmgr App Manager + +Here will be information about App Manager component + +*/
\ No newline at end of file diff --git a/src/components/policy/policy_external/doc/doxygen/components/HMI/index.txt b/src/components/policy/policy_external/doc/doxygen/components/HMI/index.txt new file mode 100644 index 0000000000..361763118d --- /dev/null +++ b/src/components/policy/policy_external/doc/doxygen/components/HMI/index.txt @@ -0,0 +1,5 @@ +/*! \page components_hmi HMI + +Here will be information about HMI component + +*/
\ No newline at end of file diff --git a/src/components/policy/policy_external/doc/doxygen/components/JSONHandler/Formatters/index.txt b/src/components/policy/policy_external/doc/doxygen/components/JSONHandler/Formatters/index.txt new file mode 100644 index 0000000000..9854b88d5f --- /dev/null +++ b/src/components/policy/policy_external/doc/doxygen/components/JSONHandler/Formatters/index.txt @@ -0,0 +1,9 @@ +/*! \page components_jsonhandler_formatters Smart Objects Formatters + +In order to create JSON string representation from Smart Object or create Smart Object data structure from JSON string representation JSON Handler component has special classes called formatters. + +The interface of formatter is quite simple and defined by NsSmartDeviceLink::NsJSONHandler::Formatters::CFormatterJsonBase class. Actually it has two methods - NsSmartDeviceLink::NsJSONHandler::Formatters::CFormatterJsonBase::objToJsonValue to convert JSON string to object and NsSmartDeviceLink::NsJSONHandler::Formatters::CFormatterJsonBase::jsonValueToObj to create JSON string from object. + +Current implementation has two different implementations of NsSmartDeviceLink::NsJSONHandler::Formatters::CFormatterJsonBase class: NsSmartDeviceLink::NsJSONHandler::Formatters::CFormatterJsonALRPCv1 for ALRPC.v1 and NsSmartDeviceLink::NsJSONHandler::Formatters::CFormatterJsonALRPCv2 for ALRPC.v2. These implementations handle specifics of each format. + +*/ diff --git a/src/components/policy/policy_external/doc/doxygen/components/JSONHandler/index.txt b/src/components/policy/policy_external/doc/doxygen/components/JSONHandler/index.txt new file mode 100644 index 0000000000..a65c8ddc7d --- /dev/null +++ b/src/components/policy/policy_external/doc/doxygen/components/JSONHandler/index.txt @@ -0,0 +1,8 @@ +/*! \page components_jsonhandler JSON Handler + +Here will be information about JSON Handler component + +Detailed information: + - \subpage components_jsonhandler_formatters "Smart Objects Formatters" + +*/ diff --git a/src/components/policy/policy_external/doc/doxygen/components/ProtocolHandler/index.txt b/src/components/policy/policy_external/doc/doxygen/components/ProtocolHandler/index.txt new file mode 100644 index 0000000000..c5b5ceb79c --- /dev/null +++ b/src/components/policy/policy_external/doc/doxygen/components/ProtocolHandler/index.txt @@ -0,0 +1,5 @@ +/*! \page components_protocolhandler Protocol Handler + +Here will be information about Protocol Handler component + +*/
\ No newline at end of file diff --git a/src/components/policy/policy_external/doc/doxygen/components/SmartObjects/Smart b/src/components/policy/policy_external/doc/doxygen/components/SmartObjects/Smart new file mode 100644 index 0000000000..e69de29bb2 --- /dev/null +++ b/src/components/policy/policy_external/doc/doxygen/components/SmartObjects/Smart diff --git a/src/components/policy/policy_external/doc/doxygen/components/SmartObjects/Smart Objects Types/Value representation.txt b/src/components/policy/policy_external/doc/doxygen/components/SmartObjects/Smart Objects Types/Value representation.txt new file mode 100644 index 0000000000..6505ae6f43 --- /dev/null +++ b/src/components/policy/policy_external/doc/doxygen/components/SmartObjects/Smart Objects Types/Value representation.txt @@ -0,0 +1,25 @@ +/*! \page components_smartobjects_types_repr Type value representation methods for SmartObjects + +As alternative to the type casts NsSmartDeviceLink::NsSmartObjects::CSmartObject class defines set of usable methods that allow to represent object values as desired type. Use of these methods may change code style and readability but functionally it completely similar to the type casts of Smart Objects. + +Example: + +<pre> +NsSmartDeviceLink::NsSmartObjects::CSmartObject obj; + +obj[0] = 1; + +obj[1] = true; + +obj[2] = 'a'; + +obj[3] = 3.14; + +int i = obj[0].asInt(); + +char c = obj[1].asChar(); + +double d = obj[2].asDouble(); +</pre> + +*/ diff --git a/src/components/policy/policy_external/doc/doxygen/components/SmartObjects/Smart Objects Types/index.txt b/src/components/policy/policy_external/doc/doxygen/components/SmartObjects/Smart Objects Types/index.txt new file mode 100644 index 0000000000..61ca201507 --- /dev/null +++ b/src/components/policy/policy_external/doc/doxygen/components/SmartObjects/Smart Objects Types/index.txt @@ -0,0 +1,9 @@ +/*! \page components_smartobjects_types Smart Objects Types + +Current implementation of Smart Objects contains definitions that allow working with every Smart Object +as variable of one of the basic types: bool, int, long, double, char, string (both as char* and std::string), array and map. + +There are two different ways to work with type values in SmartObjects: + - \subpage components_smartobjects_types_cast "Type cast for SmartObjects" + - \subpage components_smartobjects_types_repr "Type value representation methods for SmartObjects" +*/ diff --git a/src/components/policy/policy_external/doc/doxygen/components/SmartObjects/Smart Objects Validation/Schema Structure.txt b/src/components/policy/policy_external/doc/doxygen/components/SmartObjects/Smart Objects Validation/Schema Structure.txt new file mode 100644 index 0000000000..2e611f74b9 --- /dev/null +++ b/src/components/policy/policy_external/doc/doxygen/components/SmartObjects/Smart Objects Validation/Schema Structure.txt @@ -0,0 +1,101 @@ +/*! \page components_smartobjects_validation_items Schema structure: Schema Items + +In order to create new Schema (new object of class NsSmartDeviceLink::NsSmartObjects::CSmartSchema) client first must define all required Schema Items. Actually every Schema is a tree of respective Schema Items. Each node and leaf of that tree defines structural rules for some Smart Object data structure. + +Schema Items are represented as class hierarchy. The base class for all schema items is a NsSmartDeviceLink::NsSmartObjects::ISchemaItem class. This base class defines generic validation interface for Schema Items. + +To define special elements with always successful or always failing validation there are two special Schema Items: NsSmartDeviceLink::NsSmartObjects::CAlwaysTrueSchemaItem and NsSmartDeviceLink::NsSmartObjects::CAlwaysFalseSchemaItem. + +NsSmartDeviceLink::NsSmartObjects::CBoolSchemaItem is used for boolean values and has no parameters (only verifies that respective Smart Object is really has boolean value). + +NsSmartDeviceLink::NsSmartObjects::TNumberSchemaItem is template Schema Item that can be used for both integer and floating point values. In addition to the regular type verification it is possible to set min and max value range (these values are optional). + +NsSmartDeviceLink::NsSmartObjects::TEnumSchemaItem is used to verify any custom client-defined enum. + +NsSmartDeviceLink::NsSmartObjects::CStringSchemaItem is used to verify a string values. As optional parameter max length of the string could be set. + +NsSmartDeviceLink::NsSmartObjects::CArraySchemaItem provides validation for array. Can be used to verify special type and array size. + +NsSmartDeviceLink::NsSmartObjects::CObjectSchemaItem used in case when Schema Item includes another Schema Item. Actually this is only way to create tree node of new Schema. All other Schema Items will be used only to become leafs of validation tree. + +After creation of all required Schema Items (which is actually bind in the tree) it is possible to create Schema. +Schema can be initialized not only by raw root Schema Item, but also by special abstraction called Member (defined by NsSmartDeviceLink::NsSmartObjects::CObjectSchemaItem::SMember class). So every root item (NsSmartDeviceLink::NsSmartObjects::CObjectSchemaItem) firstly should be wrapped as Member. This wrapping process also allows to set "is mandatory" status for every Member. + + and pass root Schema Item as initial parameter to the new Schema. + +Currently Schemas are generated by the InterfaceGenerator. For supported ALRPC.v1/.v2 Schema has following structure: + +<pre> + +ROOT + | + -- PARAMS + | | + | -- FUNCTION_ID + | | + | -- MESSAGE_TYPE + | | + | -- CORRELATION_ID + | | + | -- PROTOCOL_VERSION + | | + | -- PROTOCOL_TYPE + | + -- MSG_PARAMS + | + -- OBJECT + | + -- (Actually contains function-specific leaf item) + ... +</pre> + +Example: + +<pre> + +// Function parameter success. +// +// true, if successful +// false, if failed +TSharedPtr<ISchemaItem> success_SchemaItem = CBoolSchemaItem::create(TSchemaItemParameter<bool>()); + +// Function parameter resultCode. +// +// See Result +TSharedPtr<ISchemaItem> resultCode_SchemaItem = TEnumSchemaItem<Result::eType>::create(resultCode_allowedEnumSubsetValues, TSchemaItemParameter<Result::eType>()); + +// Function parameter info. +// +// Provides additional human readable info regarding the result. +TSharedPtr<ISchemaItem> info_SchemaItem = CStringSchemaItem::create(TSchemaItemParameter<size_t>(1000), TSchemaItemParameter<std::string>()); + +schemaMembersMap["success"] = CObjectSchemaItem::SMember(success_SchemaItem, true); + +schemaMembersMap["resultCode"] = CObjectSchemaItem::SMember(resultCode_SchemaItem, true); + +schemaMembersMap["info"] = CObjectSchemaItem::SMember(info_SchemaItem, false); + +std::map<std::string, CObjectSchemaItem::SMember> paramsMembersMap; + +paramsMembersMap[NsSmartDeviceLink::NsJSONHandler::strings::S_FUNCTION_ID] = CObjectSchemaItem::SMember(TEnumSchemaItem<FunctionID::eType>::create(FunctionIDItems), true); + +paramsMembersMap[NsSmartDeviceLink::NsJSONHandler::strings::S_MESSAGE_TYPE] = CObjectSchemaItem::SMember(TEnumSchemaItem<messageType::eType>::create(MessageTypeItems), true); + +paramsMembersMap[NsSmartDeviceLink::NsJSONHandler::strings::S_CORRELATION_ID] = CObjectSchemaItem::SMember(TNumberSchemaItem<int>::create(), true); + +paramsMembersMap[NsSmartDeviceLink::NsJSONHandler::strings::S_PROTOCOL_VERSION] = CObjectSchemaItem::SMember(TNumberSchemaItem<int>::create(1, 2), true); + +paramsMembersMap[NsSmartDeviceLink::NsJSONHandler::strings::S_PROTOCOL_TYPE] = CObjectSchemaItem::SMember(TNumberSchemaItem<int>::create(), true); + +std::map<std::string, CObjectSchemaItem::SMember> rootMembersMap; + +rootMembersMap[NsSmartDeviceLink::NsJSONHandler::strings::S_MSG_PARAMS] = CObjectSchemaItem::SMember(CObjectSchemaItem::create(schemaMembersMap), true); + +rootMembersMap[NsSmartDeviceLink::NsJSONHandler::strings::S_PARAMS] = CObjectSchemaItem::SMember(CObjectSchemaItem::create(paramsMembersMap), true); + + +CSmartSchema(CObjectSchemaItem::create(rootMembersMap)); + +</pre> + +*/ diff --git a/src/components/policy/policy_external/doc/doxygen/components/SmartObjects/Smart Objects Validation/Validation.txt b/src/components/policy/policy_external/doc/doxygen/components/SmartObjects/Smart Objects Validation/Validation.txt new file mode 100644 index 0000000000..a02f0be4bd --- /dev/null +++ b/src/components/policy/policy_external/doc/doxygen/components/SmartObjects/Smart Objects Validation/Validation.txt @@ -0,0 +1,9 @@ +/*! \page components_smartobjects_validation_use Using Schema for validation + +The main purpose of Schema is validation of existing Smart Object. This process includes type and value validation. The client can use results of validation to determine if given Smart Object is valid or not. Validation of specific Smart Object can be triggered by using NsSmartDeviceLink::NsSmartObjects::CSmartSchema::validate method. Internally Schema triggers respective validate method of every Schema Item in order to perform validation. + +Another feature of Schema is capability to be applied to the Smart Object. Applying means that Schema tries to modify object to "normalize" data. Currently this "normalization" effects on string representation of enums. Applying of the Schema can be triggered by using NsSmartDeviceLink::NsSmartObjects::CSmartSchema::applySchema method. Internally Schema triggers respective apply method of every Schema Item and at the moment only enum Schema Items try to covert string representation to enum values. + +To "unapply" modifications done by apply feature Schema has NsSmartDeviceLink::NsSmartObjects::CSmartSchema::unapplySchema method. It can be used to make string representations of enums. + +*/ diff --git a/src/components/policy/policy_external/doc/doxygen/components/SmartObjects/Smart Objects Validation/index.txt b/src/components/policy/policy_external/doc/doxygen/components/SmartObjects/Smart Objects Validation/index.txt new file mode 100644 index 0000000000..d425791873 --- /dev/null +++ b/src/components/policy/policy_external/doc/doxygen/components/SmartObjects/Smart Objects Validation/index.txt @@ -0,0 +1,10 @@ +/*! \page components_smartobjects_validation Smart Objects validation + +The mechanism of Smart Objects validation includes special Schema. This Schema is similar to the regular XML schema. In other words Schema defines structural description of desired object. After that definition is done Schema can be applied to the object in order to make validation. + +Every Schema is constructed from objects called SchemaItems. Every SchemaItem defines type and restriction of specific data structure. + +For more details please review: + - \subpage components_smartobjects_validation_items "Schema structure: Schema Items" + - \subpage components_smartobjects_validation_use "Using Schema for validation" +*/ diff --git a/src/components/policy/policy_external/doc/doxygen/components/SmartObjects/Use b/src/components/policy/policy_external/doc/doxygen/components/SmartObjects/Use new file mode 100644 index 0000000000..e69de29bb2 --- /dev/null +++ b/src/components/policy/policy_external/doc/doxygen/components/SmartObjects/Use diff --git a/src/components/policy/policy_external/doc/doxygen/components/SmartObjects/Use of Smart Objects/index.txt b/src/components/policy/policy_external/doc/doxygen/components/SmartObjects/Use of Smart Objects/index.txt new file mode 100644 index 0000000000..d270436890 --- /dev/null +++ b/src/components/policy/policy_external/doc/doxygen/components/SmartObjects/Use of Smart Objects/index.txt @@ -0,0 +1,6 @@ +/*! \page components_smartobjects_usage Use Smart Objects + +There are lots of useful applications for the Smart Objects. They allow building complex dynamic data +structures in runtime and can be used to store and provide almost any data. For example any array can contain an item which is other array and so on. + +*/ diff --git a/src/components/policy/policy_external/doc/doxygen/components/SmartObjects/index.txt b/src/components/policy/policy_external/doc/doxygen/components/SmartObjects/index.txt new file mode 100644 index 0000000000..3844e1ab69 --- /dev/null +++ b/src/components/policy/policy_external/doc/doxygen/components/SmartObjects/index.txt @@ -0,0 +1,11 @@ +/*! \page components_smartobjects Smart Objects + +Smart Object is building block for a custom dynamic data structures with virtually unlimited complexity. Client code can use Smart Objects to create containers for simple basic types such as bools, ints, doubles, chars, strings end enums as well as arrays and maps. + +Smart Objects solution also includes validation/normalization mechanism of schemas witch is similar to the XML schemas. This feature allows client to validate any data structure. + +More detailed information is described in following chapters: + - \subpage components_smartobjects_types "Smart Objects Types" + - \subpage components_smartobjects_usage "Use of Smart Objects" + - \subpage components_smartobjects_validation "Smart Objects validation" +*/ diff --git a/src/components/policy/policy_external/doc/doxygen/components/TransportManager/Client Specification/ConnectionManagement.txt b/src/components/policy/policy_external/doc/doxygen/components/TransportManager/Client Specification/ConnectionManagement.txt new file mode 100644 index 0000000000..2ba273e9d4 --- /dev/null +++ b/src/components/policy/policy_external/doc/doxygen/components/TransportManager/Client Specification/ConnectionManagement.txt @@ -0,0 +1,11 @@ +/** @page components_transportmanager_client_connection_management Connection Management + * + * As all requests to TransportManager are asynchronous, client must implement NsSmartDeviceLink::NsTransportManager::ITransportManagerDeviceListener + * interface and add itself as a device listener with NsSmartDeviceLink::NsTransportManager::ITransportManager::addDeviceListener() + * in order to receive notifications. + * To connect remote device client must use NsSmartDeviceLink::NsTransportManager::ITransportManager::connectDevice(). It will initiate connections to all + * applications running on remove device. For TCP device this call has no effect as TCP connections are initiated by remote devices. + * Client will be notified about each connected application with NsSmartDeviceLink::NsTransportManager::ITransportManagerDeviceListener::onApplicationConnected(). + * To disconnect all applications running on remote device client must use NsSmartDeviceLink::NsTransportManager::ITransportManager::disconnectDevice(). + * Client will be notified about each disconnected application with NsSmartDeviceLink::NsTransportManager::ITransportManagerDeviceListener::onApplicationDisconnected(). + */ diff --git a/src/components/policy/policy_external/doc/doxygen/components/TransportManager/Client Specification/DataTransfer.txt b/src/components/policy/policy_external/doc/doxygen/components/TransportManager/Client Specification/DataTransfer.txt new file mode 100644 index 0000000000..98dd7426be --- /dev/null +++ b/src/components/policy/policy_external/doc/doxygen/components/TransportManager/Client Specification/DataTransfer.txt @@ -0,0 +1,11 @@ +/** @page components_transportmanager_client_data_transfer Data Transfer + * + * As all requests to TransportManager are asynchronous, client must implement NsSmartDeviceLink::NsTransportManager::ITransportManagerDataListener + * interface and add itself as a data listener with NsSmartDeviceLink::NsTransportManager::ITransportManager::addDataListener() + * in order to receive notifications. + * To send frame to remote device client must use NsSmartDeviceLink::NsTransportManager::ITransportManager::sendFrame() poviding connection handle, + * frame data, data size and user data. User data is an integer that is assigned to a frame and will be sent back to client when sending of frame + * will be completed. Client may use this data to identify frame when send result will be reported. When sending of frame is completed + * client is notified via NsSmartDeviceLink::NsTransportManager::ITransportManagerDataListener::onFrameSendCompleted(). When frame is received from a remote + * device client is notified via NsSmartDeviceLink::NsTransportManager::ITransportManagerDataListener::onFrameReceived(). + */ diff --git a/src/components/policy/policy_external/doc/doxygen/components/TransportManager/Client Specification/DeviceManagement.txt b/src/components/policy/policy_external/doc/doxygen/components/TransportManager/Client Specification/DeviceManagement.txt new file mode 100644 index 0000000000..eb5f3e477e --- /dev/null +++ b/src/components/policy/policy_external/doc/doxygen/components/TransportManager/Client Specification/DeviceManagement.txt @@ -0,0 +1,14 @@ +/** @page components_transportmanager_client_device_management Device Management + * + * As all requests to TransportManager are asynchronous, client must implement NsSmartDeviceLink::NsTransportManager::ITransportManagerDeviceListener + * interface and add itself as a device listener with NsSmartDeviceLink::NsTransportManager::ITransportManager::addDeviceListener() + * in order to receive notifications. + * Client of TransportManager may use NsSmartDeviceLink::NsTransportManager::ITransportManager::scanForNewDevices() + * to initiate device scan on all device adapters that support this feature. In order to get list of available + * devices client must override NsSmartDeviceLink::NsTransportManager::ITransportManagerDeviceListener::onDeviceListUpdated(). + * Each device adapter will perform scan independently from other device adapters and device list might be updated + * several times (after each adapter that supports scanning finishes scanning operation). Device list might also be + * updated without device scan request, e.g. if new client connects via TCP this device will be added to device list + * and update notification will be sent to client. In any of these cases client will be provided with the full + * device list from all device adapters in every notification. + */ diff --git a/src/components/policy/policy_external/doc/doxygen/components/TransportManager/Client Specification/index.txt b/src/components/policy/policy_external/doc/doxygen/components/TransportManager/Client Specification/index.txt new file mode 100644 index 0000000000..8916dbeb55 --- /dev/null +++ b/src/components/policy/policy_external/doc/doxygen/components/TransportManager/Client Specification/index.txt @@ -0,0 +1,18 @@ +/*! \page components_transportmanager_client Transport Manager Client Specification + +This chapter describes details of correct use of Transport Manager on the client side. In other words this chapter can be called "How to create effective and safe client of Transport Manager". +Transport Manager defines set of asynchronous requests (means that operations are non-blocking in the calling thread) and provides two different interfaces to monitor asynchronous responses and notifications about data update. + +Clients of Transport Manager should use NsSmartDeviceLink::NsTransportManager::ITransportManager interface to initiate any request to the component. +Also Transport Manager provides two different interfaces: + +1) NsSmartDeviceLink::NsTransportManager::ITransportManagerDataListener. Client can implement this interface if it needs information about data frame send/receive. + +2) NsSmartDeviceLink::NsTransportManager::ITransportManagerDeviceListener. Client can implement this interface if it needs information about updates of devices available for communication and current client applications status. + +For more information about typical use of Transport Manager please read the following topics: + - \subpage components_transportmanager_client_device_management "Device Management" + - \subpage components_transportmanager_client_connection_management "Connection Management" + - \subpage components_transportmanager_client_data_transfer "Data Transfer" + +*/ diff --git a/src/components/policy/policy_external/doc/doxygen/components/TransportManager/Internal b/src/components/policy/policy_external/doc/doxygen/components/TransportManager/Internal new file mode 100644 index 0000000000..e69de29bb2 --- /dev/null +++ b/src/components/policy/policy_external/doc/doxygen/components/TransportManager/Internal diff --git a/src/components/policy/policy_external/doc/doxygen/components/TransportManager/Internal Design/Device Adapters/BluetoothAdapter.txt b/src/components/policy/policy_external/doc/doxygen/components/TransportManager/Internal Design/Device Adapters/BluetoothAdapter.txt new file mode 100644 index 0000000000..970aeffd83 --- /dev/null +++ b/src/components/policy/policy_external/doc/doxygen/components/TransportManager/Internal Design/Device Adapters/BluetoothAdapter.txt @@ -0,0 +1,19 @@ +/** @page components_transportmanager_internal_design_transport_adapters_bluetooth_adapter Bluetooth Adapter + * + * Bluetooth adapter handles communication with external devices via bluetooth. It is implemented in + * NsSmartDeviceLink::NsTransportManager::CBluetoothAdapter. + * + * @section components_transportmanager_internal_design_transport_adapters_bluetooth_adapter_discovery Device discovery + * + * When requested by a call to NsSmartDeviceLink::NsTransportManager::CTransportAdapter::scanForNewDevices() bluetooth adapter + * searches for bluetooth devices. For each found device it runs SDP query for service with SmartDeviceLink UUID + * (936DA01F-9ABD-4D9D-80C7-02AF85C822A8). Devices that support this service are added to bluetooth adapter device list. + * Bluetooth device scans are performed only when explicitly requested. + * + * @section components_transportmanager_internal_design_transport_adapters_bluetooth_adapter_connecting_devices Connecting devices + * + * NsSmartDeviceLink::NsTransportManager::CBluetoothAdapter::createConnectionsListForDevice() runs SDP query for specified device + * and fills connection list with connections to all RFCOMM channels on remote device where SmartDeviceLink service has been discovered. + * + * @see @ref components_transportmanager_internal_design_transport_adapters_common_connecting_devices + */ diff --git a/src/components/policy/policy_external/doc/doxygen/components/TransportManager/Internal Design/Device Adapters/TCPAdapter.txt b/src/components/policy/policy_external/doc/doxygen/components/TransportManager/Internal Design/Device Adapters/TCPAdapter.txt new file mode 100644 index 0000000000..d81b70dfe8 --- /dev/null +++ b/src/components/policy/policy_external/doc/doxygen/components/TransportManager/Internal Design/Device Adapters/TCPAdapter.txt @@ -0,0 +1,20 @@ +/** @page components_transportmanager_internal_design_transport_adapters_tcp_adapter TCP Adapter + * + * TCP adapter handles communication with remote devices via TCP/IP socket. It is implemented in + * NsSmartDeviceLink::NsTransportManager::CTCPAdapter. + * + * @section components_transportmanager_internal_design_transport_adapters_tcp_adapter_listen Listening for connections + * + * TCP adapter creates listening TCP socket (TCP port is specified in NsSmartDeviceLink::NsTransportManager::CTCPAdapter::cTCPAdapterPort) + * and listens for incoming connections. Devices are identified by their IP address. + * + * @section components_transportmanager_internal_design_transport_adapters_tcp_adapter_accept Accepting connection + * + * When TCP adapter accepts connection it checks if there is a device with IP address matching with IP address of accepted connection. + * If there is no such device, then this device is added and device list is updated. + * + * @section components_transportmanager_internal_design_transport_adapters_tcp_adapter_disconnecting Disconnecting + * + * When socket gets disconnected TCP adapter checks if there is another opened connection for IP address of disconnected application. + * If it was the last application from this IP address then device with this IP address is removed and devices list is updated. + */ diff --git a/src/components/policy/policy_external/doc/doxygen/components/TransportManager/Internal Design/Device Adapters/index.txt b/src/components/policy/policy_external/doc/doxygen/components/TransportManager/Internal Design/Device Adapters/index.txt new file mode 100644 index 0000000000..3a5d0f0e91 --- /dev/null +++ b/src/components/policy/policy_external/doc/doxygen/components/TransportManager/Internal Design/Device Adapters/index.txt @@ -0,0 +1,89 @@ +/** @page components_transportmanager_internal_design_transport_adapters Device Adapters + * + * TransportManager communicates with actual devices via device adapters. + * + * @section components_transportmanager_internal_design_transport_adapters_common Common logic + * + * Logic common to all device adapters is implemented in class NsSmartDeviceLink::NsTransportManager::CTransportAdapter. + * + * @subsection components_transportmanager_internal_design_transport_adapters_common_devices_map Devices map + * + * Devices map is a map of device handle to internal device structure NsSmartDeviceLink::NsTransportManager::CTransportAdapter::SDevice. + * Devices map is stored in NsSmartDeviceLink::NsTransportManager::CTransportAdapter::mDevices. Any access to this map must be performed + * with NsSmartDeviceLink::NsTransportManager::CTransportAdapter::mDevicesMutex locked. + * + * @subsection components_transportmanager_internal_design_transport_adapters_common_connections_map Connections map + * + * Connections map is a map of connection handle to internal connection structure NsSmartDeviceLink::NsTransportManager::CTransportAdapter::SConnection. + * Connections map is stored in NsSmartDeviceLink::NsTransportManager::CTransportAdapter::mConnections. Any access to this map must be performed + * with NsSmartDeviceLink::NsTransportManager::CTransportAdapter::mConnectionsMutex locked. + * + * @subsection components_transportmanager_internal_design_transport_adapters_common_main_thread Device adapter main thread + * + * Device adapter main thread is started in NsSmartDeviceLink::NsTransportManager::CTransportAdapter::run(). + * Specific device adapter must implement virtual function NsSmartDeviceLink::NsTransportManager::CTransportAdapter::mainThread() + * and implement its specific main thread logic there. + * + * @subsection components_transportmanager_internal_design_transport_adapters_common_connection_thread Device adapter connection thread + * + * Device adapter connection thread is started in NsSmartDeviceLink::NsTransportManager::CTransportAdapter::startConnection(). + * Specific device adapter must implement virtual function NsSmartDeviceLink::NsTransportManager::CTransportAdapter::connectionThread() + * and implement its specific connection thread logic there. When connection is established and socket file descriptor is set + * in NsSmartDeviceLink::NsTransportManager::CTransportAdapter::SConnection::mConnectionSocket specific device adapter may call + * NsSmartDeviceLink::NsTransportManager::CTransportAdapter::handleCommunication() to handle all communication through this socket + * until connection is terminated. + * + * @subsection components_transportmanager_internal_design_transport_adapters_common_threads_termination Termination of device adapter threads + * + * Specific device adapter implementation must call in its destructor NsSmartDeviceLink::NsTransportManager::CTransportAdapter::waitForThreadsTermination() + * to wait for termination of all threads (main thread and connection threads). Device adapter threads must be terminated before specific + * device adapter class is destructed, so it can't be called in the destructor of base class and must be called explicitly from the inherited + * class's destructor. + * + * @subsection components_transportmanager_internal_design_transport_adapters_common_device_scan Requesting scan for new devices + * + * Device scan is requested by setting flag NsSmartDeviceLink::NsTransportManager::CTransportAdapter::mDeviceScanRequested + * and signaling conditional variable NsSmartDeviceLink::NsTransportManager::CTransportAdapter::mDeviceScanRequestedCond, which may be monitored + * by specific device adapter if it supports device scanning. Specific device adaptere may call for this purpose + * NsSmartDeviceLink::NsTransportManager::CTransportAdapter::waitForDeviceScanRequest() which will wait on this conditional variable + * until it's signaled or specified timeout expires. + * + * @subsection components_transportmanager_internal_design_transport_adapters_common_connecting_devices Connecting devices + * + * Device connection is initiated with a call to NsSmartDeviceLink::NsTransportManager::CTransportAdapter::connectDevice(). + * This method calls virtual function NsSmartDeviceLink::NsTransportManager::CTransportAdapter::createConnectionsListForDevice() + * which may be implemented by specific device adapter to create a list of connections that must be established for the device. + * For each connection created by device adapter it calls NsSmartDeviceLink::NsTransportManager::CTransportAdapter::startConnection() + * which adds connection to connections map and starts connection thread. + * + * @subsection components_transportmanager_internal_design_transport_adapters_common_disconnecting_devices Disconnecting devices + * + * Device disconnection is initiated with a call to NsSmartDeviceLink::NsTransportManager::CTransportAdapter::disconnectDevice(). + * This method finds all connections in connections map that corresponds to specified device and calls + * NsSmartDeviceLink::NsTransportManager::CTransportAdapter::stopConnection() for each of them. + * + * @subsection components_transportmanager_internal_design_transport_adapters_common_handling_communication Handling communication + * + * All frames requested to be sent via NsSmartDeviceLink::NsTransportManager::CTransportAdapter::sendFrame() are stored in + * NsSmartDeviceLink::NsTransportManager::CTransportAdapter::SConnection::mFramesToSend. Pipe + * NsSmartDeviceLink::NsTransportManager::CTransportAdapter::SConnection::mNotificationPipeFds is used by + * NsSmartDeviceLink::NsTransportManager::CTransportAdapter::sendFrame() to notify connection thread that data is available + * to be sent. NsSmartDeviceLink::NsTransportManager::CTransportAdapter::sendFrame() writes one byte to the write end of this pipe. + * NsSmartDeviceLink::NsTransportManager::CTransportAdapter::handleCommunication() uses poll() to wait for + * incoming data using connection socket file descriptor and outgoing data using file descriptor of the read end of this pipe. + * When either of them become available for reading or some error occurs (e.g. socket gets disconnected) connection thread + * wakes up and handles this event. Notification pipe is also used to notify connection thread that connection has to be + * terminated using NsSmartDeviceLink::NsTransportManager::CTransportAdapter::SConnection::mTerminateFlag. + * + * @subsection components_transportmanager_internal_design_transport_adapters_common_update_client_device_list Updating client device list. + * + * Specific device adapter may call NsSmartDeviceLink::NsTransportManager::CTransportAdapter::updateClientDeviceList() when its internal + * knowledge about available devices is updated to notify device adapter client (TransportManager) about this update. + * + * @section components_transportmanager_internal_design_transport_adapters_common_specific Specific device adapters + * + * Current TransportManager implementation contains following device adapters: + * + * - @subpage components_transportmanager_internal_design_transport_adapters_bluetooth_adapter "Bluetooth Adapter" + * - @subpage components_transportmanager_internal_design_transport_adapters_tcp_adapter "TCP Adapter" + */ diff --git a/src/components/policy/policy_external/doc/doxygen/components/TransportManager/Internal Design/Interaction.txt b/src/components/policy/policy_external/doc/doxygen/components/TransportManager/Internal Design/Interaction.txt new file mode 100644 index 0000000000..655d0a1290 --- /dev/null +++ b/src/components/policy/policy_external/doc/doxygen/components/TransportManager/Internal Design/Interaction.txt @@ -0,0 +1,7 @@ +/*! \page components_transportmanager_internal_design_interaction Sub-Components Interaction + +Internally Transport Manager is a root component for Device Adapters. After running Transport Manager creates Device Adapters and runs them too. + +During system life cycle all messages from Device Adapter are translated via Transport Manager to the clients. In other direction – all requests from clients are re-directed to respective Device Adapters by the Transport Manager. + +*/ diff --git a/src/components/policy/policy_external/doc/doxygen/components/TransportManager/Internal Design/MultiThreading.txt b/src/components/policy/policy_external/doc/doxygen/components/TransportManager/Internal Design/MultiThreading.txt new file mode 100644 index 0000000000..6c35f0962f --- /dev/null +++ b/src/components/policy/policy_external/doc/doxygen/components/TransportManager/Internal Design/MultiThreading.txt @@ -0,0 +1,9 @@ +/*! \page components_transportmanager_internal_design_multithreading Multi-Threading in Component + +Internally Transport Manager uses different threads for different operations. This design solution was used to provide efficient asynchronous communication with clients and underlying Device Adapters. + +Transport Manager uses one thread to operate with all device-related callbacks. In other word all callbacks declared in NsSmartDeviceLink::NsTransportManager::ITransportManagerDeviceListener will be called from that thread. + +For every active connection one service thread will be created. This thread will be used for all connection-related callbacks. Therefore every implementation of NsSmartDeviceLink::NsTransportManager::ITransportManagerDataListener will be called in separated thread that allows client to support multiple connection simultaneously. + +*/ diff --git a/src/components/policy/policy_external/doc/doxygen/components/TransportManager/Internal Design/TrasportManager.txt b/src/components/policy/policy_external/doc/doxygen/components/TransportManager/Internal Design/TrasportManager.txt new file mode 100644 index 0000000000..c96fd46a22 --- /dev/null +++ b/src/components/policy/policy_external/doc/doxygen/components/TransportManager/Internal Design/TrasportManager.txt @@ -0,0 +1,15 @@ +/*! \page components_transportmanager_internal_design_trasport_manager Trasport Manager Implementation + +Actually Transport Manager component is implemented as classical manager component. It manages connections and abstract devices and provides unified information for the clients. + +Connection-related information encapsulated in structure NsSmartDeviceLink::NsTransportManager::CTransportManager::SConnectionInfo. Transport Manager manages these structures to store information about every active connection. + +Frame processing encapsulated in structure NsSmartDeviceLink::NsTransportManager::CTransportManager::SFrameDataForConnection. Transport Manager manages these structures to store information related to data for specific connection. + +Callback information between transport manager threads passed in form of special structures: +NsSmartDeviceLink::NsTransportManager::CTransportManager::SDeviceListenerCallback. +NsSmartDeviceLink::NsTransportManager::CTransportManager::SDataListenerCallback. + +Client calls to TM guarded by separate mutex. This allows use component from different threads without any risk. + +*/ diff --git a/src/components/policy/policy_external/doc/doxygen/components/TransportManager/Internal Design/index.txt b/src/components/policy/policy_external/doc/doxygen/components/TransportManager/Internal Design/index.txt new file mode 100644 index 0000000000..b29ec48dd1 --- /dev/null +++ b/src/components/policy/policy_external/doc/doxygen/components/TransportManager/Internal Design/index.txt @@ -0,0 +1,15 @@ +/*! \page components_transportmanager_internal_design Component Internal Design + +This chapter is focused on Transport Manager internal design and describes internal sub-components and use of multi-threading. + +Information regarding sub-components is described in following topics: + - \subpage components_transportmanager_internal_design_transport_adapters "Device Adapters" + - \subpage components_transportmanager_internal_design_trasport_manager "Trasport Manager Implementation" + +Detailed description of sub-components interaction is described here: + - \subpage components_transportmanager_internal_design_interaction "Sub-Components Interaction" + +More information about internal usage of multi-threading id described here: + - \subpage components_transportmanager_internal_design_multithreading "Multi-Threading in Component" + +*/ diff --git a/src/components/policy/policy_external/doc/doxygen/components/TransportManager/Use Cases/UseCase1.txt b/src/components/policy/policy_external/doc/doxygen/components/TransportManager/Use Cases/UseCase1.txt new file mode 100644 index 0000000000..4af46e4320 --- /dev/null +++ b/src/components/policy/policy_external/doc/doxygen/components/TransportManager/Use Cases/UseCase1.txt @@ -0,0 +1,74 @@ +/*! \page components_transportmanager_use_cases_1 Scenario with 1 device and 1 application + +<h3>Preconditions:</h3> +<table> + <tr> + <th>Steps</th> + <th>Actions</th> + <th>Expected result</th> + </tr> + <tr> + <td>1</td> + <td>The Device is connected to SmartDeviceLink Core VIA Bluetooth or Wi-Fi</td> + <td> + <p>For BT: Devices are paired</p> + <p>For Wi-Fi: Devices are in the same network</p> + </td> + </tr> + <tr> + <td>2</td> + <td>Make sure that correct device is connected to SmartDeviceLink core</td> + <td>IP-address of connected device is relevant</td> + </tr> +</table> + +<h3>Testcase:</h3> +<table> + <tr> + <th>Steps</th> + <th>Actions</th> + <th>Expected result</th> + </tr> + <tr> + <td>1</td> + <td>Start SmartDeviceLink application on the Devices</td> + <td>SmartDeviceLink application is up and ready</td> + </tr> + <tr> + <td>2</td> + <td>Initiate a Device search in HMI</td> + <td>HMI displays the list of found devices/applications</td> + </tr> + <tr> + <td>3</td> + <td>Connect to desired device\application</td> + <td>Application is marked as connected/notification is displayed in HMI</td> + </tr> + <tr> + <td>4</td> + <td>Send alert message from SmartDeviceLink application</td> + <td>Alert is displayed on HMI</td> + </tr> + <tr> + <td>5</td> + <td>Disconnect device from SmartDeviceLink core</td> + <td>Application is marked as disconnected/notification is displayed in HMI</td> + </tr> + <tr> + <td>6</td> + <td>Try to send alert from disconnected device</td> + <td>Alert shouldn’t be delivered and displayed in HMI</td> + </tr> + <tr> + <td>7</td> + <td><strong>Repeat steps 1-4 with using another connection method (BT of Wi-Fi)</strong></td> + <td>Expected results should be the same</td> + </tr> + <tr> + <td>8</td> + <td><h3>Stress:</h3>Send big amount of alert messages in a short period of time</td> + <td>All alert messages are processed correctly</td> + </tr> +</table> + +*/ diff --git a/src/components/policy/policy_external/doc/doxygen/components/TransportManager/Use Cases/UseCase2.txt b/src/components/policy/policy_external/doc/doxygen/components/TransportManager/Use Cases/UseCase2.txt new file mode 100644 index 0000000000..de1d6baae0 --- /dev/null +++ b/src/components/policy/policy_external/doc/doxygen/components/TransportManager/Use Cases/UseCase2.txt @@ -0,0 +1,96 @@ +/*! \page components_transportmanager_use_cases_2 Scenario with 2 or more devices with 1 application onboard + +<h3>Preconditions:</h3> +<table> + <tr> + <th>Steps</th> + <th>Actions</th> + <th>Expected result</th> + </tr> + <tr> + <td>1</td> + <td>Device-1 is connected to Core via Bluetooth</td> + <td>Devices are paired</td> + </tr> + <tr> + <td>2</td> + <td>Device-2 is connected to SmartDeviceLink Core via Wi-Fi</td> + <td>Devices are in the same network</td> + </tr> + <tr> + <td>3</td> + <td>Make sure that correct devices are connected to SmartDeviceLink core</td> + <td>IP-address of connected devices are relevant</td> + </tr> +</table> + +<h3>Testcase:</h3> +<table> + <tr> + <th>Steps</th> + <th>Actions</th> + <th>Expected result</th> + </tr> + <tr> + <td>1</td> + <td>Start SmartDeviceLink application on the Devices</td> + <td>SmartDeviceLink application is up and ready</td> + </tr> + <tr> + <td>2</td> + <td>Initiate a Device search in HMI</td> + <td>HMI displays the list of found devices/applications</td> + </tr> + <tr> + <td>3</td> + <td>Connect to application-1 on 1-st device</td> + <td>Application is marked as connected/notification is displayed in HMI</td> + </tr> + <tr> + <td>4</td> + <td>Connect to application on 2-nd device</td> + <td>Application is marked as connected/notification is displayed in HMI. Both applications on device-1 and device-2 are marked as connected</td> + </tr> + <tr> + <td>5</td> + <td>Send alert message from SmartDeviceLink application-1</td> + <td>Alert is displayed on HMI</td> + </tr> + <tr> + <td>6</td> + <td>Send alert message from SmartDeviceLink application-2</td> + <td>Alert is displayed on HMI</td> + </tr> + <tr> + <td>7</td> + <td>Send alert messages from both application simultaneously</td> + <td>Both alerts are displayed on HMI/Alerts are showed consequently</td> + </tr> + <tr> + <td>8</td> + <td>Disconnect device-2 from SmartDeviceLink core</td> + <td>Application is marked as disconnected/notification is displayed in HMI</td> + </tr> + <tr> + <td>9</td> + <td>Try to send alert messages from both application simultaneously</td> + <td>Alert is delivered only from device-1</td> + </tr> + <tr> + <td>10</td> + <td>Disconnect device-1 from SmartDeviceLink core</td> + <td>Application is marked as disconnected/notification is displayed in HMI</td> + </tr> + <tr> + <td>11</td> + <td><strong>Repeat steps 1-9 with more devices or use same connection method (BT of Wi-Fi)</strong></td> + <td>Expected results should be the same</td> + </tr> + <tr> + <td>12</td> + <td><h3>Stress:</h3>Send big amount of alert messages in a short period of time from all devices</td> + <td>All alert messages are processed correctly</td> + </tr> +</table> + +*/ diff --git a/src/components/policy/policy_external/doc/doxygen/components/TransportManager/Use Cases/UseCase3.txt b/src/components/policy/policy_external/doc/doxygen/components/TransportManager/Use Cases/UseCase3.txt new file mode 100644 index 0000000000..f11faadfdc --- /dev/null +++ b/src/components/policy/policy_external/doc/doxygen/components/TransportManager/Use Cases/UseCase3.txt @@ -0,0 +1,131 @@ +/*! \page components_transportmanager_use_cases_3 Scenario with 2 or more devices with 2 or more applications onboard + +<h3>Preconditions:</h3> +<table> + <tr> + <th>Steps</th> + <th>Actions</th> + <th>Expected result</th> + </tr> + <tr> + <td>1</td> + <td>Device-1 is connected to Core via Bluetooth</td> + <td>Devices are paired</td> + </tr> + <tr> + <td>2</td> + <td>Device-2 is connected to SmartDeviceLink Core via Wi-Fi</td> + <td>Devices are in the same network</td> + </tr> + <tr> + <td>3</td> + <td>Make sure that correct devices are connected to SmartDeviceLink core</td> + <td>IP-address of connected devices are relevant</td> + </tr> +</table> + +<h3>Testcase:</h3> +<table> + <tr> + <th>Steps</th> + <th>Actions</th> + <th>Expected result</th> + </tr> + <tr> + <td>1</td> + <td>Start SmartDeviceLink application on the Devices</td> + <td>SmartDeviceLink application is up and ready</td> + </tr> + <tr> + <td>2</td> + <td>Initiate a Device search in HMI</td> + <td>HMI displays the list of found devices/applications</td> + </tr> + <tr> + <td>3</td> + <td>Connect to application-1 on 1-st device</td> + <td>Application is marked as connected/notification is displayed in HMI</td> + </tr> + <tr> + <td>4</td> + <td>Send alert message from SmartDeviceLink application-1 on device-1</td> + <td>Alert is displayed on HMI</td> + </tr> + <tr> + <td>5</td> + <td>Connect to application-2 on 1-st device</td> + <td>Application is marked as connected/notification is displayed in HMI Both applications are marked as connected</td> + </tr> + <tr> + <td>6</td> + <td>Send alert message from SmartDeviceLink application-2 on device-1</td> + <td>Alert is displayed on HMI</td> + </tr> + <tr> + <td>7</td> + <td>Send alert messages from application-1 and application-2 on device-1 simultaneously</td> + <td>Both alerts are displayed on HMI/Alerts are showed consequently</td> + </tr> + <tr> + <td>8</td> + <td>Connect to application-1 on 2-st device</td> + <td>Application is marked as connected/notification is displayed in HMI. All 3 applications are marked as connected</td> + </tr> + <tr> + <td>9</td> + <td>Send alert messages from application-1 on device-1 and device-2 simultaneously</td> + <td>Both alerts are displayed on HMI/Alerts are showed consequently</td> + </tr> + <tr> + <td>10</td> + <td>Send alert message from SmartDeviceLink application-1 on device-2</td> + <td>Alert is displayed on HMI</td> + </tr> + <tr> + <td>11</td> + <td>Connect to application on 2-nd device</td> + <td>Application is marked as connected/notification is displayed in HMI. All 4 applications are marked as connected</td> + </tr> + <tr> + <td>12</td> + <td>Send alert message from SmartDeviceLink application-2 on device-2</td> + <td>Alert is displayed on HMI</td> + </tr> + <tr> + <td>13</td> + <td>Send alert messages from application-1 and application-2 on device-2 simultaneously</td> + <td>Both alerts are displayed on HMI/Alerts are showed consequently</td> + </tr> + <tr> + <td>14</td> + <td>Send alert messages from application-2 on device-1 and device-2 simultaneously</td> + <td>Both alerts are displayed on HMI/Alerts are showed consequently</td> + </tr> + <tr> + <td>15</td> + <td>Send alert messages from all application simultaneously</td> + <td>Both alerts are displayed on HMI/Alerts are showed consequently</td> + </tr> + <tr> + <td>16</td> + <td>Disconnect device-1 from SmartDeviceLink core</td> + <td>Applications are marked as disconnected/notification is displayed in HMI</td> + </tr> + <tr> + <td>17</td> + <td>Disconnect device-2 from SmartDeviceLink core</td> + <td>All applications are marked as disconnected/notification is displayed in HMI</td> + </tr> + <tr> + <td>18</td> + <td><strong>Repeat steps 1-15 with more devices and more applications or use same connection method (BT of Wi-Fi)</strong></td> + <td>Expected results should be the same</td> + </tr> + <tr> + <td>19</td> + <td><h3>Stress:</h3>Send big amount of alert messages in a short period of time from all devices</td> + <td>All alert messages are processed correctly</td> + </tr> +</table> + +*/ diff --git a/src/components/policy/policy_external/doc/doxygen/components/TransportManager/Use Cases/index.txt b/src/components/policy/policy_external/doc/doxygen/components/TransportManager/Use Cases/index.txt new file mode 100644 index 0000000000..c929a16a88 --- /dev/null +++ b/src/components/policy/policy_external/doc/doxygen/components/TransportManager/Use Cases/index.txt @@ -0,0 +1,11 @@ +/*! \page components_transportmanager_use_cases High-Level Use Cases to Test Component + +This page contains set of high-level use-cases which can be used for testing of Transport Manager functionallity. + +In described scenarious term “Device” means any device which is able to run SmartDeviceLink Applications and capable to connect via BT or +Wi-Fi. + +- \subpage components_transportmanager_use_cases_1 Simple scenario for smoke tests of trasprot level. +- \subpage components_transportmanager_use_cases_2 Many devices verification for transport level operations. +- \subpage components_transportmanager_use_cases_3 Complex verification of correct transport level operations. +*/ diff --git a/src/components/policy/policy_external/doc/doxygen/components/TransportManager/index.txt b/src/components/policy/policy_external/doc/doxygen/components/TransportManager/index.txt new file mode 100644 index 0000000000..73252c751c --- /dev/null +++ b/src/components/policy/policy_external/doc/doxygen/components/TransportManager/index.txt @@ -0,0 +1,9 @@ +/*! \page components_transportmanager Transport Manager + +Transport Manager is a component of SmartDeviceLink application which is designed to provide transparent access to transport layer for other components. Current implementation provides unified access to connections via Bluetooth and TCP. Also this component allows run automatic device discovery and provides information about found devices which is able to connect to SmartDeviceLink. + +More detailed information is described in following chapters: + - \subpage components_transportmanager_client "Transport Manager Client Specification" + - \subpage components_transportmanager_internal_design "Component Internal Design" + - \subpage components_transportmanager_use_cases "High-Level Use Cases to Test Component" +*/ diff --git a/src/components/policy/policy_external/doc/doxygen/components/index.txt b/src/components/policy/policy_external/doc/doxygen/components/index.txt new file mode 100644 index 0000000000..186de88af0 --- /dev/null +++ b/src/components/policy/policy_external/doc/doxygen/components/index.txt @@ -0,0 +1,10 @@ +/*! \page components Components + +Project contain following components: + - \subpage components_transportmanager "Transport Manager" + - \subpage components_protocolhandler "Protocol Handler" + - \subpage components_jsonhandler "JSON Handler" + - \subpage components_smartobjects "Smart Objects" + - \subpage components_appmgr "App Manager" + - \subpage components_hmi "HMI" +*/ diff --git a/src/components/policy/policy_external/doc/doxygen/info.txt b/src/components/policy/policy_external/doc/doxygen/info.txt new file mode 100644 index 0000000000..e8afe55c12 --- /dev/null +++ b/src/components/policy/policy_external/doc/doxygen/info.txt @@ -0,0 +1,5 @@ +/*! \page info Project information + +Here will be general information about project + +*/
\ No newline at end of file diff --git a/src/components/policy/policy_external/doc/doxygen/mainpage.txt b/src/components/policy/policy_external/doc/doxygen/mainpage.txt new file mode 100644 index 0000000000..5cd05e2606 --- /dev/null +++ b/src/components/policy/policy_external/doc/doxygen/mainpage.txt @@ -0,0 +1,9 @@ +/*! \mainpage Project SmartDeviceLink + +This is the entry point to the documentation about project. + +This manual is divided in the following sections: +- \subpage info "General project information" +- \subpage components "Project components" +- \subpage tools "Project specific tools" +*/ diff --git a/src/components/policy/policy_external/doc/doxygen/tools/InterfaceGenerator/Arhitecture.txt b/src/components/policy/policy_external/doc/doxygen/tools/InterfaceGenerator/Arhitecture.txt new file mode 100644 index 0000000000..4cf9e84d99 --- /dev/null +++ b/src/components/policy/policy_external/doc/doxygen/tools/InterfaceGenerator/Arhitecture.txt @@ -0,0 +1,5 @@ +/*! \page tools_interfacegenerator_architecture InterfaceGenerator architecture + +InterfaceGenerator is designed as flexible and easily expendable tool that allows to implement both new parsers and generators independently. The core idea of InterfaceGenerator that it has middle-ware product - abstract model of interface that should be generated. This middle layer allows to separate collection of parsers from generators. Also it is possible to add any new validation / normalization component between them. So at the moment the root script creates actual parser and that parser produces model of interface (set of Python classes objects). After that interface model is passed to the desired generator and generator creates result source code files. + +*/ diff --git a/src/components/policy/policy_external/doc/doxygen/tools/InterfaceGenerator/CMake Integration.txt b/src/components/policy/policy_external/doc/doxygen/tools/InterfaceGenerator/CMake Integration.txt new file mode 100644 index 0000000000..b4fb0b3df5 --- /dev/null +++ b/src/components/policy/policy_external/doc/doxygen/tools/InterfaceGenerator/CMake Integration.txt @@ -0,0 +1,13 @@ +/*! \page tools_interfacegenerator_cmakeintegration Integration with CMake + +In order to organize usable build process that allows to create generated code at every workstation in accordance with local setting and ensure that code re-generated after any modification in source XML or InterfaceGenerator itself was designed custom CMake rule "GenerateInterface". + +This rule takes 3 arguments - name of source XML file, desired namespace for generated code and name of parser to use (name of parser is required because supported XML formats are indistinguishable and client must explicitly specify desired parser type). + +Example: + +<pre> +GenerateInterface("test_v4_protocol_v2_0_revP.xml" "Gen::test::components::JSONHandler" "alrpcv2") +</pre> + +*/ diff --git a/src/components/policy/policy_external/doc/doxygen/tools/InterfaceGenerator/How To Use.txt b/src/components/policy/policy_external/doc/doxygen/tools/InterfaceGenerator/How To Use.txt new file mode 100644 index 0000000000..0f9e340bc5 --- /dev/null +++ b/src/components/policy/policy_external/doc/doxygen/tools/InterfaceGenerator/How To Use.txt @@ -0,0 +1,31 @@ +/*! \page tools_interfacegenerator_usage How to use InterfaceGenerator + +To run InterfaceGenerator the Python 2.7 interpreter should be installed. As input InterfaceGenerator requires full path to the source XML file, namespace to generate result code in, full path to the output directory where result source code C++ will be created and optionally explicit specification of parser type. + +Example1 (Run Generator.py to display help): + +<pre> +$ python Generator.py -h + +usage: Generator.py [-h] --parser-type {alrpcv1,alrpcv2} + source-xml namespace output-dir + +SmartSchema interface generator + +positional arguments: + source-xml + namespace + output-dir + +optional arguments: + -h, --help show this help message and exit + --parser-type {alrpcv1,alrpcv2} +</pre> + +Example2 (Run Generator.py to generate some code) + +<pre> +python Generator.py /home/user1/xml/alrpc1.xml App::Gen:: /home/user1/gen --parser-type=alrpcv2 +</pre> + +*/ diff --git a/src/components/policy/policy_external/doc/doxygen/tools/InterfaceGenerator/Use of Output.txt b/src/components/policy/policy_external/doc/doxygen/tools/InterfaceGenerator/Use of Output.txt new file mode 100644 index 0000000000..b486fd7e37 --- /dev/null +++ b/src/components/policy/policy_external/doc/doxygen/tools/InterfaceGenerator/Use of Output.txt @@ -0,0 +1,11 @@ +/*! \page tools_interfacegenerator_output Use of InterfaceGenerator output + +As a result InterfaceGenerator produces one .cpp and one .hpp file in the output directory. Those files contain one C++ class which named in accordance with input XML file name. Class is declared and implemented in specified namespace. Also all enums form source XML file have automatically generated declarations within specified namespace. + +Generated class is inherited form predefined base template class CSmartFactory. Actually this inherited class defines specific set of Smart Object schema's initialization methods which are set to the base class member and can be used by the clients. + +Also generated code contains string mapping for enums that is used to convert string representation or enums to integer values and vice versa. + +Result source code should be compilable but this is not guaranteed if source XML file contains identifier names that are not correct C++ identifiers. + +*/ diff --git a/src/components/policy/policy_external/doc/doxygen/tools/InterfaceGenerator/index.txt b/src/components/policy/policy_external/doc/doxygen/tools/InterfaceGenerator/index.txt new file mode 100644 index 0000000000..21b437f6b7 --- /dev/null +++ b/src/components/policy/policy_external/doc/doxygen/tools/InterfaceGenerator/index.txt @@ -0,0 +1,12 @@ +/*! \page tools_interfacegenerator InterfaceGenerator + +InterfaceGenerator is a special code generation tool that allows creating of C++ source code to work with interface described as XML file. +InterfaceGenerator is a bundle of Python scripts. Root script is a Generator.py. This script should be used by the client to run generator. +Currently InterfaceGenerator supports generation form ALRPC v.1 and ALRPC v.2 XML formats. + +For more details please review: + - \subpage tools_interfacegenerator_usage "How to use InterfaceGenerator" + - \subpage tools_interfacegenerator_output "Use of InterfaceGenerator output" + - \subpage tools_interfacegenerator_architecture "InterfaceGenerator architecture" + - \subpage tools_interfacegenerator_cmakeintegration "Integration with CMake" +*/ diff --git a/src/components/policy/policy_external/doc/doxygen/tools/index.txt b/src/components/policy/policy_external/doc/doxygen/tools/index.txt new file mode 100644 index 0000000000..4befa33e8d --- /dev/null +++ b/src/components/policy/policy_external/doc/doxygen/tools/index.txt @@ -0,0 +1,5 @@ +/*! \page tools Tools + +Project uses following special tools: + - \subpage tools_interfacegenerator "InterfaceGenerator" +*/ diff --git a/src/components/policy/policy_external/doc/grc/conf.smartDeviceLinkCore b/src/components/policy/policy_external/doc/grc/conf.smartDeviceLinkCore new file mode 100644 index 0000000000..a026407723 --- /dev/null +++ b/src/components/policy/policy_external/doc/grc/conf.smartDeviceLinkCore @@ -0,0 +1,33 @@ +# source filename +regexp=\w+\.(?:cpp|h) +colours=yellow +=== +regexp=^(ERROR|FATAL) +colours=red on_yellow +=== +regexp=^WARN +colours=red +=== +regexp=^INFO +colours=blue +=== +regexp=^TRACE +colours=magenta +=== +# component +regexp=(?<=\])\[[^]]+\] +colours=cyan +=== +# something invalid +regexp=(?i)invalid +colours=red +=== +# RPC message start +regexp=^\{$ +colours=bold +count=block +=== +# RPC message end +regexp=^\}$ +colours=bold +count=unblock
\ No newline at end of file diff --git a/src/components/policy/policy_external/doc/grc/grc.conf b/src/components/policy/policy_external/doc/grc/grc.conf new file mode 100644 index 0000000000..dfd3d4cbef --- /dev/null +++ b/src/components/policy/policy_external/doc/grc/grc.conf @@ -0,0 +1,3 @@ +# smartDeviceCore command +(^|[/\w\.]+/)smartDeviceLinkCore\s? +conf.smartDeviceLinkCore diff --git a/src/components/policy/policy_external/doc/install.txt b/src/components/policy/policy_external/doc/install.txt new file mode 100644 index 0000000000..c870856e97 --- /dev/null +++ b/src/components/policy/policy_external/doc/install.txt @@ -0,0 +1,91 @@ +* Introduction + ================ + smartDeviceLinkCore is an application which manages the transport, connection and communication between a head unit and mobile device. + +* OS and Hardware + ========= + Ubuntu 12.04.01 LTS 32-bit OS on the PC with USB-dongle + Application has been tested using 2 types of USB-dongle: + D-Link DBT-122 + STLab B-121mini + +* External components + =================== + For build application we need: + libbluetooth3, the BlueZ library + libbluetooth-dev, the development files to link to the BluetZ library. + Install libraries: + sudo apt-get install libbluetooth3 + sudo apt-get install libbluetooth-dev + + We are using cmake to create build configurations. + Install cmake: + sudo apt-get install cmake + + Also, make sure the g++ compiler is installed: + sudo apt-get install g++ + + To start web-based HMI we need web-browser with web-socket RFC6455 support. + For example Google Chromium. Install it using: + sudo apt-get install chromium-browser + + To run InterfaceGenerator some python libraries are required and must be + installed with following command: + sudo pip install -r tools/InterfaceGenerator/requirements.txt + + For logging Apache log4cxx library is used. Install required packages with the following command: + sudo apt-get install liblog4cxx10 liblog4cxx10-dev + + For installing pulseaudio development files which neededfor audio management fetures run: + sudo apt-get install libpulse-dev + + For installing gstreamer development files which needed for audio management fetures: + First add gstreamer repositories to your apt source list (/etc/apt/sources.list): + deb http://ppa.launchpad.net/gstreamer-developers/ppa/ubuntu <distributive codename> main + deb-src http://ppa.launchpad.net/gstreamer-developers/ppa/ubuntu <distributive codename> main + use code name relevant to the Ubuntu version which you use instead of <distributive codename>. + Run: + sudo apt-get update + and: + sudo apt-get install gstreamer1.0* + +* Build application + ================= + We support "out of sources" concept for build from R3.0.0 + It means all generated by build tools files will be stored in separate folder. + Temporary build of application requires two steps. + 1. Enter src/thirdPartyLibs/logger + build logger: + + 1. Create directory outside of SmartDeviceLink project directory. + For example "build" folder in the same folder with SmartDeviceLink git repo folder which has a name "git_repo": + You will have folders structure like this: + /home/projects/smart_device_link + |--build + |--git_repo + |--doc + |--src + |--test + |--DoxyFile + \--CMakeLists.txt + Enter this folder: + cd build + + 2. Create build configuration using cmake: + 2.1 For Debug configuration + cmake ../git_repo + 2.2 For Release configuration, run: + cmake -DCMAKE_BUILD_TYPE=Release ../git_repo + 2.3 For Debug configuration with tests, run: + cmake -DBUILD_TESTS=On ../git_repo + + 3. Make project: + make + + Ready to use release application will be in build/src/appMain/smartDeviceLinkCore + + 4. If You built configuration with tests (see 2.3 above), then You can run all project tests and see overall result with: + make test + + 5. For creating the doxygen documentation run: + make doxygen
\ No newline at end of file diff --git a/src/components/policy/policy_external/doc/qnx_build.txt b/src/components/policy/policy_external/doc/qnx_build.txt new file mode 100644 index 0000000000..4f67d6eed3 --- /dev/null +++ b/src/components/policy/policy_external/doc/qnx_build.txt @@ -0,0 +1,28 @@ +Building the project +cmake -DCMAKE_TOOLCHAIN_FILE=../applink/qnx_6.5.0_linux_x86.cmake ../applink +or for Momentics project: +cmake -DCMAKE_TOOLCHAIN_FILE=../applink/qnx_6.5.0_linux_x86.cmake -G "Eclipse CDT4 - Unix Makefiles" ../applink + +Building with support D-Bus and Qt 4.8 +Install D-Bus (see https://adc.luxoft.com/confluence/x/0AHJDw) +Install Qt 4.8 (see https://adc.luxoft.com/confluence/x/UwfJDw) +cmake -DHMI2=ON -DCMAKE_TOOLCHAIN_FILE=../applink/qnx_6.5.0_linux_x86.cmake ../applink +or for Momentics project: +cmake -DHMI2=ON -DCMAKE_TOOLCHAIN_FILE=../applink/qnx_6.5.0_linux_x86.cmake -G "Eclipse CDT4 - Unix Makefiles" ../applink + +make +make install + +Running project: +Change server IP in configuration file to QNX target IP. +Copy directory bin to QNX target. +You can copy it using scp. Example: +scp -r user_name@linux_pc_ip:/full_path/to/dir . + +For Web HMI set target IP in ini file and change target IP in src/components/HMI/ffw/RPCClient.js +! Currently we don't have any configuration file for HMI. + +Execute smartDeviceLinkCore on QNX qtarget. +Execute HMI on Linux PC (only Web HMI). + +Have fun! diff --git a/src/components/policy/policy_external/doc/readme.txt b/src/components/policy/policy_external/doc/readme.txt new file mode 100644 index 0000000000..66087df057 --- /dev/null +++ b/src/components/policy/policy_external/doc/readme.txt @@ -0,0 +1,65 @@ +* Introduction + ================ + smartDeviceCore is an application which manages the transport, connection and communication between a head unit and mobile device. + +* OS and Hardware + ========= + Ubuntu 12.04.1 LTS 32-bit OS on the PC with USB-dongle + Application has been tested using 2 types of USB-dongle: + D-Link DBT-122 + STLab B-121mini + + * External components + =================== + For start application we need: + libbluetooth3, the BlueZ library + Install library: + sudo apt-get install libbluetooth3 + To start web-based HMI we need web-browser with web-socket RFC6455 support. + For example Google Chromium. Install it using: + sudo apt-get install chromium-browser + In current implementation Chromium is required for autostart HMI feature. + For HMI autostart please set path to hmi in config file + For example: + LinkToWebHMI = ${path_to_HMI_repository}/index.html + +* Running application + ==================== + Plug USB-dongle in. + Switch Bluetooth on a mobile device ON and make the device discoverable. + Pair mobile device with PC using Ubuntu tools. + Device should contain SmartDeviceLink compatible application installed. + Start application with command: + ./smartDeviceLinkCore + Application starts to search devices and starts HMI in cromium-browser. + In case HMI has not been started please start web-based HMI manually in browser opening src/components/HMI/index.html. + SmartDeviceLinkCore is searching Bluetooth devices with a correspondibg service. + Go to info menu in HMI and press App button. + Press change Devices button. + Select the device from a list. + Application opens all available ports on devices and starts communication. + Returning to the App menu all applications will be shown in a list. + +* Colorized logs + ============== + You can have colorized log output of smartDeviceLinkCore's messages in the terminal with the help of grc: + + 1. Make sure grc is installed: + sudo apt-get install grc + + 2. Copy the config files from the grc/ directory into ~/.grc/ directory: + mkdir ~/.grc + cp grc/* ~/.grc/ + + 3. Add an alias to your shell's config (usually, ~/.bashrc or ~/.zshrc): + alias grca='grc -es --colour=auto' + + Either restart the shell session or source the edited file: + source ~/.bashrc + or + source ~/.zshrc + + 4. Start the smartDeviceLink core with the following command: + grca ./smartDeviceLinkCore + + 5. PROFIT
\ No newline at end of file |