Update documentation to include Plugin Programming Guide and Plugin Documentation Template #644
Conversation
…ocumentation template
paulbourelly999
requested review from
DokurOmkar and
jwillmartin
and removed request for
DokurOmkar
examples/tmx-exampleapps/SampleBSMPlugin/src/SampleBSMPlugin.cpp
Outdated
Show resolved
Hide resolved
| @@ -2,4 +2,4 @@ PROJECT ( SampleBSMPlugin VERSION 5.0 LANGUAGES CXX ) | |||
|
|
|||
| BuildTmxPlugin ( ) | |||
|
|
|||
| TARGET_LINK_LIBRARIES (${PROJECT_NAME} tmxutils jsoncpp) | |||
There was a problem hiding this comment.
Nothing in the sample plugin uses json CPP
| @@ -0,0 +1,1233 @@ | |||
| # Programming Guide | |||
|
|
|||
| The V2X Hub Programming Guide was developed during the V2I Reference Implementation project for developers of plugins for the V2X Hub in supporting Connected Vehicle (CV) technology. This programming guide gives details on how to create a plugin for the V2X Hub based on the Example Plugin created by Battelle. The Example Plugin can be obtained from OSADP, along with the other V2X Hub software that you will need to compile and setup to do your own V2X Hub development. | |||
There was a problem hiding this comment.
Maybe add a link to Example Plugin? Not sure Who is Battelle, and OSADP?
There was a problem hiding this comment.
This comes directly from https://github.com/usdot-fhwa-OPS/V2X-Hub/blob/develop/docs/V2I_Hub_PluginProgrammingGuide_Final.pdf which can also be found as a word doc on confluence here https://usdot-carma.atlassian.net/wiki/spaces/V2XH/pages/1508311057/V2X+Hub+Project+Documentation?preview=/1508311057/1508311084/V2X_Hub_PluginProgrammingGuide_3-2.docx . I have simply copied it and reformatted it into markdown for easier maintenance.
As for a link the the SampleBsmPlugin, I included it in the parent page. I can link this one to the ExamplePlugin but I really want to work to consolidate these examples and have a single one. I was hoping to include this programming guide now without major revision and start revising individual parts as we continue to develop.
| - manifest.json | ||
| - README.md | ||
|
|
||
| The main source code for the plugin resides in the ExamplePlugin.cpp file. This C++ class extends the PluginClient class from the V2X Hub API. The PluginClient has methods that can be overwritten to retrieve settings and messages. The next section will describe the source code needed to do the basic functionality for a plugin, and chapter 2 will walk through the process of creating a plugin based on the Example Plugin. The SampleData files are simply examples on how to include other C++ source files into a V2X Hub Plugin. They are currently not used. |
There was a problem hiding this comment.
PluginClient or ClockAwarePlugin?
There was a problem hiding this comment.
Not seeing SampleData files?
There was a problem hiding this comment.
Its refering to the ExamplePlugin SampleData.cpp. I will correct the part of this referring to the wrong base class but I want to save correction related to the example plugin for a story in the Update Documentation epic to revise/consolidate our example/tutorial plugin.
|
|
||
| The CMakeLists.txt file contains the needed information for cmake to create the make files needed to compile the project. When creating a new plugin, this file will need to be modified with the plugins information. | ||
|
|
||
| The manifest.json file is used by the V2X Hub Core to setup communications between the core and plugin. The file contains a description of the plugin, the executable location, the IP address of the V2X Hub running the core application, port information for communication, messages that are produced by this plugin, and then finally the configuration values for the plugin. The majority of this file will remain untouched, except for the configuration, messageTypes, and description sections. More detail will be given on the modification of those sections in chapter 2. |
There was a problem hiding this comment.
Provide link to chapter 2?
There was a problem hiding this comment.
Chapter 2 is in this document
|
|
||
| In the former case, the Plugin will retrieve its configured value with the key “Instance” and store that value as an integer into the variable `instance`. If the key is found in the configuration database for that plugin, it will set the `instance` variable to the value found in that database. Since all data is stored as strings, there is an implicit conversion (using the default lexical cast from [Boost](http://www.boost.org/doc/libs/1_58_0/doc/html/boost_lexical_cast.html)) to an integer type. If the conversion fails, or the key is not found, then the variable is unset. In the code above, this could lead to a programming error because there is no default value for the variable. Also, note that in this example `instance` is defined locally, thus can only be used within the scope of that variable. | ||
|
|
||
| In the second example, the “Frequency” parameter is retrieved and stored in a class variable. This could be the simple private variable `__frequency`, which is a thread-safe “atomic” variable of unsigned integer type. However, this example also uses some redirection provided by the V2X Hub Plugin API to add some desired functionality. The PluginDataMonitor.h header adds a type accessible by the macro `DATA_MONITOR()` that wraps `__frequency` inside a class that knows when that parameter actually changed values. A common use case would be to log a message that the value has changed. In the UpdateConfigSettings excerpt above, the value of `__frequency`is updated when the `get()` function returns that reference out of the wrapper class. See the Data Monitor section for more on using data monitors. |
There was a problem hiding this comment.
Where is this PluginDataMonitor.h ?
There was a problem hiding this comment.
It is a class in TMX Core
| SubscribeToMessage() | ||
| ``` | ||
|
|
||
| The SubscribeToMessages function must be called after the filters are setup, otherwise the plugin will not receive the wanted messages. This function can be invoked more than once, if other filters are added. Currently, the only way to un-subscribe to a message is to restart the plugin. |
There was a problem hiding this comment.
How would restarting the plugin allow to un-subscribe messages?
There was a problem hiding this comment.
That is how the plugin class works.
|
paulbourelly999
deleted the
vh-1337-v2xhub-plugin-documentation-template
branch
PR Details
Description
This PR includes improvements to our documentation. Specifically we have taken the Plugin Programming Guide and converted it to a Mark Down file included in the
src/v2i-hubdirectory. Additionally we have deleted redundant example plugins.Related Issue
VH-1337
Motivation and Context
Improve development documentation
How Has This Been Tested?
NA
Types of changes
Checklist:
V2XHUB Contributing Guide