diff --git a/en/README.md b/en/README.md index 12f3cac..4b8ded4 100644 --- a/en/README.md +++ b/en/README.md @@ -64,7 +64,6 @@ The most important classes are: - [Gimbal](/api_reference/classdronecore_1_1_gimbal.md): Control a gimbal. - [FollowMe](/api_reference/classdronecore_1_1_follow_me.md): Drone tracks a position supplied by DroneCore. - [Logging](/api_reference/classdronecore_1_1_logging.md): Data logging and streaming from the vehicle. -- [include/device_plugin_container.h.in](https://github.com/dronecore/DroneCore/blob/{{ book.github_branch }}/include/device_plugin_container.h.in): Auto-generated file that is required for DroneCore plugin development - see [DevicePluginContainer](/api_reference/classdronecore_1_1_device_plugin_container.md). ## Getting Started @@ -78,8 +77,8 @@ Developers who want to contribute to the API will need to build the C++ library This guide contains information and examples showing how to use DroneCore. If you have specific questions that are not answered by the documentation, these can be raised on: -* [Slack DroneCore Channel](https://px4.slack.com/messages/C68J8H32A) (get a [Slack login here](http://slack.px4.io)) * [Discuss board](http://discuss.px4.io/c/dronecore) +* [Slack DroneCore Channel](https://px4.slack.com/messages/C68J8H32A) (get a [Slack login here](http://slack.px4.io)) Use Github for bug reports/enhancement requests: diff --git a/en/SUMMARY.md b/en/SUMMARY.md index 036b3d3..c943194 100644 --- a/en/SUMMARY.md +++ b/en/SUMMARY.md @@ -6,9 +6,10 @@ * [Guide](guide/README.md) * [Usage/Paradigms](guide/general_usage.md) * [Connecting to Devices](guide/connections.md) + * [Managing Devices](guide/using_plugins.md) * [Vehicle Information](guide/device_version.md) * [Telemetry](guide/telemetry.md) - * [Taking Off and Landing](guide/taking_off_landing.md) + * [Actions - Take Off, Arm, ...](guide/taking_off_landing.md) * [Missions](guide/missions.md) * [Offboard Control](guide/offboard.md) * [Follow Me](guide/follow_me.md) @@ -46,7 +47,6 @@ * [struct Config](api_reference/structdronecore_1_1_follow_me_1_1_config.md) * [struct TargetLocation ](api_reference/structdronecore_1_1_follow_me_1_1_target_location.md) * [class Logging](api_reference/classdronecore_1_1_logging.md) - * [class DevicePluginContainer](api_reference/classdronecore_1_1_device_plugin_container.md) * [Contributing](contributing/README.md) * [Building Source](contributing/build.md) * [Testing](contributing/test.md) diff --git a/en/api_reference/README.md b/en/api_reference/README.md index b102051..94aae6a 100644 --- a/en/api_reference/README.md +++ b/en/api_reference/README.md @@ -24,5 +24,4 @@ * [class FollowMe](classdronecore_1_1_follow_me.md) * [struct Config](structdronecore_1_1_follow_me_1_1_config.md) * [struct TargetLocation ](structdronecore_1_1_follow_me_1_1_target_location.md) -* [class Logging](classdronecore_1_1_logging.md) -* [class DevicePluginContainer](classdronecore_1_1_device_plugin_container.md) \ No newline at end of file +* [class Logging](classdronecore_1_1_logging.md) \ No newline at end of file diff --git a/en/api_reference/classdronecore_1_1_action.md b/en/api_reference/classdronecore_1_1_action.md index d515a99..9856772 100644 --- a/en/api_reference/classdronecore_1_1_action.md +++ b/en/api_reference/classdronecore_1_1_action.md @@ -26,7 +26,7 @@ std::function< void([Result](classdronecore_1_1_action.md#classdronecore_1_1_act Type | Name | Description ---: | --- | --- -| [Action](#classdronecore_1_1_action_1a4d54f66fbb7629198d5d2f5f261261c0) (ActionImpl *impl) | Constructor (internal use only). +| [Action](#classdronecore_1_1_action_1a9fd3af84d59048b3c787ed0c5644ed07) (Device *device) | Constructor. Creates the plugin and associates it with a specified [Device](classdronecore_1_1_device.md). | [~Action](#classdronecore_1_1_action_1a6bb0301fecf66d75ca3b27bda25af7f2) () | Destructor (internal use only). | [Action](#classdronecore_1_1_action_1ae48b0e06ca2b4b7544a10c7734a03f63) (const Action &)=delete | Copy constructor (object is not copyable). [Result](classdronecore_1_1_action.md#classdronecore_1_1_action_1ad92c9d2e08f60f54b17ea0d861339011) | [arm](#classdronecore_1_1_action_1a8b8631ea15655f0c922a9ba7d2e1c72c) () const | Send command to *arm* the drone (synchronous). @@ -62,18 +62,23 @@ const char * | [result_str](#classdronecore_1_1_action_1a1fefb474ee36cb15fe31b42 ## Constructor & Destructor Documentation -### Action() {#classdronecore_1_1_action_1a4d54f66fbb7629198d5d2f5f261261c0} +### Action() {#classdronecore_1_1_action_1a9fd3af84d59048b3c787ed0c5644ed07} ```cpp -dronecore::Action::Action(ActionImpl *impl) +dronecore::Action::Action(Device *device) ``` +Constructor. Creates the plugin for a specific [Device](classdronecore_1_1_device.md). -Constructor (internal use only). +The plugin is typically created as shown below: + +```cpp +auto action = std::make_shared(&device); +``` **Parameters** -* ActionImpl * **impl** - Private internal implementation. +* [Device](classdronecore_1_1_device.md) * **device** - The specific device associated with this plugin. ### ~Action() {#classdronecore_1_1_action_1a6bb0301fecf66d75ca3b27bda25af7f2} ```cpp diff --git a/en/api_reference/classdronecore_1_1_device.md b/en/api_reference/classdronecore_1_1_device.md index ded2052..9547469 100644 --- a/en/api_reference/classdronecore_1_1_device.md +++ b/en/api_reference/classdronecore_1_1_device.md @@ -1,57 +1,96 @@ # dronecore::Device Class Reference -`#include: device.h` +`#include: UNKNOWN` ---- -A [Device](classdronecore_1_1_device.md) represents a vehicle such as a drone or robot. +## Data Structures -A device can consist of multiple components such as an autopilot with a gimbal and camera. +struct [MavlinkHandlerTableEntry](structdronecore_1_1_device_1_1_mavlink_handler_table_entry.md) +## Public Types -This class is derived from [DevicePluginContainer](classdronecore_1_1_device_plugin_container.md), which provides methods to access plugin classes like [Action](classdronecore_1_1_action.md), [Telemetry](classdronecore_1_1_telemetry.md), [Info](classdronecore_1_1_info.md), [Logging](classdronecore_1_1_logging.md), [Offboard](classdronecore_1_1_offboard.md) and [Mission](classdronecore_1_1_mission.md) (for example, using [DroneCore::device()](classdronecore_1_1_drone_core.md#classdronecore_1_1_drone_core_1a5bac6e419e56a1f77a51adef98e94e7c).[action()](classdronecore_1_1_device_plugin_container.md#classdronecore_1_1_device_plugin_container_1aea48bd55b1ace227ebb56690794c2192)...). +Type | Description +--- | --- +enum [FlightMode](#classdronecore_1_1_device_1abe2b638e92f46ad3bdc124429a5929e8) | +std::function< void(const mavlink_message_t &)> [mavlink_message_handler_t](#classdronecore_1_1_device_1a1bca06c484ee8a4f18f0371a2a492e7b) | +std::function< void(MavlinkCommands::Result, float)> [command_result_callback_t](#classdronecore_1_1_device_1a6ee9b5b6b3d40554ced23537168d801e) | +std::function< void(bool success)> [success_t](#classdronecore_1_1_device_1aa90d45a543d894492d30618438e5ced4) | +std::function< void(bool success, float value)> [get_param_float_callback_t](#classdronecore_1_1_device_1a8eabc97aec9a0ac69f79df2caabd8687) | +std::function< void(bool success, int32_t value)> [get_param_int_callback_t](#classdronecore_1_1_device_1a38ead6807abd7c8d72a8cf3909b4560d) | -**NOTE** The content of [DevicePluginContainer](classdronecore_1_1_device_plugin_container.md), and hence the available accessors, are auto-generated at compile time. - - -[Device](classdronecore_1_1_device.md) objects are not created or destroyed directly by API consumers. They are accessed using, for example, [DroneCore::device()](classdronecore_1_1_drone_core.md#classdronecore_1_1_drone_core_1a5bac6e419e56a1f77a51adef98e94e7c) and cleaned up when [DroneCore](classdronecore_1_1_drone_core.md) is destroyed. +## Public Member Functions -## Public Member Functions +Type | Name | Description +---: | --- | --- +| [Device](#classdronecore_1_1_device_1af07b4defa38736ce928377af2f31fb6e) (DroneCoreImpl *parent, uint8_t target_system_id) | +| [~Device](#classdronecore_1_1_device_1a65c697e12eed30109074e18a9cfdc836) () | +| [Device](#classdronecore_1_1_device_1acf95b02d5d1d705ce3dc1438786e0c91) (const Device &)=delete | +void | [process_mavlink_message](#classdronecore_1_1_device_1a7324f5f4cc1f7bce40a2e8c237f1212e) (const mavlink_message_t &message) | +void | [register_mavlink_message_handler](#classdronecore_1_1_device_1aa7ae3afa910a2043185e319cfaaa4196) (uint16_t msg_id, mavlink_message_handler_t callback, const void *cookie) | +void | [unregister_all_mavlink_message_handlers](#classdronecore_1_1_device_1a7fd2014818f2e41cc93b6c31d259f21c) (const void *cookie) | +void | [register_timeout_handler](#classdronecore_1_1_device_1afc704e09b8331cdd36341a1ffd331c11) (std::function< void()> callback, double duration_s, void **cookie) | +void | [refresh_timeout_handler](#classdronecore_1_1_device_1ad7d945426276c079ffc9d173583d1427) (const void *cookie) | +void | [unregister_timeout_handler](#classdronecore_1_1_device_1a95673878b3a69db3817def10310a565d) (const void *cookie) | +void | [add_call_every](#classdronecore_1_1_device_1a466bede03fdf9be31cefb206ef561114) (std::function< void()> callback, float interval_s, void **cookie) | +void | [change_call_every](#classdronecore_1_1_device_1aed059a1d5a9f2ee4e11963e5d371577c) (float interval_s, const void *cookie) | +void | [reset_call_every](#classdronecore_1_1_device_1a38c719f6ccadf6a17e61c47c14cdf234) (const void *cookie) | +void | [remove_call_every](#classdronecore_1_1_device_1a5a101b41ec651a6a764a01d3208934e2) (const void *cookie) | +bool | [send_message](#classdronecore_1_1_device_1a9d09cd1b8b9689080337f7efd9e9d77d) (const mavlink_message_t &message) | +MavlinkCommands::Result | [send_command_with_ack](#classdronecore_1_1_device_1afcc8c11d47f681c41705d82ee3cd74ea) (uint16_t command, const MavlinkCommands::Params ¶ms, uint8_t component_id=0) | +void | [send_command_with_ack_async](#classdronecore_1_1_device_1a0ef6cf5c11820fb2ae00bd96f9abd4de) (uint16_t command, const MavlinkCommands::Params ¶ms, command_result_callback_t callback, uint8_t component_id=0) | +MavlinkCommands::Result | [set_msg_rate](#classdronecore_1_1_device_1af10ca5a146f0129c51566486a20d98ed) (uint16_t message_id, double rate_hz, uint8_t component_id=0) | +void | [set_msg_rate_async](#classdronecore_1_1_device_1ad3af9775d80d5301c19808822da6f9aa) (uint16_t message_id, double rate_hz, command_result_callback_t callback, uint8_t component_id=0) | +void | [request_autopilot_version](#classdronecore_1_1_device_1abd185340eaad71374b8f8647a5594502) () | +uint64_t | [get_target_uuid](#classdronecore_1_1_device_1a54bdadb4e8e52c9d159099749c29b7b4) () const | +uint8_t | [get_target_system_id](#classdronecore_1_1_device_1a55d2b2b871b2435420885b9594ca5b9b) () const | +uint8_t | [get_target_component_id](#classdronecore_1_1_device_1a41f2b9cf224c09d0c17081620ac201c5) () const | +void | [set_target_system_id](#classdronecore_1_1_device_1a01f14b9dffc35b045bbfe76f411c84f8) (uint8_t system_id) | +bool | [target_supports_mission_int](#classdronecore_1_1_device_1afbe6f90ecace24d8b7081a01be3686c3) () const | +bool | [is_armed](#classdronecore_1_1_device_1ad8b067dc607c3fd7bd86c2961409ce60) () const | +void | [set_param_float_async](#classdronecore_1_1_device_1a1b784f4c51451f23cb978b1982ead1bf) (const std::string &name, float value, success_t callback) | +void | [set_param_int_async](#classdronecore_1_1_device_1aa8fe748620f9934df97582943b20b372) (const std::string &name, int32_t value, success_t callback) | +void | [set_param_ext_float_async](#classdronecore_1_1_device_1a46ca0087cd5135a12a9f163455876fe2) (const std::string &name, float value, success_t callback) | +void | [set_param_ext_int_async](#classdronecore_1_1_device_1ab494873b3e6e99706c89c669d867c0bf) (const std::string &name, int32_t value, success_t callback) | +MavlinkCommands::Result | [set_flight_mode](#classdronecore_1_1_device_1acafac8ecf0801045ad894e80bcd9d9a8) (FlightMode mode) | +void | [set_flight_mode_async](#classdronecore_1_1_device_1a56d240c32839524470a8784f5c72e8a0) (FlightMode mode, command_result_callback_t callback) | +void | [get_param_float_async](#classdronecore_1_1_device_1a48dbd54b03ad86c9784dfac75274713f) (const std::string &name, get_param_float_callback_t callback) | +void | [get_param_int_async](#classdronecore_1_1_device_1a682a74475e24cac262ac90b18e5dd49a) (const std::string &name, get_param_int_callback_t callback) | +void | [get_param_ext_float_async](#classdronecore_1_1_device_1a6050f2993f78689c778cdb4240bb3606) (const std::string &name, get_param_float_callback_t callback) | +void | [get_param_ext_int_async](#classdronecore_1_1_device_1a7b4050c8aa12e198d99b23be4f281c7f) (const std::string &name, get_param_int_callback_t callback) | +bool | [is_connected](#classdronecore_1_1_device_1afac855ffb266017d932c4060140af717) () const | +Time & | [get_time](#classdronecore_1_1_device_1a6009c92dbd4ffd14367ad4ee1d4b3054) () | +void | [register_plugin](#classdronecore_1_1_device_1a7622b2667c5454c490a0d6722f738ec3) (PluginImplBase *plugin_impl) | +void | [unregister_plugin](#classdronecore_1_1_device_1aac00d6ae3d53154900785b882df5edf4) (PluginImplBase *plugin_impl) | +void | [lock_communication](#classdronecore_1_1_device_1a15d93e6a12f2208f8fa56466b7f2f819) () | +void | [unlock_communication](#classdronecore_1_1_device_1a801aab463023eb3e64670c86349fa54c) () | +const [Device](classdronecore_1_1_device.md) & | [operator=](#classdronecore_1_1_device_1ad03d3cdf0aaa8e4cb21becb6c7806c33) (const Device &)=delete | + +## Static Public Member Functions Type | Name | Description ---: | --- | --- -| [Device](#classdronecore_1_1_device_1aa64ba685fe110fcb0a8e1b92156f144b) (DeviceImpl *impl) | Constructor (internal use only). -| [~Device](#classdronecore_1_1_device_1a65c697e12eed30109074e18a9cfdc836) () | Destructor (internal use only). -[Info](classdronecore_1_1_info.md) & | [info](#classdronecore_1_1_device_plugin_container_1a1509e3d7a469cbc3e33471138b1f4dc7) () | -[Logging](classdronecore_1_1_logging.md) & | [logging](#classdronecore_1_1_device_plugin_container_1a0551f966021bdbd9e41700232c33d379) () | -[Telemetry](classdronecore_1_1_telemetry.md) & | [telemetry](#classdronecore_1_1_device_plugin_container_1a9b119348d0f5195c9b0919fbe6196b14) () | -[FollowMe](classdronecore_1_1_follow_me.md) & | [follow_me](#classdronecore_1_1_device_plugin_container_1ae13164c3bb59230c559341b8506c5e03) () | -[Action](classdronecore_1_1_action.md) & | [action](#classdronecore_1_1_device_plugin_container_1aea48bd55b1ace227ebb56690794c2192) () | -[Gimbal](classdronecore_1_1_gimbal.md) & | [gimbal](#classdronecore_1_1_device_plugin_container_1a2fce9f439c565af9a8510c5746c728f0) () | -[Offboard](classdronecore_1_1_offboard.md) & | [offboard](#classdronecore_1_1_device_plugin_container_1a63193bd25273bbda48665e12e012f478) () | -[Mission](classdronecore_1_1_mission.md) & | [mission](#classdronecore_1_1_device_plugin_container_1a8a05778326d0ef4c74146bc42fdcb52d) () | +uint8_t | [get_own_system_id](#classdronecore_1_1_device_1ab598504aa60a5acf830161daf8eed908) () | +uint8_t | [get_own_component_id](#classdronecore_1_1_device_1aa6dc1543b0ae9439a6bacca0dc9c52e6) () | ## Constructor & Destructor Documentation -### Device() {#classdronecore_1_1_device_1aa64ba685fe110fcb0a8e1b92156f144b} +### Device() {#classdronecore_1_1_device_1af07b4defa38736ce928377af2f31fb6e} ```cpp -dronecore::Device::Device(DeviceImpl *impl) +dronecore::Device::Device(DroneCoreImpl *parent, uint8_t target_system_id) ``` -Constructor (internal use only). - -This constructor does not need to be called by any consumer of the API. - **Parameters** -* DeviceImpl * **impl** - The underlying device implementation. +* DroneCoreImpl * **parent** - +* uint8_t **target_system_id** - ### ~Device() {#classdronecore_1_1_device_1a65c697e12eed30109074e18a9cfdc836} ```cpp @@ -59,105 +98,517 @@ dronecore::Device::~Device() ``` -Destructor (internal use only). +### Device() {#classdronecore_1_1_device_1acf95b02d5d1d705ce3dc1438786e0c91} +```cpp +dronecore::Device::Device(const Device &)=delete +``` + + +**Parameters** + +* const [Device](classdronecore_1_1_device.md) & - + +## Member Typdef Documentation + + +### typedef mavlink_message_handler_t {#classdronecore_1_1_device_1a1bca06c484ee8a4f18f0371a2a492e7b} + +```cpp +typedef std::function dronecore::Device::mavlink_message_handler_t +``` + + +### typedef command_result_callback_t {#classdronecore_1_1_device_1a6ee9b5b6b3d40554ced23537168d801e} + +```cpp +typedef std::function dronecore::Device::command_result_callback_t +``` + + +### typedef success_t {#classdronecore_1_1_device_1aa90d45a543d894492d30618438e5ced4} + +```cpp +typedef std::function dronecore::Device::success_t +``` + + +### typedef get_param_float_callback_t {#classdronecore_1_1_device_1a8eabc97aec9a0ac69f79df2caabd8687} + +```cpp +typedef std::function dronecore::Device::get_param_float_callback_t +``` -The destructor of [Device](classdronecore_1_1_device.md) does not need to be called by any consumer of the API. + +### typedef get_param_int_callback_t {#classdronecore_1_1_device_1a38ead6807abd7c8d72a8cf3909b4560d} + +```cpp +typedef std::function dronecore::Device::get_param_int_callback_t +``` + + +## Member Enumeration Documentation + + +### enum FlightMode {#classdronecore_1_1_device_1abe2b638e92f46ad3bdc124429a5929e8} + + +Value | Description +--- | --- + `HOLD` | + `RETURN_TO_LAUNCH` | + `TAKEOFF` | + `LAND` | + `MISSION` | + `FOLLOW_ME` | + `OFFBOARD` | ## Member Function Documentation -### info() {#classdronecore_1_1_device_plugin_container_1a1509e3d7a469cbc3e33471138b1f4dc7} +### process_mavlink_message() {#classdronecore_1_1_device_1a7324f5f4cc1f7bce40a2e8c237f1212e} +```cpp +void dronecore::Device::process_mavlink_message(const mavlink_message_t &message) +``` + + +**Parameters** + +* const mavlink_message_t & **message** - + +### register_mavlink_message_handler() {#classdronecore_1_1_device_1aa7ae3afa910a2043185e319cfaaa4196} +```cpp +void dronecore::Device::register_mavlink_message_handler(uint16_t msg_id, mavlink_message_handler_t callback, const void *cookie) +``` + + +**Parameters** + +* uint16_t **msg_id** - +* mavlink_message_handler_t **callback** - +* const void * **cookie** - + +### unregister_all_mavlink_message_handlers() {#classdronecore_1_1_device_1a7fd2014818f2e41cc93b6c31d259f21c} +```cpp +void dronecore::Device::unregister_all_mavlink_message_handlers(const void *cookie) +``` + + +**Parameters** + +* const void * **cookie** - + +### register_timeout_handler() {#classdronecore_1_1_device_1afc704e09b8331cdd36341a1ffd331c11} +```cpp +void dronecore::Device::register_timeout_handler(std::function< void()> callback, double duration_s, void **cookie) +``` + + +**Parameters** + +* std::function< void()> **callback** - +* double **duration_s** - +* void ** **cookie** - + +### refresh_timeout_handler() {#classdronecore_1_1_device_1ad7d945426276c079ffc9d173583d1427} +```cpp +void dronecore::Device::refresh_timeout_handler(const void *cookie) +``` + + +**Parameters** + +* const void * **cookie** - + +### unregister_timeout_handler() {#classdronecore_1_1_device_1a95673878b3a69db3817def10310a565d} +```cpp +void dronecore::Device::unregister_timeout_handler(const void *cookie) +``` + + +**Parameters** + +* const void * **cookie** - + +### add_call_every() {#classdronecore_1_1_device_1a466bede03fdf9be31cefb206ef561114} +```cpp +void dronecore::Device::add_call_every(std::function< void()> callback, float interval_s, void **cookie) +``` + + +**Parameters** + +* std::function< void()> **callback** - +* float **interval_s** - +* void ** **cookie** - + +### change_call_every() {#classdronecore_1_1_device_1aed059a1d5a9f2ee4e11963e5d371577c} +```cpp +void dronecore::Device::change_call_every(float interval_s, const void *cookie) +``` + + +**Parameters** + +* float **interval_s** - +* const void * **cookie** - + +### reset_call_every() {#classdronecore_1_1_device_1a38c719f6ccadf6a17e61c47c14cdf234} +```cpp +void dronecore::Device::reset_call_every(const void *cookie) +``` + + +**Parameters** + +* const void * **cookie** - + +### remove_call_every() {#classdronecore_1_1_device_1a5a101b41ec651a6a764a01d3208934e2} +```cpp +void dronecore::Device::remove_call_every(const void *cookie) +``` + + +**Parameters** + +* const void * **cookie** - + +### send_message() {#classdronecore_1_1_device_1a9d09cd1b8b9689080337f7efd9e9d77d} +```cpp +bool dronecore::Device::send_message(const mavlink_message_t &message) +``` + + +**Parameters** + +* const mavlink_message_t & **message** - + +**Returns** + + bool - + +### send_command_with_ack() {#classdronecore_1_1_device_1afcc8c11d47f681c41705d82ee3cd74ea} +```cpp +MavlinkCommands::Result dronecore::Device::send_command_with_ack(uint16_t command, const MavlinkCommands::Params ¶ms, uint8_t component_id=0) +``` + + +**Parameters** + +* uint16_t **command** - +* const MavlinkCommands::Params & **params** - +* uint8_t **component_id** - + +**Returns** + + MavlinkCommands::Result - + +### send_command_with_ack_async() {#classdronecore_1_1_device_1a0ef6cf5c11820fb2ae00bd96f9abd4de} +```cpp +void dronecore::Device::send_command_with_ack_async(uint16_t command, const MavlinkCommands::Params ¶ms, command_result_callback_t callback, uint8_t component_id=0) +``` + + +**Parameters** + +* uint16_t **command** - +* const MavlinkCommands::Params & **params** - +* command_result_callback_t **callback** - +* uint8_t **component_id** - + +### set_msg_rate() {#classdronecore_1_1_device_1af10ca5a146f0129c51566486a20d98ed} ```cpp -Info& dronecore::DevicePluginContainer::info() +MavlinkCommands::Result dronecore::Device::set_msg_rate(uint16_t message_id, double rate_hz, uint8_t component_id=0) ``` -Getter for [Info](classdronecore_1_1_info.md) plugin. +**Parameters** + +* uint16_t **message_id** - +* double **rate_hz** - +* uint8_t **component_id** - **Returns** - [Info](classdronecore_1_1_info.md) & - a reference to the info plugin instance + MavlinkCommands::Result - + +### set_msg_rate_async() {#classdronecore_1_1_device_1ad3af9775d80d5301c19808822da6f9aa} +```cpp +void dronecore::Device::set_msg_rate_async(uint16_t message_id, double rate_hz, command_result_callback_t callback, uint8_t component_id=0) +``` + + +**Parameters** + +* uint16_t **message_id** - +* double **rate_hz** - +* command_result_callback_t **callback** - +* uint8_t **component_id** - -### logging() {#classdronecore_1_1_device_plugin_container_1a0551f966021bdbd9e41700232c33d379} +### request_autopilot_version() {#classdronecore_1_1_device_1abd185340eaad71374b8f8647a5594502} ```cpp -Logging& dronecore::DevicePluginContainer::logging() +void dronecore::Device::request_autopilot_version() ``` -Getter for [Logging](classdronecore_1_1_logging.md) plugin. +### get_target_uuid() {#classdronecore_1_1_device_1a54bdadb4e8e52c9d159099749c29b7b4} +```cpp +uint64_t dronecore::Device::get_target_uuid() const +``` + **Returns** - [Logging](classdronecore_1_1_logging.md) & - a reference to the logging plugin instance + uint64_t - -### telemetry() {#classdronecore_1_1_device_plugin_container_1a9b119348d0f5195c9b0919fbe6196b14} +### get_target_system_id() {#classdronecore_1_1_device_1a55d2b2b871b2435420885b9594ca5b9b} ```cpp -Telemetry& dronecore::DevicePluginContainer::telemetry() +uint8_t dronecore::Device::get_target_system_id() const ``` -Getter for [Telemetry](classdronecore_1_1_telemetry.md) plugin. +**Returns** + + uint8_t - + +### get_target_component_id() {#classdronecore_1_1_device_1a41f2b9cf224c09d0c17081620ac201c5} +```cpp +uint8_t dronecore::Device::get_target_component_id() const +``` + **Returns** - [Telemetry](classdronecore_1_1_telemetry.md) & - a reference to the telemetry plugin instance + uint8_t - -### follow_me() {#classdronecore_1_1_device_plugin_container_1ae13164c3bb59230c559341b8506c5e03} +### set_target_system_id() {#classdronecore_1_1_device_1a01f14b9dffc35b045bbfe76f411c84f8} ```cpp -FollowMe& dronecore::DevicePluginContainer::follow_me() +void dronecore::Device::set_target_system_id(uint8_t system_id) ``` -Getter for [FollowMe](classdronecore_1_1_follow_me.md) plugin. +**Parameters** + +* uint8_t **system_id** - + +### target_supports_mission_int() {#classdronecore_1_1_device_1afbe6f90ecace24d8b7081a01be3686c3} +```cpp +bool dronecore::Device::target_supports_mission_int() const +``` + **Returns** - [FollowMe](classdronecore_1_1_follow_me.md) & - a reference to the follow_me plugin instance + bool - -### action() {#classdronecore_1_1_device_plugin_container_1aea48bd55b1ace227ebb56690794c2192} +### is_armed() {#classdronecore_1_1_device_1ad8b067dc607c3fd7bd86c2961409ce60} ```cpp -Action& dronecore::DevicePluginContainer::action() +bool dronecore::Device::is_armed() const ``` -Getter for [Action](classdronecore_1_1_action.md) plugin. +**Returns** + + bool - + +### set_param_float_async() {#classdronecore_1_1_device_1a1b784f4c51451f23cb978b1982ead1bf} +```cpp +void dronecore::Device::set_param_float_async(const std::string &name, float value, success_t callback) +``` + + +**Parameters** + +* const std::string & **name** - +* float **value** - +* success_t **callback** - + +### set_param_int_async() {#classdronecore_1_1_device_1aa8fe748620f9934df97582943b20b372} +```cpp +void dronecore::Device::set_param_int_async(const std::string &name, int32_t value, success_t callback) +``` + + +**Parameters** + +* const std::string & **name** - +* int32_t **value** - +* success_t **callback** - + +### set_param_ext_float_async() {#classdronecore_1_1_device_1a46ca0087cd5135a12a9f163455876fe2} +```cpp +void dronecore::Device::set_param_ext_float_async(const std::string &name, float value, success_t callback) +``` + + +**Parameters** + +* const std::string & **name** - +* float **value** - +* success_t **callback** - + +### set_param_ext_int_async() {#classdronecore_1_1_device_1ab494873b3e6e99706c89c669d867c0bf} +```cpp +void dronecore::Device::set_param_ext_int_async(const std::string &name, int32_t value, success_t callback) +``` + + +**Parameters** + +* const std::string & **name** - +* int32_t **value** - +* success_t **callback** - + +### set_flight_mode() {#classdronecore_1_1_device_1acafac8ecf0801045ad894e80bcd9d9a8} +```cpp +MavlinkCommands::Result dronecore::Device::set_flight_mode(FlightMode mode) +``` + + +**Parameters** + +* FlightMode **mode** - **Returns** - [Action](classdronecore_1_1_action.md) & - a reference to the action plugin instance + MavlinkCommands::Result - -### gimbal() {#classdronecore_1_1_device_plugin_container_1a2fce9f439c565af9a8510c5746c728f0} +### set_flight_mode_async() {#classdronecore_1_1_device_1a56d240c32839524470a8784f5c72e8a0} ```cpp -Gimbal& dronecore::DevicePluginContainer::gimbal() +void dronecore::Device::set_flight_mode_async(FlightMode mode, command_result_callback_t callback) ``` -Getter for [Gimbal](classdronecore_1_1_gimbal.md) plugin. +**Parameters** + +* FlightMode **mode** - +* command_result_callback_t **callback** - + +### get_param_float_async() {#classdronecore_1_1_device_1a48dbd54b03ad86c9784dfac75274713f} +```cpp +void dronecore::Device::get_param_float_async(const std::string &name, get_param_float_callback_t callback) +``` + + +**Parameters** + +* const std::string & **name** - +* get_param_float_callback_t **callback** - + +### get_param_int_async() {#classdronecore_1_1_device_1a682a74475e24cac262ac90b18e5dd49a} +```cpp +void dronecore::Device::get_param_int_async(const std::string &name, get_param_int_callback_t callback) +``` + + +**Parameters** + +* const std::string & **name** - +* get_param_int_callback_t **callback** - + +### get_param_ext_float_async() {#classdronecore_1_1_device_1a6050f2993f78689c778cdb4240bb3606} +```cpp +void dronecore::Device::get_param_ext_float_async(const std::string &name, get_param_float_callback_t callback) +``` + + +**Parameters** + +* const std::string & **name** - +* get_param_float_callback_t **callback** - + +### get_param_ext_int_async() {#classdronecore_1_1_device_1a7b4050c8aa12e198d99b23be4f281c7f} +```cpp +void dronecore::Device::get_param_ext_int_async(const std::string &name, get_param_int_callback_t callback) +``` + + +**Parameters** + +* const std::string & **name** - +* get_param_int_callback_t **callback** - + +### is_connected() {#classdronecore_1_1_device_1afac855ffb266017d932c4060140af717} +```cpp +bool dronecore::Device::is_connected() const +``` + + +**Returns** + + bool - + +### get_time() {#classdronecore_1_1_device_1a6009c92dbd4ffd14367ad4ee1d4b3054} +```cpp +Time& dronecore::Device::get_time() +``` + **Returns** - [Gimbal](classdronecore_1_1_gimbal.md) & - a reference to the gimbal plugin instance + Time & - + +### register_plugin() {#classdronecore_1_1_device_1a7622b2667c5454c490a0d6722f738ec3} +```cpp +void dronecore::Device::register_plugin(PluginImplBase *plugin_impl) +``` + + +**Parameters** + +* PluginImplBase * **plugin_impl** - + +### unregister_plugin() {#classdronecore_1_1_device_1aac00d6ae3d53154900785b882df5edf4} +```cpp +void dronecore::Device::unregister_plugin(PluginImplBase *plugin_impl) +``` + + +**Parameters** + +* PluginImplBase * **plugin_impl** - -### offboard() {#classdronecore_1_1_device_plugin_container_1a63193bd25273bbda48665e12e012f478} +### lock_communication() {#classdronecore_1_1_device_1a15d93e6a12f2208f8fa56466b7f2f819} ```cpp -Offboard& dronecore::DevicePluginContainer::offboard() +void dronecore::Device::lock_communication() ``` -Getter for [Offboard](classdronecore_1_1_offboard.md) plugin. +### unlock_communication() {#classdronecore_1_1_device_1a801aab463023eb3e64670c86349fa54c} +```cpp +void dronecore::Device::unlock_communication() +``` + + +### operator=() {#classdronecore_1_1_device_1ad03d3cdf0aaa8e4cb21becb6c7806c33} +```cpp +const Device& dronecore::Device::operator=(const Device &)=delete +``` + + +**Parameters** + +* const [Device](classdronecore_1_1_device.md) & - **Returns** - [Offboard](classdronecore_1_1_offboard.md) & - a reference to the offboard plugin instance + const [Device](classdronecore_1_1_device.md) & - -### mission() {#classdronecore_1_1_device_plugin_container_1a8a05778326d0ef4c74146bc42fdcb52d} +### get_own_system_id() {#classdronecore_1_1_device_1ab598504aa60a5acf830161daf8eed908} ```cpp -Mission& dronecore::DevicePluginContainer::mission() +static uint8_t dronecore::Device::get_own_system_id() ``` -Getter for [Mission](classdronecore_1_1_mission.md) plugin. +**Returns** + + uint8_t - + +### get_own_component_id() {#classdronecore_1_1_device_1aa6dc1543b0ae9439a6bacca0dc9c52e6} +```cpp +static uint8_t dronecore::Device::get_own_component_id() +``` + **Returns** - [Mission](classdronecore_1_1_mission.md) & - a reference to the mission plugin instance \ No newline at end of file + uint8_t - \ No newline at end of file diff --git a/en/api_reference/classdronecore_1_1_device_plugin_container.md b/en/api_reference/classdronecore_1_1_device_plugin_container.md deleted file mode 100644 index 7367687..0000000 --- a/en/api_reference/classdronecore_1_1_device_plugin_container.md +++ /dev/null @@ -1,160 +0,0 @@ -# dronecore::DevicePluginContainer Class Reference -`#include: device_plugin_container.h` - ----- - - -The [DevicePluginContainer](classdronecore_1_1_device_plugin_container.md) contains all plugins for a device. - - -The content of the [DevicePluginContainer](classdronecore_1_1_device_plugin_container.md) is auto-generated at compile time. Plugins such as [Action](classdronecore_1_1_action.md) or [Telemetry](classdronecore_1_1_telemetry.md) are included so that they can be accessed using [DroneCore::device()](classdronecore_1_1_drone_core.md#classdronecore_1_1_drone_core_1a5bac6e419e56a1f77a51adef98e94e7c).[action()](classdronecore_1_1_device_plugin_container.md#classdronecore_1_1_device_plugin_container_1aea48bd55b1ace227ebb56690794c2192)... - - -## Public Member Functions - - -Type | Name | Description ----: | --- | --- -| [DevicePluginContainer](#classdronecore_1_1_device_plugin_container_1af4c0f2facc64a99818737971f7f1cc77) (const DevicePluginContainer &)=delete | Copy constructor (object is not copyable). -[Info](classdronecore_1_1_info.md) & | [info](#classdronecore_1_1_device_plugin_container_1a1509e3d7a469cbc3e33471138b1f4dc7) () | -[Logging](classdronecore_1_1_logging.md) & | [logging](#classdronecore_1_1_device_plugin_container_1a0551f966021bdbd9e41700232c33d379) () | -[Telemetry](classdronecore_1_1_telemetry.md) & | [telemetry](#classdronecore_1_1_device_plugin_container_1a9b119348d0f5195c9b0919fbe6196b14) () | -[FollowMe](classdronecore_1_1_follow_me.md) & | [follow_me](#classdronecore_1_1_device_plugin_container_1ae13164c3bb59230c559341b8506c5e03) () | -[Action](classdronecore_1_1_action.md) & | [action](#classdronecore_1_1_device_plugin_container_1aea48bd55b1ace227ebb56690794c2192) () | -[Gimbal](classdronecore_1_1_gimbal.md) & | [gimbal](#classdronecore_1_1_device_plugin_container_1a2fce9f439c565af9a8510c5746c728f0) () | -[Offboard](classdronecore_1_1_offboard.md) & | [offboard](#classdronecore_1_1_device_plugin_container_1a63193bd25273bbda48665e12e012f478) () | -[Mission](classdronecore_1_1_mission.md) & | [mission](#classdronecore_1_1_device_plugin_container_1a8a05778326d0ef4c74146bc42fdcb52d) () | -const [DevicePluginContainer](classdronecore_1_1_device_plugin_container.md) & | [operator=](#classdronecore_1_1_device_plugin_container_1abb90ffceec0873823fb78067d8d6e385) (const DevicePluginContainer &)=delete | Equality operator (object is not copyable). - - -## Constructor & Destructor Documentation - - -### DevicePluginContainer() {#classdronecore_1_1_device_plugin_container_1af4c0f2facc64a99818737971f7f1cc77} -```cpp -dronecore::DevicePluginContainer::DevicePluginContainer(const DevicePluginContainer &)=delete -``` - - -Copy constructor (object is not copyable). - - -**Parameters** - -* const [DevicePluginContainer](classdronecore_1_1_device_plugin_container.md) & - - -## Member Function Documentation - - -### info() {#classdronecore_1_1_device_plugin_container_1a1509e3d7a469cbc3e33471138b1f4dc7} -```cpp -Info& dronecore::DevicePluginContainer::info() -``` - - -Getter for [Info](classdronecore_1_1_info.md) plugin. - -**Returns** - - [Info](classdronecore_1_1_info.md) & - a reference to the info plugin instance - -### logging() {#classdronecore_1_1_device_plugin_container_1a0551f966021bdbd9e41700232c33d379} -```cpp -Logging& dronecore::DevicePluginContainer::logging() -``` - - -Getter for [Logging](classdronecore_1_1_logging.md) plugin. - -**Returns** - - [Logging](classdronecore_1_1_logging.md) & - a reference to the logging plugin instance - -### telemetry() {#classdronecore_1_1_device_plugin_container_1a9b119348d0f5195c9b0919fbe6196b14} -```cpp -Telemetry& dronecore::DevicePluginContainer::telemetry() -``` - - -Getter for [Telemetry](classdronecore_1_1_telemetry.md) plugin. - -**Returns** - - [Telemetry](classdronecore_1_1_telemetry.md) & - a reference to the telemetry plugin instance - -### follow_me() {#classdronecore_1_1_device_plugin_container_1ae13164c3bb59230c559341b8506c5e03} -```cpp -FollowMe& dronecore::DevicePluginContainer::follow_me() -``` - - -Getter for [FollowMe](classdronecore_1_1_follow_me.md) plugin. - -**Returns** - - [FollowMe](classdronecore_1_1_follow_me.md) & - a reference to the follow_me plugin instance - -### action() {#classdronecore_1_1_device_plugin_container_1aea48bd55b1ace227ebb56690794c2192} -```cpp -Action& dronecore::DevicePluginContainer::action() -``` - - -Getter for [Action](classdronecore_1_1_action.md) plugin. - -**Returns** - - [Action](classdronecore_1_1_action.md) & - a reference to the action plugin instance - -### gimbal() {#classdronecore_1_1_device_plugin_container_1a2fce9f439c565af9a8510c5746c728f0} -```cpp -Gimbal& dronecore::DevicePluginContainer::gimbal() -``` - - -Getter for [Gimbal](classdronecore_1_1_gimbal.md) plugin. - -**Returns** - - [Gimbal](classdronecore_1_1_gimbal.md) & - a reference to the gimbal plugin instance - -### offboard() {#classdronecore_1_1_device_plugin_container_1a63193bd25273bbda48665e12e012f478} -```cpp -Offboard& dronecore::DevicePluginContainer::offboard() -``` - - -Getter for [Offboard](classdronecore_1_1_offboard.md) plugin. - -**Returns** - - [Offboard](classdronecore_1_1_offboard.md) & - a reference to the offboard plugin instance - -### mission() {#classdronecore_1_1_device_plugin_container_1a8a05778326d0ef4c74146bc42fdcb52d} -```cpp -Mission& dronecore::DevicePluginContainer::mission() -``` - - -Getter for [Mission](classdronecore_1_1_mission.md) plugin. - -**Returns** - - [Mission](classdronecore_1_1_mission.md) & - a reference to the mission plugin instance - -### operator=() {#classdronecore_1_1_device_plugin_container_1abb90ffceec0873823fb78067d8d6e385} -```cpp -const DevicePluginContainer& dronecore::DevicePluginContainer::operator=(const DevicePluginContainer &)=delete -``` - - -Equality operator (object is not copyable). - - -**Parameters** - -* const [DevicePluginContainer](classdronecore_1_1_device_plugin_container.md) & - - -**Returns** - - const [DevicePluginContainer](classdronecore_1_1_device_plugin_container.md) & - \ No newline at end of file diff --git a/en/api_reference/classdronecore_1_1_follow_me.md b/en/api_reference/classdronecore_1_1_follow_me.md index 0810e0d..d948cd3 100644 --- a/en/api_reference/classdronecore_1_1_follow_me.md +++ b/en/api_reference/classdronecore_1_1_follow_me.md @@ -33,7 +33,7 @@ enum [Result](#classdronecore_1_1_follow_me_1aee7e30070ac95bc63b68c10bd7253b02) Type | Name | Description ---: | --- | --- -| [FollowMe](#classdronecore_1_1_follow_me_1a4fb2ce15bde7d521644dc0835cf217e1) (FollowMeImpl *impl) | Constructor (internal use only). +| [FollowMe](#classdronecore_1_1_follow_me_1a2d3cbcee491efa09392e6333ae77926c) (Device *device) | Constructor. Creates the plugin and associates it with a specified [Device](classdronecore_1_1_device.md). | [~FollowMe](#classdronecore_1_1_follow_me_1a66ffe3c9652bc08a2766f211592316ac) () | Destructor (internal use only). | [FollowMe](#classdronecore_1_1_follow_me_1a54589c314eeba131aca1c4c56d4b15e3) (const FollowMe &)=delete | Copy constructor (object is not copyable). const [Config](structdronecore_1_1_follow_me_1_1_config.md) & | [get_config](#classdronecore_1_1_follow_me_1a054aebafe0839a1028f277285b769fe5) () const | Gets current [FollowMe](classdronecore_1_1_follow_me.md) configuration. @@ -56,18 +56,23 @@ std::string | [result_str](#classdronecore_1_1_follow_me_1a50d848b1c7b00e40343b8 ## Constructor & Destructor Documentation -### FollowMe() {#classdronecore_1_1_follow_me_1a4fb2ce15bde7d521644dc0835cf217e1} +### FollowMe() {#classdronecore_1_1_follow_me_1a2d3cbcee491efa09392e6333ae77926c} ```cpp -dronecore::FollowMe::FollowMe(FollowMeImpl *impl) +dronecore::FollowMe::FollowMe(Device *device) ``` +Constructor. Creates the plugin for a specific [Device](classdronecore_1_1_device.md). -Constructor (internal use only). +The plugin is typically created as shown below: + +```cpp +auto follow_me = std::make_shared(&device); +``` **Parameters** -* FollowMeImpl * **impl** - Private internal implementation. +* [Device](classdronecore_1_1_device.md) * **device** - The specific device associated with this plugin. ### ~FollowMe() {#classdronecore_1_1_follow_me_1a66ffe3c9652bc08a2766f211592316ac} ```cpp diff --git a/en/api_reference/classdronecore_1_1_gimbal.md b/en/api_reference/classdronecore_1_1_gimbal.md index 7f75841..bc48338 100644 --- a/en/api_reference/classdronecore_1_1_gimbal.md +++ b/en/api_reference/classdronecore_1_1_gimbal.md @@ -23,7 +23,7 @@ std::function< void([Result](classdronecore_1_1_gimbal.md#classdronecore_1_1_gim Type | Name | Description ---: | --- | --- -| [Gimbal](#classdronecore_1_1_gimbal_1a14f51547abcaabeb212ec04439e497be) (GimbalImpl *impl) | Constructor (internal use only). +| [Gimbal](#classdronecore_1_1_gimbal_1a2a5ad56ba40eaacc0261f82ed49407e6) (Device *device) | Constructor. Creates the plugin and associates it with a specified [Device](classdronecore_1_1_device.md). | [~Gimbal](#classdronecore_1_1_gimbal_1a4f8b2a6cf5a7347a474f8e47618ad838) () | Destructor (internal use only). | [Gimbal](#classdronecore_1_1_gimbal_1a82637c62da14ae39db96724d4273cad4) (const Gimbal &)=delete | Copy constructor (object is not copyable). [Result](classdronecore_1_1_gimbal.md#classdronecore_1_1_gimbal_1a2404686489b502fbc58e940701ba1e6f) | [set_pitch_and_yaw](#classdronecore_1_1_gimbal_1ac8ac49d29f11b2107da6b043bb57b54e) (float pitch_deg, float yaw_deg) | Set gimbal pitch and yaw angles (synchronous). @@ -41,18 +41,23 @@ const char * | [result_str](#classdronecore_1_1_gimbal_1ad60c5378cc7d160be67432f ## Constructor & Destructor Documentation -### Gimbal() {#classdronecore_1_1_gimbal_1a14f51547abcaabeb212ec04439e497be} +### Gimbal() {#classdronecore_1_1_gimbal_1a2a5ad56ba40eaacc0261f82ed49407e6} ```cpp -dronecore::Gimbal::Gimbal(GimbalImpl *impl) +dronecore::Gimbal::Gimbal(Device *device) ``` +Constructor. Creates the plugin for a specific [Device](classdronecore_1_1_device.md). -Constructor (internal use only). +The plugin is typically created as shown below: + +```cpp +auto gimbal = std::make_shared(&device); +``` **Parameters** -* GimbalImpl * **impl** - Private internal implementation. +* [Device](classdronecore_1_1_device.md) * **device** - The specific device associated with this plugin. ### ~Gimbal() {#classdronecore_1_1_gimbal_1a4f8b2a6cf5a7347a474f8e47618ad838} ```cpp diff --git a/en/api_reference/classdronecore_1_1_info.md b/en/api_reference/classdronecore_1_1_info.md index e118dbf..489db1f 100644 --- a/en/api_reference/classdronecore_1_1_info.md +++ b/en/api_reference/classdronecore_1_1_info.md @@ -19,7 +19,7 @@ struct [Version](structdronecore_1_1_info_1_1_version.md) Type | Name | Description ---: | --- | --- -| [Info](#classdronecore_1_1_info_1ab2433f8a05d19782a7d464dac9f02ade) (InfoImpl *impl) | Constructor (internal use only). +| [Info](#classdronecore_1_1_info_1a10ea70679e1b2d7e43bc9944fbe18aaf) (Device *device) | Constructor. Creates the plugin and associates it with a specified [Device](classdronecore_1_1_device.md). | [~Info](#classdronecore_1_1_info_1a39e608070500b5fca0b4415cdb13f75f) () | Destructor (internal use only). | [Info](#classdronecore_1_1_info_1af0902805d75577d1195363eda21d7bb1) (const Info &)=delete | Copy Constructor (object is not copyable). uint64_t | [uuid](#classdronecore_1_1_info_1a49c7dd5f1a369c8296f0c3a2443bc031) () const | Gets the UUID of the device. @@ -37,18 +37,23 @@ static const unsigned [GIT_HASH_STR_LEN](#classdronecore_1_1_info_1aae671143f80e ## Constructor & Destructor Documentation -### Info() {#classdronecore_1_1_info_1ab2433f8a05d19782a7d464dac9f02ade} +### Info() {#classdronecore_1_1_info_1a10ea70679e1b2d7e43bc9944fbe18aaf} ```cpp -dronecore::Info::Info(InfoImpl *impl) +dronecore::Info::Info(Device *device) ``` +Constructor. Creates the plugin for a specific [Device](classdronecore_1_1_device.md). -Constructor (internal use only). +The plugin is typically created as shown below: + +```cpp +auto info = std::make_shared(&device); +``` **Parameters** -* InfoImpl * **impl** - +* [Device](classdronecore_1_1_device.md) * **device** - The specific device associated with this plugin. ### ~Info() {#classdronecore_1_1_info_1a39e608070500b5fca0b4415cdb13f75f} ```cpp diff --git a/en/api_reference/classdronecore_1_1_logging.md b/en/api_reference/classdronecore_1_1_logging.md index 35f9110..2d2c98c 100644 --- a/en/api_reference/classdronecore_1_1_logging.md +++ b/en/api_reference/classdronecore_1_1_logging.md @@ -23,7 +23,7 @@ std::function< void([Result](classdronecore_1_1_logging.md#classdronecore_1_1_lo Type | Name | Description ---: | --- | --- -| [Logging](#classdronecore_1_1_logging_1ac543ff1d6a0e9980eeb113d39fff39bf) (LoggingImpl *impl) | Constructor (internal use only). +| [Logging](#classdronecore_1_1_logging_1a191a5eaa0d4c23b634585a276a20ba97) (Device *device) | Constructor. Creates the plugin and associates it with a specified [Device](classdronecore_1_1_device.md). | [~Logging](#classdronecore_1_1_logging_1a49e75d77f900ba5ef59a960ae9b8dc55) () | Destructor (internal use only). | [Logging](#classdronecore_1_1_logging_1a62a17eb90e3ec9253f1b40e94d3c1fd7) (const Logging &)=delete | Copy constructor (object is not copyable). [Result](classdronecore_1_1_logging.md#classdronecore_1_1_logging_1ab11e242369717d9510de1ab93bfad086) | [start_logging](#classdronecore_1_1_logging_1a4684d8226742b575fce423c9ce758fc0) () const | Start logging (synchronous). @@ -43,18 +43,23 @@ const char * | [result_str](#classdronecore_1_1_logging_1adc5a7560f1a27996fc05f2 ## Constructor & Destructor Documentation -### Logging() {#classdronecore_1_1_logging_1ac543ff1d6a0e9980eeb113d39fff39bf} +### Logging() {#classdronecore_1_1_logging_1a191a5eaa0d4c23b634585a276a20ba97} ```cpp -dronecore::Logging::Logging(LoggingImpl *impl) +dronecore::Logging::Logging(Device *device) ``` +Constructor. Creates the plugin for a specific [Device](classdronecore_1_1_device.md). -Constructor (internal use only). +The plugin is typically created as shown below: + +```cpp +auto logger = std::make_shared(&device); +``` **Parameters** -* LoggingImpl * **impl** - +* [Device](classdronecore_1_1_device.md) * **device** - The specific device associated with this plugin. ### ~Logging() {#classdronecore_1_1_logging_1a49e75d77f900ba5ef59a960ae9b8dc55} ```cpp diff --git a/en/api_reference/classdronecore_1_1_mission.md b/en/api_reference/classdronecore_1_1_mission.md index 2f5cca9..de36b08 100644 --- a/en/api_reference/classdronecore_1_1_mission.md +++ b/en/api_reference/classdronecore_1_1_mission.md @@ -22,7 +22,7 @@ std::function< void(int current, int total)> [progress_callback_t](#classdroneco Type | Name | Description ---: | --- | --- -| [Mission](#classdronecore_1_1_mission_1ae37622b5640ab3a5042b33c540b31db8) (MissionImpl *impl) | Constructor (internal use only). +| [Mission](#classdronecore_1_1_mission_1a3835376b0fbf186ad572dbfad3bcc4e9) (Device *device) | Constructor. Creates the plugin and associates it with a specified [Device](classdronecore_1_1_device.md). | [~Mission](#classdronecore_1_1_mission_1a395b8c121630aa8a5dd3d48f95290659) () | Destructor (internal use only). | [Mission](#classdronecore_1_1_mission_1a4947f79b7dd71e66bca64e5bbb0b3377) (const Mission &)=delete | Copy constructor (object is not copyable). void | [upload_mission_async](#classdronecore_1_1_mission_1a414b5b6d0c66af695a725e92003872b5) (const std::vector< std::shared_ptr< MissionItem >> &mission_items, result_callback_t callback) | Uploads a vector of mission items to the device (asynchronous). @@ -47,18 +47,23 @@ const char * | [result_str](#classdronecore_1_1_mission_1a0eabb2fe4db664c552d281 ## Constructor & Destructor Documentation -### Mission() {#classdronecore_1_1_mission_1ae37622b5640ab3a5042b33c540b31db8} +### Mission() {#classdronecore_1_1_mission_1a3835376b0fbf186ad572dbfad3bcc4e9} ```cpp -dronecore::Mission::Mission(MissionImpl *impl) +dronecore::Mission::Mission(Device *device) ``` +Constructor. Creates the plugin for a specific [Device](classdronecore_1_1_device.md). -Constructor (internal use only). +The plugin is typically created as shown below: + +```cpp +auto mission = std::make_shared(&device); +``` **Parameters** -* MissionImpl * **impl** - +* [Device](classdronecore_1_1_device.md) * **device** - The specific device associated with this plugin. ### ~Mission() {#classdronecore_1_1_mission_1a395b8c121630aa8a5dd3d48f95290659} ```cpp diff --git a/en/api_reference/classdronecore_1_1_offboard.md b/en/api_reference/classdronecore_1_1_offboard.md index 8a203b4..993782c 100644 --- a/en/api_reference/classdronecore_1_1_offboard.md +++ b/en/api_reference/classdronecore_1_1_offboard.md @@ -36,7 +36,7 @@ std::function< void([Result](classdronecore_1_1_offboard.md#classdronecore_1_1_o Type | Name | Description ---: | --- | --- -| [Offboard](#classdronecore_1_1_offboard_1a8015934ad2d766f8b37b7d5b43f2b089) (OffboardImpl *impl) | Constructor (internal use only). +| [Offboard](#classdronecore_1_1_offboard_1a333ac94793dc29ed95158fb2af286fa1) (Device *device) | Constructor. Creates the plugin and associates it with a specified [Device](classdronecore_1_1_device.md). | [~Offboard](#classdronecore_1_1_offboard_1a7cb4eff36c37fed1c6d973aa41b059b8) () | Destructor (internal use only). | [Offboard](#classdronecore_1_1_offboard_1ac586be55cb24aa0ccd29c97352dd2ee5) (const Offboard &)=delete | Copy constructor (object is not copyable). [Offboard::Result](classdronecore_1_1_offboard.md#classdronecore_1_1_offboard_1a0f6e5e9f73289f27dc99abbb3ab572ed) | [start](#classdronecore_1_1_offboard_1a658454f130f7b19d56f23347a448f1b9) () | Start offboard control (synchronous). @@ -59,18 +59,22 @@ const char * | [result_str](#classdronecore_1_1_offboard_1a8eb7467e48fe354d34bc4 ## Constructor & Destructor Documentation -### Offboard() {#classdronecore_1_1_offboard_1a8015934ad2d766f8b37b7d5b43f2b089} +### Offboard() {#classdronecore_1_1_offboard_1a333ac94793dc29ed95158fb2af286fa1} ```cpp -dronecore::Offboard::Offboard(OffboardImpl *impl) +dronecore::Offboard::Offboard(Device *device) ``` +Constructor. Creates the plugin for a specific [Device](classdronecore_1_1_device.md). -Constructor (internal use only). +The plugin is typically created as shown below: +```cpp +auto offboard = std::make_shared(&device); +``` **Parameters** -* OffboardImpl * **impl** - +* [Device](classdronecore_1_1_device.md) * **device** - The specific device associated with this plugin. ### ~Offboard() {#classdronecore_1_1_offboard_1a7cb4eff36c37fed1c6d973aa41b059b8} ```cpp diff --git a/en/api_reference/classdronecore_1_1_plugin_base.md b/en/api_reference/classdronecore_1_1_plugin_base.md new file mode 100644 index 0000000..a48d496 --- /dev/null +++ b/en/api_reference/classdronecore_1_1_plugin_base.md @@ -0,0 +1,58 @@ +# dronecore::PluginBase Class Reference +`#include: UNKNOWN` + +---- + + +## Public Member Functions + + +Type | Name | Description +---: | --- | --- +| [PluginBase](#classdronecore_1_1_plugin_base_1ae98dd073e3768f140d5fb938c20c861c) () | +| [~PluginBase](#classdronecore_1_1_plugin_base_1a99a11523b84feb2fc1664eed1d4995f3) ()=default | +| [PluginBase](#classdronecore_1_1_plugin_base_1a9a163fe7dc7cc9b8c65a1ce0e86a6750) (const PluginBase &)=delete | +const [PluginBase](classdronecore_1_1_plugin_base.md) & | [operator=](#classdronecore_1_1_plugin_base_1a971a2166cd7528fedb4f18209b2ba699) (const PluginBase &)=delete | + + +## Constructor & Destructor Documentation + + +### PluginBase() {#classdronecore_1_1_plugin_base_1ae98dd073e3768f140d5fb938c20c861c} +```cpp +dronecore::PluginBase::PluginBase() +``` + + +### ~PluginBase() {#classdronecore_1_1_plugin_base_1a99a11523b84feb2fc1664eed1d4995f3} +```cpp +virtual dronecore::PluginBase::~PluginBase()=default +``` + + +### PluginBase() {#classdronecore_1_1_plugin_base_1a9a163fe7dc7cc9b8c65a1ce0e86a6750} +```cpp +dronecore::PluginBase::PluginBase(const PluginBase &)=delete +``` + + +**Parameters** + +* const [PluginBase](classdronecore_1_1_plugin_base.md) & - + +## Member Function Documentation + + +### operator=() {#classdronecore_1_1_plugin_base_1a971a2166cd7528fedb4f18209b2ba699} +```cpp +const PluginBase& dronecore::PluginBase::operator=(const PluginBase &)=delete +``` + + +**Parameters** + +* const [PluginBase](classdronecore_1_1_plugin_base.md) & - + +**Returns** + + const [PluginBase](classdronecore_1_1_plugin_base.md) & - \ No newline at end of file diff --git a/en/api_reference/classdronecore_1_1_telemetry.md b/en/api_reference/classdronecore_1_1_telemetry.md index 154e4dd..94f3b82 100644 --- a/en/api_reference/classdronecore_1_1_telemetry.md +++ b/en/api_reference/classdronecore_1_1_telemetry.md @@ -52,7 +52,7 @@ std::function< void([RCStatus](structdronecore_1_1_telemetry_1_1_r_c_status.md) Type | Name | Description ---: | --- | --- -| [Telemetry](#classdronecore_1_1_telemetry_1ab237a6c16423aebdb52e31d9714c5520) (TelemetryImpl *impl) | Constructor (internal use only). +| [Telemetry](#classdronecore_1_1_telemetry_1ad0cb6dd62c12af390870f8b5cb5bde55) (Device *device) | Constructor. Creates the plugin and associates it with a specified [Device](classdronecore_1_1_device.md). | [~Telemetry](#classdronecore_1_1_telemetry_1ade5f44873d1fd5a5ec63037307920095) () | Destructor (internal use only). | [Telemetry](#classdronecore_1_1_telemetry_1a91a3319d9040bd89d241be3d8b2e9a5e) (const Telemetry &)=delete | Copy constructor (object is not copyable). [Result](classdronecore_1_1_telemetry.md#classdronecore_1_1_telemetry_1a5bfab85edb7c160e156133a9643964bc) | [set_rate_position](#classdronecore_1_1_telemetry_1ae7a6e1313b1508fef7163287aa77a6da) (double rate_hz) | Set rate of position updates (synchronous). @@ -117,18 +117,22 @@ const char * | [result_str](#classdronecore_1_1_telemetry_1a05c6355b7f8743250b2a ## Constructor & Destructor Documentation -### Telemetry() {#classdronecore_1_1_telemetry_1ab237a6c16423aebdb52e31d9714c5520} +### Telemetry() {#classdronecore_1_1_telemetry_1ad0cb6dd62c12af390870f8b5cb5bde55} ```cpp -dronecore::Telemetry::Telemetry(TelemetryImpl *impl) +dronecore::Telemetry::Telemetry(Device *device) ``` +Constructor. Creates the plugin for a specific [Device](classdronecore_1_1_device.md). -Constructor (internal use only). +The plugin is typically created as shown below: +```cpp +auto telemetry = std::make_shared(&device); +``` **Parameters** -* TelemetryImpl * **impl** - +* [Device](classdronecore_1_1_device.md) * **device** - The specific device associated with this plugin. ### ~Telemetry() {#classdronecore_1_1_telemetry_1ade5f44873d1fd5a5ec63037307920095} ```cpp diff --git a/en/contributing/build.md b/en/contributing/build.md index 3fe7bbc..ee6a648 100644 --- a/en/contributing/build.md +++ b/en/contributing/build.md @@ -298,7 +298,7 @@ The C++ source code is annotated using comments using [Doxygen](http://doxygen.n Extract the documentation to markdown files (one per class) on macOS or Linux using the commands: ```bash rm -R install # Required (remove previous install/docs) -make clean # Required (clean build) +make distclean # Required (clean build) ./generate_docs.sh ``` The files are created in **/install/docs/markdown**. diff --git a/en/examples/fly_mission.md b/en/examples/fly_mission.md index 72c5e20..d29af0a 100644 --- a/en/examples/fly_mission.md +++ b/en/examples/fly_mission.md @@ -119,6 +119,8 @@ if(NOT MSVC) add_definitions("-std=c++11 -Wall -Wextra -Werror") else() add_definitions("-std=c++11 -WX -W2") + include_directories(${CMAKE_SOURCE_DIR}/../../install/include) + link_directories(${CMAKE_SOURCE_DIR}/../../install/lib) endif() add_executable(fly_mission @@ -127,6 +129,9 @@ add_executable(fly_mission target_link_libraries(fly_mission dronecore + dronecore_action + dronecore_mission + dronecore_telemetry ) ``` @@ -139,11 +144,14 @@ target_link_libraries(fly_mission // Author: Julian Oes , Shakthi Prashanth // +#include #include -#include +#include +#include #include -#include #include +#include +#include using namespace dronecore; @@ -193,8 +201,11 @@ int main(int /*argc*/, char ** /*argv*/) // If there were multiple, we could specify it with: // dc.device(uint64_t uuid); Device &device = dc.device(); + std::shared_ptr action = std::make_shared(&device); + std::shared_ptr mission = std::make_shared(&device); + std::shared_ptr telemetry = std::make_shared(&device); - while (!device.telemetry().health_all_ok()) { + while (!telemetry->health_all_ok()) { std::cout << "Waiting for device to be ready" << std::endl; std::this_thread::sleep_for(std::chrono::seconds(1)); } @@ -247,11 +258,11 @@ int main(int /*argc*/, char ** /*argv*/) { std::cout << "Uploading mission..." << std::endl; - // We only have the send_mission function asynchronous for now, so we wrap it using + // We only have the upload_mission function asynchronous for now, so we wrap it using // std::future. auto prom = std::make_shared>(); auto future_result = prom->get_future(); - device.mission().send_mission_async( + mission->upload_mission_async( mission_items, [prom](Mission::Result result) { prom->set_value(result); }); @@ -265,7 +276,7 @@ int main(int /*argc*/, char ** /*argv*/) } std::cout << "Arming..." << std::endl; - const Action::Result arm_result = device.action().arm(); + const Action::Result arm_result = action->arm(); if (arm_result != Action::Result::SUCCESS) { std::cout << "Arming failed (" << Action::result_str(arm_result) << "), exiting." << std::endl; return 1; @@ -275,7 +286,7 @@ int main(int /*argc*/, char ** /*argv*/) std::atomic want_to_pause {false}; // Before starting the mission, we want to be sure to subscribe to the mission progress. - device.mission().subscribe_progress( + mission->subscribe_progress( [&want_to_pause](int current, int total) { std::cout << "Mission status update: " << current << " / " << total << std::endl; @@ -290,7 +301,7 @@ int main(int /*argc*/, char ** /*argv*/) std::cout << "Starting mission." << std::endl; auto prom = std::make_shared>(); auto future_result = prom->get_future(); - device.mission().start_mission_async( + mission->start_mission_async( [prom](Mission::Result result) { prom->set_value(result); std::cout << "Started mission." << std::endl; @@ -312,7 +323,7 @@ int main(int /*argc*/, char ** /*argv*/) auto future_result = prom->get_future(); std::cout << "Pausing mission..." << std::endl; - device.mission().pause_mission_async( + mission->pause_mission_async( [prom](Mission::Result result) { prom->set_value(result); }); @@ -334,7 +345,7 @@ int main(int /*argc*/, char ** /*argv*/) auto future_result = prom->get_future(); std::cout << "Resuming mission..." << std::endl; - device.mission().start_mission_async( + mission->start_mission_async( [prom](Mission::Result result) { prom->set_value(result); }); @@ -347,14 +358,14 @@ int main(int /*argc*/, char ** /*argv*/) } } - while (!device.mission().mission_finished()) { + while (!mission->mission_finished()) { std::this_thread::sleep_for(std::chrono::seconds(1)); } { // We are done, and can do RTL to go home. std::cout << "Commanding RTL..." << std::endl; - const Action::Result result = device.action().return_to_launch(); + const Action::Result result = action->return_to_launch(); if (result != Action::Result::SUCCESS) { std::cout << "Failed to command RTL (" << Action::result_str(result) << ")" << std::endl; } else { @@ -365,7 +376,7 @@ int main(int /*argc*/, char ** /*argv*/) // We need to wait a bit, otherwise the armed state might not be correct yet. std::this_thread::sleep_for(std::chrono::seconds(2)); - while (device.telemetry().armed()) { + while (telemetry->armed()) { // Wait until we're done. std::this_thread::sleep_for(std::chrono::seconds(1)); } diff --git a/en/examples/offboard_velocity.md b/en/examples/offboard_velocity.md index 8f45721..f83dbb2 100644 --- a/en/examples/offboard_velocity.md +++ b/en/examples/offboard_velocity.md @@ -70,6 +70,9 @@ if(NOT MSVC) add_definitions("-std=c++11 -Wall -Wextra -Werror") else() add_definitions("-std=c++11 -WX -W2") + add_definitions("-D_USE_MATH_DEFINES") # For M_PI + include_directories(${CMAKE_SOURCE_DIR}/../../install/include) + link_directories(${CMAKE_SOURCE_DIR}/../../install/lib) endif() add_executable(offboard @@ -78,6 +81,9 @@ add_executable(offboard target_link_libraries(offboard dronecore + dronecore_action + dronecore_offboard + dronecore_telemetry ) ``` @@ -93,11 +99,14 @@ target_link_libraries(offboard * @date 2017-10-17 */ -#include -#include -#include #include +#include +#include #include +#include +#include +#include +#include using namespace dronecore; using std::this_thread::sleep_for; @@ -152,16 +161,18 @@ inline void offboard_log(const std::string &offb_mode, const std::string msg) */ bool offb_ctrl_ned(Device &device) { + std::shared_ptr offboard = std::make_shared(&device); + const std::string offb_mode = "NED"; // Send it once before starting offboard, otherwise it will be rejected. - device.offboard().set_velocity_ned({0.0f, 0.0f, 0.0f, 0.0f}); + offboard->set_velocity_ned({0.0f, 0.0f, 0.0f, 0.0f}); - Offboard::Result offboard_result = device.offboard().start(); + Offboard::Result offboard_result = offboard->start(); offboard_error_exit(offboard_result, "Offboard start failed"); offboard_log(offb_mode, "Offboard started"); offboard_log(offb_mode, "Turn to face East"); - device.offboard().set_velocity_ned({0.0f, 0.0f, 0.0f, 90.0f}); + offboard->set_velocity_ned({0.0f, 0.0f, 0.0f, 90.0f}); sleep_for(seconds(1)); // Let yaw settle. { @@ -172,26 +183,26 @@ bool offb_ctrl_ned(Device &device) offboard_log(offb_mode, "Go North and back South"); for (unsigned i = 0; i < steps; ++i) { float vx = 5.0f * sinf(i * step_size); - device.offboard().set_velocity_ned({vx, 0.0f, 0.0f, 90.0f}); + offboard->set_velocity_ned({vx, 0.0f, 0.0f, 90.0f}); sleep_for(milliseconds(10)); } } offboard_log(offb_mode, "Turn to face West"); - device.offboard().set_velocity_ned({0.0f, 0.0f, 0.0f, 270.0f}); + offboard->set_velocity_ned({0.0f, 0.0f, 0.0f, 270.0f}); sleep_for(seconds(2)); offboard_log(offb_mode, "Go up 2 m/s, turn to face South"); - device.offboard().set_velocity_ned({0.0f, 0.0f, -2.0f, 180.0f}); + offboard->set_velocity_ned({0.0f, 0.0f, -2.0f, 180.0f}); sleep_for(seconds(4)); offboard_log(offb_mode, "Go down 1 m/s, turn to face North"); - device.offboard().set_velocity_ned({0.0f, 0.0f, 1.0f, 0.0f}); + offboard->set_velocity_ned({0.0f, 0.0f, 1.0f, 0.0f}); sleep_for(seconds(4)); // Now, stop offboard mode. - offboard_result = device.offboard().stop(); + offboard_result = offboard->stop(); offboard_error_exit(offboard_result, "Offboard stop failed: "); offboard_log(offb_mode, "Offboard stopped"); @@ -205,44 +216,46 @@ bool offb_ctrl_ned(Device &device) */ bool offb_ctrl_body(Device &device) { + std::shared_ptr offboard = std::make_shared(&device); + const std::string offb_mode = "BODY"; // Send it once before starting offboard, otherwise it will be rejected. - device.offboard().set_velocity_body({0.0f, 0.0f, 0.0f, 0.0f}); + offboard->set_velocity_body({0.0f, 0.0f, 0.0f, 0.0f}); - Offboard::Result offboard_result = device.offboard().start(); + Offboard::Result offboard_result = offboard->start(); offboard_error_exit(offboard_result, "Offboard start failed: "); offboard_log(offb_mode, "Offboard started"); offboard_log(offb_mode, "Turn clock-wise and climb"); - device.offboard().set_velocity_body({0.0f, 0.0f, -1.0f, 60.0f}); + offboard->set_velocity_body({0.0f, 0.0f, -1.0f, 60.0f}); sleep_for(seconds(5)); offboard_log(offb_mode, "Turn back anti-clockwise"); - device.offboard().set_velocity_body({0.0f, 0.0f, 0.0f, -60.0f}); + offboard->set_velocity_body({0.0f, 0.0f, 0.0f, -60.0f}); sleep_for(seconds(5)); offboard_log(offb_mode, "Wait for a bit"); - device.offboard().set_velocity_body({0.0f, 0.0f, 0.0f, 0.0f}); + offboard->set_velocity_body({0.0f, 0.0f, 0.0f, 0.0f}); sleep_for(seconds(2)); offboard_log(offb_mode, "Fly a circle"); - device.offboard().set_velocity_body({5.0f, 0.0f, 0.0f, 30.0f}); + offboard->set_velocity_body({5.0f, 0.0f, 0.0f, 30.0f}); sleep_for(seconds(15)); offboard_log(offb_mode, "Wait for a bit"); - device.offboard().set_velocity_body({0.0f, 0.0f, 0.0f, 0.0f}); + offboard->set_velocity_body({0.0f, 0.0f, 0.0f, 0.0f}); sleep_for(seconds(5)); offboard_log(offb_mode, "Fly a circle sideways"); - device.offboard().set_velocity_body({0.0f, -5.0f, 0.0f, 30.0f}); + offboard->set_velocity_body({0.0f, -5.0f, 0.0f, 30.0f}); sleep_for(seconds(15)); offboard_log(offb_mode, "Wait for a bit"); - device.offboard().set_velocity_body({0.0f, 0.0f, 0.0f, 0.0f}); + offboard->set_velocity_body({0.0f, 0.0f, 0.0f, 0.0f}); sleep_for(seconds(8)); - offboard_result = device.offboard().stop(); + offboard_result = offboard->stop(); offboard_error_exit(offboard_result, "Offboard stop failed: "); offboard_log(offb_mode, "Offboard stopped"); @@ -264,18 +277,21 @@ int main(int, char **) // Device got discovered. Device &device = dc.device(); + std::shared_ptr action = std::make_shared(&device); + std::shared_ptr offboard = std::make_shared(&device); + std::shared_ptr telemetry = std::make_shared(&device); - while (!device.telemetry().health_all_ok()) { + while (!telemetry->health_all_ok()) { std::cout << "Waiting for device to be ready" << std::endl; sleep_for(seconds(1)); } std::cout << "Device is ready" << std::endl; - Action::Result arm_result = device.action().arm(); + Action::Result arm_result = action->arm(); action_error_exit(arm_result, "Arming failed"); std::cout << "Armed" << std::endl; - Action::Result takeoff_result = device.action().takeoff(); + Action::Result takeoff_result = action->takeoff(); action_error_exit(takeoff_result, "Takeoff failed"); std::cout << "In Air..." << std::endl; sleep_for(seconds(5)); @@ -292,7 +308,7 @@ int main(int, char **) return EXIT_FAILURE; } - const Action::Result land_result = device.action().land(); + const Action::Result land_result = action->land(); action_error_exit(land_result, "Landing failed"); // We are relying on auto-disarming but let's keep watching the telemetry for a bit longer. diff --git a/en/examples/takeoff_and_land.md b/en/examples/takeoff_and_land.md index a67c760..fdc06fb 100644 --- a/en/examples/takeoff_and_land.md +++ b/en/examples/takeoff_and_land.md @@ -62,6 +62,8 @@ if(NOT MSVC) add_definitions("-std=c++11 -Wall -Wextra -Werror") else() add_definitions("-std=c++11 -WX -W2") + include_directories(${CMAKE_SOURCE_DIR}/../../install/include) + link_directories(${CMAKE_SOURCE_DIR}/../../install/lib) endif() add_executable(takeoff_and_land @@ -70,6 +72,8 @@ add_executable(takeoff_and_land target_link_libraries(takeoff_and_land dronecore + dronecore_telemetry + dronecore_action ) ``` @@ -80,11 +84,13 @@ target_link_libraries(takeoff_and_land // // Author: Julian Oes +#include +#include +#include #include +#include #include #include -#include -#include using namespace dronecore; @@ -126,8 +132,11 @@ int main(int /*argc*/, char ** /*argv*/) // dc.device(uint64_t uuid); Device &device = dc.device(); + auto telemetry = std::make_shared(&device); + auto action = std::make_shared(&device); + // We want to listen to the altitude of the drone at 1 Hz. - const Telemetry::Result set_rate_result = dc.device().telemetry().set_rate_position(1.0); + const Telemetry::Result set_rate_result = telemetry->set_rate_position(1.0); if (set_rate_result != Telemetry::Result::SUCCESS) { std::cout << ERROR_CONSOLE_TEXT << "Setting rate failed:" << Telemetry::result_str( set_rate_result) << NORMAL_CONSOLE_TEXT << std::endl; @@ -136,7 +145,7 @@ int main(int /*argc*/, char ** /*argv*/) // Set up callback to monitor altitude while the vehicle is in flight - device.telemetry().position_async([](Telemetry::Position position) { + telemetry->position_async([](Telemetry::Position position) { std::cout << TELEMETRY_CONSOLE_TEXT // set to blue << "Altitude: " << position.relative_altitude_m << " m" << NORMAL_CONSOLE_TEXT // set to default color again @@ -145,14 +154,14 @@ int main(int /*argc*/, char ** /*argv*/) // Check if vehicle is ready to arm - if (device.telemetry().health_all_ok() != true) { + if (telemetry->health_all_ok() != true) { std::cout << ERROR_CONSOLE_TEXT << "Vehicle not ready to arm" << NORMAL_CONSOLE_TEXT << std::endl; return 1; } // Arm vehicle std::cout << "Arming..." << std::endl; - const Action::Result arm_result = device.action().arm(); + const Action::Result arm_result = action->arm(); if (arm_result != Action::Result::SUCCESS) { std::cout << ERROR_CONSOLE_TEXT << "Arming failed:" << Action::result_str( @@ -162,7 +171,7 @@ int main(int /*argc*/, char ** /*argv*/) // Take off std::cout << "Taking off..." << std::endl; - const Action::Result takeoff_result = device.action().takeoff(); + const Action::Result takeoff_result = action->takeoff(); if (takeoff_result != Action::Result::SUCCESS) { std::cout << ERROR_CONSOLE_TEXT << "Takeoff failed:" << Action::result_str( takeoff_result) << NORMAL_CONSOLE_TEXT << std::endl; @@ -173,7 +182,7 @@ int main(int /*argc*/, char ** /*argv*/) std::this_thread::sleep_for(std::chrono::seconds(10)); std::cout << "Landing..." << std::endl; - const Action::Result land_result = device.action().land(); + const Action::Result land_result = action->land(); if (land_result != Action::Result::SUCCESS) { std::cout << ERROR_CONSOLE_TEXT << "Land failed:" << Action::result_str( land_result) << NORMAL_CONSOLE_TEXT << std::endl; diff --git a/en/examples/transition_vtol_fixed_wing.md b/en/examples/transition_vtol_fixed_wing.md index f209c25..42c3d29 100644 --- a/en/examples/transition_vtol_fixed_wing.md +++ b/en/examples/transition_vtol_fixed_wing.md @@ -82,6 +82,8 @@ if(NOT MSVC) add_definitions("-std=c++11 -Wall -Wextra -Werror") else() add_definitions("-std=c++11 -WX -W2") + include_directories(${CMAKE_SOURCE_DIR}/../../install/include) + link_directories(${CMAKE_SOURCE_DIR}/../../install/lib) endif() add_executable(transition_vtol_fixed_wing @@ -90,17 +92,22 @@ add_executable(transition_vtol_fixed_wing target_link_libraries(transition_vtol_fixed_wing dronecore + dronecore_action + dronecore_telemetry ) ``` [fly_mission.cpp](https://github.com/dronecore/DroneCore/blob/{{ book.github_branch }}/example/transition_vtol_fixed_wing/transition_vtol_fixed_wing.cpp) ```cpp + +#include +#include +#include #include +#include #include #include -#include -#include using std::this_thread::sleep_for; using std::chrono::milliseconds; @@ -143,9 +150,10 @@ int main(int /*argc*/, char ** /*argv*/) // If there were multiple, we could specify it with: // dc.device(uint64_t uuid); Device &device = dc.device(); + std::shared_ptr telemetry = std::make_shared(&device); // We want to listen to the altitude of the drone at 1 Hz. - const Telemetry::Result set_rate_result = dc.device().telemetry().set_rate_position(1.0); + const Telemetry::Result set_rate_result = telemetry->set_rate_position(1.0); if (set_rate_result != Telemetry::Result::SUCCESS) { std::cout << ERROR_CONSOLE_TEXT << "Setting rate failed:" << Telemetry::result_str( set_rate_result) << NORMAL_CONSOLE_TEXT << std::endl; @@ -154,7 +162,7 @@ int main(int /*argc*/, char ** /*argv*/) // Set up callback to monitor altitude while the vehicle is in flight - device.telemetry().position_async([](Telemetry::Position position) { + telemetry->position_async([](Telemetry::Position position) { std::cout << TELEMETRY_CONSOLE_TEXT // set to blue << "Altitude: " << position.relative_altitude_m << " m" << NORMAL_CONSOLE_TEXT // set to default color again @@ -163,14 +171,16 @@ int main(int /*argc*/, char ** /*argv*/) // Check if vehicle is ready to arm - if (device.telemetry().health_all_ok() != true) { + if (telemetry->health_all_ok() != true) { std::cout << ERROR_CONSOLE_TEXT << "Vehicle not ready to arm" << NORMAL_CONSOLE_TEXT << std::endl; return 1; } + std::shared_ptr action = std::make_shared(&device); + // Arm vehicle std::cout << "Arming..." << std::endl; - const Action::Result arm_result = device.action().arm(); + const Action::Result arm_result = action->arm(); if (arm_result != Action::Result::SUCCESS) { std::cout << ERROR_CONSOLE_TEXT << "Arming failed:" << Action::result_str( @@ -180,7 +190,7 @@ int main(int /*argc*/, char ** /*argv*/) // Take off std::cout << "Taking off..." << std::endl; - const Action::Result takeoff_result = device.action().takeoff(); + const Action::Result takeoff_result = action->takeoff(); if (takeoff_result != Action::Result::SUCCESS) { std::cout << ERROR_CONSOLE_TEXT << "Takeoff failed:" << Action::result_str( takeoff_result) << NORMAL_CONSOLE_TEXT << std::endl; @@ -191,7 +201,7 @@ int main(int /*argc*/, char ** /*argv*/) std::this_thread::sleep_for(std::chrono::seconds(10)); std::cout << "Transition to fixedwing..." << std::endl; - const Action::Result fw_result = device.action().transition_to_fixedwing(); + const Action::Result fw_result = action->transition_to_fixedwing(); if (fw_result != Action::Result::SUCCESS) { std::cout << ERROR_CONSOLE_TEXT << "Transition to fixed wing failed: " << Action::result_str( @@ -203,7 +213,7 @@ int main(int /*argc*/, char ** /*argv*/) std::this_thread::sleep_for(std::chrono::seconds(10)); std::cout << "Transition back to multicopter..." << std::endl; - const Action::Result mc_result = device.action().transition_to_multicopter(); + const Action::Result mc_result = action->transition_to_multicopter(); if (mc_result != Action::Result::SUCCESS) { std::cout << ERROR_CONSOLE_TEXT << "Transition to multi copter failed:" << Action::result_str( mc_result) << NORMAL_CONSOLE_TEXT << std::endl; @@ -215,7 +225,7 @@ int main(int /*argc*/, char ** /*argv*/) // Return to launch std::cout << "Return to launch..." << std::endl; - const Action::Result rtl_result = device.action().return_to_launch(); + const Action::Result rtl_result = action->return_to_launch(); if (rtl_result != Action::Result::SUCCESS) { std::cout << ERROR_CONSOLE_TEXT << "Returning to launch failed:" << Action::result_str( rtl_result) << NORMAL_CONSOLE_TEXT << std::endl; @@ -227,7 +237,7 @@ int main(int /*argc*/, char ** /*argv*/) // Land std::cout << "Landing..." << std::endl; - const Action::Result land_result = device.action().land(); + const Action::Result land_result = action->land(); if (land_result != Action::Result::SUCCESS) { std::cout << ERROR_CONSOLE_TEXT << "Land failed:" << Action::result_str( land_result) << NORMAL_CONSOLE_TEXT << std::endl; diff --git a/en/getting_started/faq.md b/en/getting_started/faq.md index beb3b44..ae36daa 100644 --- a/en/getting_started/faq.md +++ b/en/getting_started/faq.md @@ -8,13 +8,13 @@ The aim was to have an API in a language which is cross-platform and has many la Yes, DroneCore is designed to support multiple vehicles. A vehicle is called a device in DroneCore. -A device needs to have a specific mavlink system ID but can consist of multiple components with different component IDs. An example would be a drone with a gimbal and a camera talking mavlink with the same system ID but different component IDs. +A device needs to have a specific MAVLink system ID but can consist of multiple components with different component IDs. An example would be a drone with a gimbal and a camera talking MAVLink with the same system ID but different component IDs. The limit is in theory 255 vehicles for system IDs ranging from 1 to 255. ### What sorts of vehicles does DroneCore support? -The DroneCore API is designed for interacting with *aircraft* (copters, fixed wing and VTOL). +The DroneCore API is designed for interacting with *aircraft*. It has primarily been tested for use with copters, but also has basic support for fixed wing and [VTOL](../guide/vtol.md). The API may "work" with ground based vehicle or other type, but some methods will not make sense, and this use-case is unsupported and untested. @@ -24,7 +24,7 @@ The architecture has stubs for serial, TCP, and UDP connections. However, only U ### Why is libCURL a dependency? -libCURL will be required to download the camera definition file which is referenced in [CAMERA_INFORMATION](http://mavlink.org/messages/common#CAMERA_INFORMATION). It might also come in handy whenever any other REST resources are required. +libCURL will be required to download the camera definition file which is referenced in [CAMERA_INFORMATION](http://mavlink.org/messages/common#CAMERA_INFORMATION). It might also come in handy whenever any other REST resources are required. ### How are plugins added? diff --git a/en/guide/connections.md b/en/guide/connections.md index d095a47..215ebe4 100644 --- a/en/guide/connections.md +++ b/en/guide/connections.md @@ -80,8 +80,4 @@ return the first device detected, or a null `Device` if none have been discovere Device &device = dc.device() ``` -The `Device` can be used to query and control the vehicle. You use the device getters to get an instance of a plugin API (e.g. [Device::action()](../api_reference/classdronecore_1_1_device.md#classdronecore_1_1_device_plugin_container_1aea48bd55b1ace227ebb56690794c2192) to get an [Action](../api_reference/classdronecore_1_1_action.md) object) and then call the object's methods. For example, to arm the device you would do: -```cpp -const Action::Result arm_result = device.action().arm(); -``` -The plugin APIs are covered in other guide topics. \ No newline at end of file +The `Device` is used by DroneCore plugin classes to query and control the vehicle. For more information see [Using Plugins](../guide/using_plugins.md) (and the other guide topics). \ No newline at end of file diff --git a/en/guide/device_version.md b/en/guide/device_version.md index d9cc319..0055e3e 100644 --- a/en/guide/device_version.md +++ b/en/guide/device_version.md @@ -6,24 +6,35 @@ The [Info](../api_reference/classdronecore_1_1_info.md) class is used to get dev hardware may return garbage values (for example, the simulator provides garbage values for the vendor firmware semantic version). -The code below shows how to query the UUID, version, and product, information and print it to the console: +## Preconditions +The following code assumes that you already have included DroneCore (`#include `) and that there is a [connection to a device](../guide/connections.md) obtained as shown below: ```cpp -// Get Device to query (the code assumes we have already found at least one vehicle and we -// want to query the first detected vehicle). -Device &device = dc.device(); +Device &device = dc.device(); +``` + +The code also assumes that you have defined `info`, a shared pointer to an instance of the `Info` class associated with the device (see [Using Plugins](../guide/using_plugins.md)): +```cpp +#include +auto info = std::make_shared(&device); +``` +## Query Device Information + +The code below shows how to query the UUID, version, and product, information and print it to the console: + +```cpp // Get device UUID -std::cout << " UUID: " << device.info().uuid() << std::endl; +std::cout << " UUID: " << info->uuid() << std::endl; // Wait until version/firmware information has been populated from the vehicle -while (!device.info().is_complete()) { +while (!info->is_complete()) { std::cout << "Waiting for Version information to populate from device." << std::endl; std::this_thread::sleep_for(std::chrono::seconds(1)); } // Get the device Version struct -const Info::Version &deviceVersion = device.info().get_version(); +const Info::Version &deviceVersion = info->get_version(); // Print out the vehicle version information. std::cout << " flight_sw_major: " << deviceVersion.flight_sw_major<< std::endl @@ -39,7 +50,7 @@ std::cout << " flight_sw_major: " << deviceVersion.flight_sw_major<< std::endl << " os_sw_git_hash: " << deviceVersion.os_sw_git_hash<< std::endl; // Get the device Product struct -const Info::Product &deviceProduct = device.info().get_product(); +const Info::Product &deviceProduct = info->get_product(); // Print out the vehicle product information. std::cout << " vendor_id: " << deviceProduct.vendor_id<< std::endl diff --git a/en/guide/follow_me.md b/en/guide/follow_me.md index fa95d1f..1dab838 100644 --- a/en/guide/follow_me.md +++ b/en/guide/follow_me.md @@ -8,6 +8,42 @@ The API is used to supply the position(s) for the [target](../api_reference/stru - Windows: [Windows.Devices.Geolocation](https://docs.microsoft.com/en-us/uwp/api/Windows.Devices.Geolocation) +## Create the Plugin + +> **Tip** `FollowMe` objects are created in the same way as other DroneCore plugins. General instructions are provided in the topic: [Using Plugins](../guide/using_plugins.md). + +The main steps are: + +1. Link the plugin library into your application. Do this by adding `dronecore_follow_me` to the `target_link_libraries` section of the app's *cmake* build definition file + + ```cmake + target_link_libraries(your_application_name + dronecore + ... + dronecore_follow_me + ... + ) + ``` +1. [Create a connection](../guide/connections.md) to a `device`. For example (basic code without error checking): + ``` + #include + DroneCore dc; + DroneCore::ConnectionResult conn_result = dc.add_udp_connection(); + // Wait for the device to connect via heartbeat + while (!dc.is_connected()) { + sleep_for(seconds(1)); + } + // Device got discovered. + Device &device = dc.device(); + ``` +1. Create a shared pointer to an instance of `FollowMe` instantiated with the `device`: + ``` + #include + auto follow_me = std::make_shared(&device); + ``` + +The `follow_me` pointer can then used to access the plugin API (as shown in the following sections). + ## Set the Follow Configuration By default the vehicle will follow directly behind the target at a height and distance of 8 metres. @@ -23,7 +59,7 @@ config.responsiveness = 0.2f; // Higher responsiveness config.follow_direction = FollowMe::Config::FollowDirection::FRONT; //Follow from front-centre // Apply configuration -FollowMe::Result config_result = device.follow_me().set_config(config); +FollowMe::Result config_result = follow_me->set_config(config); if (config_result != FollowMe::Result::SUCCESS) { // handle config-setting failure (in this case print error) std::cout << "Setting configuration failed:" << FollowMe::result_str(config_result) << std::endl; @@ -32,7 +68,7 @@ if (config_result != FollowMe::Result::SUCCESS) { The [get_config()](../api_reference/classdronecore_1_1_follow_me.md#classdronecore_1_1_follow_me_1a054aebafe0839a1028f277285b769fe5) method is provided to get the current configuration: ```cpp -auto curr_config = device.follow_me().get_config(); +auto curr_config = follow_me->get_config(); ``` ## Following a Target @@ -45,7 +81,7 @@ Use [set_target_location()](../api_reference/classdronecore_1_1_follow_me.md#cla ```cpp // Start following -FollowMe::Result follow_me_result = device.follow_me().start(); +FollowMe::Result follow_me_result = follow_me->start(); if (follow_me_result != FollowMe::Result::SUCCESS) { // handle start failure (in this case print error) std::cout << "Failed to start following:" << FollowMe::result_str(follow_me_result) << std::endl; @@ -54,11 +90,11 @@ if (follow_me_result != FollowMe::Result::SUCCESS) { // Get target position from underlying platform and supply to vehicle. // For this example we just show one point being set (instead of a stream). -follow_me.set_target_location({ 47.39776569, 8.54553292, 0.f, 0.f, 0.f, 0.f }); +follow_me->set_target_location({ 47.39776569, 8.54553292, 0.f, 0.f, 0.f, 0.f }); // Stop following -follow_me_result = device.follow_me().stop(); +follow_me_result = follow_me->stop(); if (follow_me_result != FollowMe::Result::SUCCESS) { // handle stop failure (in this case print error) std::cout << "Failed to stop following:" << FollowMe::result_str(follow_me_result) << std::endl; diff --git a/en/guide/general_usage.md b/en/guide/general_usage.md index b7318f3..67cce49 100644 --- a/en/guide/general_usage.md +++ b/en/guide/general_usage.md @@ -2,14 +2,15 @@ This topic provides general/overview information about how DroneCore is used, designed and some limitations. - ## Object Management -[DroneCore](../api_reference/classdronecore_1_1_drone_core.md) is the main library class. API consumers use it to discover and manage vehicles ([Device](../api_reference/classdronecore_1_1_device.md) objects), which in turn provide access to all other drone information and control objects. +[DroneCore](../api_reference/classdronecore_1_1_drone_core.md) is the main library class. Applications must create a `DroneCore` object and destroy it during application shut down. The object is usually created as an automatic variable that is cleaned up when it goes out of scope (you can also dynamically create/destroy the object using `new`/`delete`). + +API consumers use [DroneCore](../api_reference/classdronecore_1_1_drone_core.md) to discover and connect to [Device](../api_reference/classdronecore_1_1_device.md) objects (vehicles/cameras etc.). -DroneCore applications must create a `DroneCore` object and destroy it during application shut down. The object can be created as an automatic variable that is cleaned up when it goes out of scope, or you can dynamically create/destroy the object using `new`/`delete`. +Access to drone information and control objects are provided [by plugins](../guide/using_plugins.md) (e.g. Telemetry, Action, Mission etc.). Plugin objects are instantiated with a *specific* `Device` object (a plugin instance must be created for every device that needs it). -All other objects are returned/owned by the API and will automatically be destroyed along with `DroneCore`. +Plugin objects are created as shared pointers that will be destroyed when all associated handles are out of scope. All objects are automatically cleaned up when the parent `DroneCore` object is destroyed. ## Error Handling @@ -30,9 +31,10 @@ DroneCore applications that are running in environments where this is possible c ## API Limitations/Behaviour + ### Supported Vehicles -DroneCore has been designed to manage *aircraft* (copter, fixed wing, VTOL) that use the PX4 autopilot. +DroneCore has been designed to manage *aircraft* that use the PX4 autopilot. It has primarily been tested for use with copters, but also has basic support for fixed wing and [VTOL](../guide/vtol.md). The APIs include methods that do not make sense for other vehicle types - including "takeoff" and "land". While ground vehicles may work, they are not supported and are untested. @@ -48,7 +50,7 @@ The rate at which update messages are sent by the vehicle can be specified using ### Actions/Offboard -Actions methods (and any other "vehicle instructions") return when the vehicle has confirmed that the message was received and will be acted on (or not). The methods do not wait for the commanded action to complete. +`Action` methods (and any other "vehicle instructions") return when the vehicle has confirmed that the message was received and will be acted on (or not). The methods do not wait for the commanded action to complete. So, for example, the [Action::land()](../api_reference/classdronecore_1_1_action.md#classdronecore_1_1_action_1ad1a50dd7bff99d3099916576efbf8cf6) method returns as soon as the vehicle confirms it will land, but will actually land at some later point. @@ -61,9 +63,10 @@ The `Mission` and `MissionItem` APIs provide a the most useful *subset* of MAVLi Not every mission command behaviour supported by the protocol and PX4 will be supported by DroneCore. For example, at time of writing the API does not allow you to specify commands that jump back to previous mission items. +The API allows you to download/import missions. Note however that this will fail if the mission contains a command that is not supported by the API. + ### Connection Status A device is considered to be disconnected (timed-out) if its heartbeat message is not detected within 3 seconds. - diff --git a/en/guide/missions.md b/en/guide/missions.md index 60bf2cc..c333628 100644 --- a/en/guide/missions.md +++ b/en/guide/missions.md @@ -22,12 +22,42 @@ The supported set is: > DroneCore provides some omitted functionality through the [Action](../guide/taking_off_landing.md) API. -## Preconditions +## Create the Plugin + +> **Tip** `Mission` objects are created in the same way as other DroneCore plugins. General instructions are provided in the topic: [Using Plugins](../guide/using_plugins.md). + +The main steps are: + +1. Link the plugin library into your application. Do this by adding `dronecore_mission` to the `target_link_libraries` section of the app's *cmake* build definition file + + ```cmake + target_link_libraries(your_application_name + dronecore + ... + dronecore_mission + ... + ) + ``` +1. [Create a connection](../guide/connections.md) to a `device`. For example (basic code without error checking): + ``` + #include + DroneCore dc; + DroneCore::ConnectionResult conn_result = dc.add_udp_connection(); + // Wait for the device to connect via heartbeat + while (!dc.is_connected()) { + sleep_for(seconds(1)); + } + // Device got discovered. + Device &device = dc.device(); + ``` +1. Create a shared pointer to an instance of `Mission` instantiated with the `device`: + ``` + #include + auto mission = std::make_shared(&device); + ``` + +The `mission` pointer can then used to access the plugin API (as shown in the following sections). -The following code assumes that you already have included DroneCore (`#include `) and the standard library (`#include `) and that there is a [connection to a device](../guide/connections.md) obtained as shown below: -```cpp -Device &device = dc.device(); -``` ## Defining a Mission @@ -119,7 +149,7 @@ The example below shows how this is done, using promises to wait on the result. { auto prom = std::make_shared>(); auto future_result = prom->get_future(); - device.mission().upload_mission_async( + mission->upload_mission_async( mission_items, [prom](Mission::Result result) { prom->set_value(result); }); @@ -143,7 +173,7 @@ The code fragment below shows how this is done, using promises to wait on the re { auto prom = std::make_shared>(); auto future_result = prom->get_future(); - device.mission().start_mission_async( + mission->start_mission_async( [prom](Mission::Result result) { prom->set_value(result); }); @@ -165,7 +195,7 @@ To pause a mission use [Mission::pause_mission_async()](../api_reference/classdr auto future_result = prom->get_future(); std::cout << "Pausing mission..." << std::endl; - device.mission().pause_mission_async( + mission->pause_mission_async( [prom](Mission::Result result) { prom->set_value(result); }); @@ -186,7 +216,7 @@ Asynchronously monitor progress using [Mission::subscribe_progress()](../api_ref The code fragment just takes a lambda function that reports the current status. ```cpp -device.mission().subscribe_progress( [](int current, int total) { +mission->subscribe_progress( [](int current, int total) { std::cout << "Mission status update: " << current << " / " << total << std::endl; }); ``` @@ -231,7 +261,7 @@ The code fragment below shows how to download a mission: auto prom = std::make_shared>(); auto future = prom->get_future(); - device.mission().download_mission_async( + mission->download_mission_async( [prom](Mission::Result result, std::vector> mission_items_downloaded) { PromiseResult promise_result {}; promise_result.mission_result = result; diff --git a/en/guide/offboard.md b/en/guide/offboard.md index 5fcae15..aa564a9 100644 --- a/en/guide/offboard.md +++ b/en/guide/offboard.md @@ -8,13 +8,41 @@ for controlling the vehicle using velocity and yaw setpoints. It is useful for t Client code must specify a setpoint before starting *Offboard mode*. DroneCore automatically resends setpoints at 20Hz (PX4 requires that setpoints are minimally resent at 2Hz). If more precise control is required, clients can call the setpoint methods at whatever rate is required. -## Preconditions - -The following code assumes that you already have included DroneCore (`#include `) -and that there is a [connection](../guide/connections.md) to a `device` obtained as shown below: -``` -Device &device = dc.device(); -``` +## Create the Plugin + +> **Tip** `Offboard` objects are created in the same way as other DroneCore plugins. General instructions are provided in the topic: [Using Plugins](../guide/using_plugins.md). + +The main steps are: + +1. Link the plugin library into your application. Do this by adding `dronecore_offboard` to the `target_link_libraries` section of the app's *cmake* build definition file + + ```cmake + target_link_libraries(your_application_name + dronecore + ... + dronecore_offboard + ... + ) + ``` +1. [Create a connection](../guide/connections.md) to a `device`. For example (basic code without error checking): + ``` + #include + DroneCore dc; + DroneCore::ConnectionResult conn_result = dc.add_udp_connection(); + // Wait for the device to connect via heartbeat + while (!dc.is_connected()) { + sleep_for(seconds(1)); + } + // Device got discovered. + Device &device = dc.device(); + ``` +1. Create a shared pointer to an instance of `Offboard` instantiated with the `device`: + ``` + #include + auto offboard = std::make_shared(&device); + ``` + +The `offboard` pointer can then used to access the plugin API (as shown in the following sections). ## Starting/Stopping Offboard Mode @@ -24,10 +52,10 @@ After you have created a setpoint call [start()](../api_reference/classdronecore ```cpp // Create a setpoint before starting offboard mode (in this case a null setpoint) -device.offboard().set_velocity_body({0.0f, 0.0f, 0.0f, 0.0f}); +offboard->set_velocity_body({0.0f, 0.0f, 0.0f, 0.0f}); // Start offboard mode. -Offboard::Result offboard_result = device.offboard().start(); +Offboard::Result offboard_result = offboard->start(); if (result != Offboard::Result::SUCCESS) { std::cerr << "Offboard::start() failed: " << Offboard::result_str(offboard_result) << std::endl; @@ -46,7 +74,7 @@ The synchronous API is used as shown below: ```cpp //Stop offboard mode -offboard_result = device.offboard().stop(); +offboard_result = offboard->stop(); if (result != Offboard::Result::SUCCESS) { std::cerr << "Offboard::stop() failed: " << Offboard::result_str(offboard_result) << std::endl; @@ -76,11 +104,11 @@ Examples: * Head North at 3 m/s: ```cpp - device.offboard().set_velocity_ned({3.0f, 0.0f, 0.0f, 0.0f}); + offboard->set_velocity_ned({3.0f, 0.0f, 0.0f, 0.0f}); ``` * Head North-West with 5 m/s on each velocity component (notice that a negative value is required on the `east_m_s` value to move West): ```cpp - device.offboard().set_velocity_ned({5.0f, -5.0f, 0.0f, 0.0f}); + offboard->set_velocity_ned({5.0f, -5.0f, 0.0f, 0.0f}); ``` @@ -92,11 +120,11 @@ Examples: * Go *up* at 2 m/s (note, negative value to go up!): ```cpp - device.offboard().set_velocity_ned({0.0f, 0.0f, -2.0f, 0.0f}); + offboard->set_velocity_ned({0.0f, 0.0f, -2.0f, 0.0f}); ``` * Go down at 3 m/s: ```cpp - device.offboard().set_velocity_body({0.0f, 0.0f, 3.0f, 0.0f}); + offboard->set_velocity_body({0.0f, 0.0f, 3.0f, 0.0f}); ``` @@ -111,11 +139,11 @@ the final (fourth) value is the yaw direction. Examples: * Turn to face West: ```cpp - device.offboard().set_velocity_ned({0.0f, 0.0f, 0.0f, 270.0f}); + offboard->set_velocity_ned({0.0f, 0.0f, 0.0f, 270.0f}); ``` * Turn to face North: ```cpp - device.offboard().set_velocity_ned({0.0f, 0.0f, 0.0f, 0.0f}); + offboard->set_velocity_ned({0.0f, 0.0f, 0.0f, 0.0f}); ``` It is not possible to control the rate or direction that the vehicle will use to turn towards the setpoint direction (it will turn in whatever direction reaches the setpoint fastest). @@ -132,11 +160,11 @@ Examples: * Turn clock-wise at 60 degrees per second: ```cpp - device.offboard().set_velocity_body({0.0f, 0.0f, 0.0f, 60.0f}); + offboard->set_velocity_body({0.0f, 0.0f, 0.0f, 60.0f}); ``` * Turn anti clock-wise at 5 degrees per second: ```cpp - device.offboard().set_velocity_body({0.0f, 0.0f, 0.0f, -5.0f}); + offboard->set_velocity_body({0.0f, 0.0f, 0.0f, -5.0f}); ``` ### Fly Forwards @@ -144,7 +172,7 @@ Examples: Use `set_velocity_body()` to set the velocity components relative to the body frame. To fly forwards, simply set the first parameter (`Offboard::VelocityBodyYawspeed::forward_m_s`) when the vehicle is not rotating. ```cpp -device.offboard().set_velocity_body({5.0f, 0.0f, 0.0f, 0.0f}); +offboard->set_velocity_body({5.0f, 0.0f, 0.0f, 0.0f}); ``` ### Fly a Circle @@ -152,13 +180,13 @@ device.offboard().set_velocity_body({5.0f, 0.0f, 0.0f, 0.0f}); To fly a circle, use `set_velocity_body()` with both forward and rotational components. This will force the vehicle to travel in a curved path. ```cpp -device.offboard().set_velocity_body({5.0f, 0.0f, 0.0f, 30.0f}); +offboard->set_velocity_body({5.0f, 0.0f, 0.0f, 30.0f}); ``` You can force the vehicle to fly sideways by using the (`Offboard::VelocityBodyYawspeed::right_m_s` value), and in the other direction by using a negative rotation value: ```cpp // Fly a circle sideways -device.offboard().set_velocity_body({0.0f, -5.0f, 0.0f, -30.0f}); +offboard->set_velocity_body({0.0f, -5.0f, 0.0f, -30.0f}); ``` diff --git a/en/guide/taking_off_landing.md b/en/guide/taking_off_landing.md index cc592f5..6fbcf6a 100644 --- a/en/guide/taking_off_landing.md +++ b/en/guide/taking_off_landing.md @@ -1,4 +1,4 @@ -# Take-off and Landing (and Other Actions) +# Actions (Take-off, Landing, Arming, etc) DroneCore provides the [Action](../api_reference/classdronecore_1_1_action.md) class for commanding the vehicle to arm, takeoff, land, return home and land, disarm, kill and transition between VTOL modes. @@ -6,8 +6,46 @@ Most of the methods have both synchronous and asynchronous versions. The methods > **Note** The implication is that you may need to monitor for completion of actions! - -> **Note** All the code fragments below refer to the object `device`, which is a [connected device/vehicle](../guide/connections.md). + + +## Create the Plugin + +> **Tip** `Action` objects are created in the same way as other DroneCore plugins. General instructions are provided in the topic: [Using Plugins](../guide/using_plugins.md). + +The main steps are: + +1. Link the plugin library into your application. Do this by adding `dronecore_action` to the `target_link_libraries` section of the app's *cmake* build definition file + + ```cmake + target_link_libraries(your_application_name + dronecore + ... + dronecore_action + ... + ) + ``` +1. [Create a connection](../guide/connections.md) to a `device`. For example (basic code without error checking): + ``` + #include + DroneCore dc; + DroneCore::ConnectionResult conn_result = dc.add_udp_connection(); + // Wait for the device to connect via heartbeat + while (!dc.is_connected()) { + sleep_for(seconds(1)); + } + // Device got discovered. + Device &device = dc.device(); + ``` +1. Create a shared pointer to an instance of `Action` instantiated with the `device`: + ``` + #include + auto action = std::make_shared(&device); + ``` + +The `action` pointer can then used to access the plugin API (as shown in the following sections). + + +> **Note** Some of the sections below additionally assume you have created a `Telemetry` instance that can be accessed using `telemetry`. ## Taking Off @@ -27,7 +65,7 @@ The code fragment below shows very simple code to synchronously poll for health ```cpp // Wait until health is OK and vehicle is ready to arm -while (device.telemetry().health_all_ok() != true) { +while (telemetry->health_all_ok() != true) { std::cout << "Vehicle not ready to arm ..." << std::endl; std::this_thread::sleep_for(std::chrono::seconds(1)); } @@ -37,7 +75,7 @@ The code fragment below performs the same task, but additionally exits the app i ```cpp // Exit if calibration is required -Telemetry::Health check_health = device.telemetry().health(); +Telemetry::Health check_health = telemetry->health(); bool calibration_required = false; if (!check_health.gyrometer_calibration_ok) { std::cout << ERROR_CONSOLE_TEXT << "Gyro requires calibration." << NORMAL_CONSOLE_TEXT << std::endl; @@ -61,9 +99,9 @@ if (calibration_required) { // Check if ready to arm (reporting status) -while (device.telemetry().health_all_ok() != true) { +while (telemetry->health_all_ok() != true) { std::cout << ERROR_CONSOLE_TEXT << "Vehicle not ready to arm. Waiting on:" << NORMAL_CONSOLE_TEXT << std::endl; - Telemetry::Health current_health = device.telemetry().health(); + Telemetry::Health current_health = telemetry->health(); if (!current_health.global_position_ok) { std::cout << ERROR_CONSOLE_TEXT << " - GPS fix." << NORMAL_CONSOLE_TEXT << std::endl; } @@ -86,7 +124,7 @@ Once the vehicle is ready, use the following synchronous code to arm: ```cpp // Arm vehicle std::cout << "Arming..." << std::endl; -const Action::Result arm_result = device.action().arm(); +const Action::Result arm_result = action->arm(); if (arm_result != Action::Result::SUCCESS) { std::cout << "Arming failed:" @@ -103,7 +141,7 @@ if (arm_result != Action::Result::SUCCESS) { The default/current takeoff altitude can be queried using [get_takeoff_altitude_m()](../api_reference/classdronecore_1_1_action.md#classdronecore_1_1_action_1a1888deebcc48d906c3c19473596e6fec). This target can be changed at any point before takeoff using [set_takeoff_altitude()](../api_reference/classdronecore_1_1_action.md#classdronecore_1_1_action_1adc6f7f6668d3681afa4d820095154c9d). The code fragment below shows how to set the takeoff altitude to 3 metres: ```cpp -device.action().set_takeoff_altitude(3.0); +action->set_takeoff_altitude(3.0); ``` ### Takeoff Action @@ -112,7 +150,7 @@ Once the vehicle is armed it can be commanded to take off. The code below uses t ```cpp // Command Take off std::cout << "Taking off..." << std::endl; -const Action::Result takeoff_result = device.action().takeoff(); +const Action::Result takeoff_result = action->takeoff(); if (takeoff_result != Action::Result::SUCCESS) { std::cout << "Takeoff failed:" << Action::result_str( takeoff_result) << std::endl; @@ -127,10 +165,10 @@ If the command succeeds the vehicle will takeoff, and hover at the takeoff altit The code below checks for takeoff completion by polling the current altitude until the target altitude is reached: ```cpp -float target_alt=device.action().get_takeoff_altitude_m(); +float target_alt=action->get_takeoff_altitude_m(); float current_position=0; while (current_positionposition().relative_altitude_m; std::this_thread::sleep_for(std::chrono::seconds(1)); } // Reached target altitude - continue with next instruction. @@ -146,7 +184,7 @@ The best way to land the vehicle at the current location is to use the [land()]( The code below shows how to use the land action. ```cpp -const Action::Result land_result = device.action().land(); +const Action::Result land_result = action->land(); if (land_result != Action::Result::SUCCESS) { //Land failed, so exit (in reality might try a return to land or kill.) return 1; @@ -157,7 +195,7 @@ The vehicle should land and then automatically disarm. If you want to monitor th app based on the armed state, as shown below. ```cpp -while (device.telemetry().armed()) { +while (telemetry->armed()) { std::this_thread::sleep_for(std::chrono::seconds(1)); } std::cout << "Disarmed, exiting." << std::endl; @@ -171,7 +209,7 @@ std::cout << "Disarmed, exiting." << std::endl; The code below shows how to use the synchronous method: ```cpp -const Action::Result rtl_result = device.action().return_to_launch(); +const Action::Result rtl_result = telemetry->return_to_launch(); if (rtl_result != Action::Result::SUCCESS) { //RTL failed, so exit (in reality might send kill command.) return 1; @@ -214,7 +252,7 @@ The code fragment below shows how to call the synchronous action to transition t and to print the result of the call (the other synchronous method is used in the same way). ```cpp -const Action::Result fw_result = device.action().transition_to_fixedwing(); +const Action::Result fw_result = action->transition_to_fixedwing(); if (fw_result != Action::Result::SUCCESS) { std::cout << "Transition to fixed wing failed: " diff --git a/en/guide/telemetry.md b/en/guide/telemetry.md index c5c1cab..5715415 100644 --- a/en/guide/telemetry.md +++ b/en/guide/telemetry.md @@ -2,9 +2,8 @@ The [Telemetry](../api_reference/classdronecore_1_1_telemetry.md) class provides simple methods for getting vehicle telemetry, including state and flight mode information. -All the methods have both synchronous and asynchronous versions, and users can set the rate at which the vehicle provides updates for each type of information. +All the methods have both synchronous and asynchronous versions, and users can set the rate at which the vehicle provides updates for each type of information. All the methods of a particular type (synchronous, asynchronous, and set_rate methods) are used in the same way. -All the methods of a particular type (synchronous, asynchronous, and set_rate methods) are used in the same way. ## API Overview @@ -25,6 +24,43 @@ In addition there are a number of methods that return vehicle "state": * Whether the vehicle is flying/in air. +## Create the Plugin + +> **Tip** `Telemetry` objects are created in the same way as other DroneCore plugins. General instructions are provided in the topic: [Using Plugins](../guide/using_plugins.md). + +The main steps are: + +1. Link the plugin library into your application. Do this by adding `dronecore_telemetry` to the `target_link_libraries` section of the app's *cmake* build definition file + + ```cmake + target_link_libraries(your_application_name + dronecore + ... + dronecore_telemetry + ... + ) + ``` +1. [Create a connection](../guide/connections.md) to a `device`. For example (basic code without error checking): + ``` + #include + DroneCore dc; + DroneCore::ConnectionResult conn_result = dc.add_udp_connection(); + // Wait for the device to connect via heartbeat + while (!dc.is_connected()) { + sleep_for(seconds(1)); + } + // Device got discovered. + Device &device = dc.device(); + ``` +1. Create a shared pointer to an instance of `Telemetry` instantiated with the `device`: + ``` + #include + auto telemetry = std::make_shared(&device); + ``` + +The `telemetry` pointer can then used to access the plugin API (as shown in the following sections). + + ## Setting the Update Rate {#update-rate} The telemetry update rate determines the frequency at which callbacks will be invoked with new information, and also the probable "freshness" of data obtained when using synchronous telemetry APIs. The default update rate depends on the autopilot and may also be limited by the characteristics of the communications channel. You can set the rate for *each* type of telemetry, and both synchronous or asynchronous rate-setting methods are provided. @@ -36,7 +72,7 @@ The rate-setting methods are all used in the same way, so we just show one examp To set the position update rate synchronously (in this case using [set_rate_position()](../api_reference/classdronecore_1_1_telemetry.md#classdronecore_1_1_telemetry_1ae7a6e1313b1508fef7163287aa77a6da)): ```cpp // Set position update rate to 1 Hz. -const Telemetry::Result set_rate_result = dc.device().telemetry().set_rate_position(1.0); +const Telemetry::Result set_rate_result = telemetry->set_rate_position(1.0); if (set_rate_result != Telemetry::Result::SUCCESS) { // handle rate-setting failure (in this case print error) std::cout << "Setting rate failed:" << Telemetry::result_str(set_rate_result) << std::endl; @@ -51,7 +87,7 @@ To set the position update rate asynchronously with [set_rate_position_async()]( auto prom = std::make_shared>(); auto future_result = prom->get_future(); // Set position update rate to 1 Hz. - device.telemetry().set_rate_position_async(1.0, [prom](Telemetry::Result result) { + telemetry->set_rate_position_async(1.0, [prom](Telemetry::Result result) { prom->set_value(result); //fulfill promise }); @@ -76,7 +112,7 @@ void dronecore::Telemetry::position_async(position_callback_t callback) The code fragment below shows this method being use with a lambda function for the callback, which simply prints out the current position and altitude). ```cpp -device.telemetry().position_async([](Telemetry::Position position) { +telemetry->position_async([](Telemetry::Position position) { std::cout << "Altitude: " << position.relative_altitude_m << " m" << std::endl << "Latitude: " << position.latitude_deg << std::endl << "Longitude: " << position.longitude_deg << std::endl; @@ -93,7 +129,7 @@ The example below shows how to use [flight_mode_async()](../api_reference/classd ```cpp // Set up callback to monitor flight mode 'changes' Telemetry::FlightMode oldFlightMode=Telemetry::FlightMode::UNKNOWN; -device.telemetry().flight_mode_async([&oldFlightMode](Telemetry::FlightMode flightMode) { +telemetry->flight_mode_async([&oldFlightMode](Telemetry::FlightMode flightMode) { if (oldFlightMode != flightMode) { //Flight mode changed. Print! std::cout << "FlightMode: " << Telemetry::flight_mode_str(flightMode) << std::endl; @@ -115,7 +151,7 @@ Often the easiest approach is to use synchronous methods and poll for the result ```cpp // Check if vehicle is ready to arm -while (!device.telemetry().health_all_ok()) { +while (!telemetry->health_all_ok()) { std::cout << "Vehicle not ready to arm" << std::endl; std::this_thread::sleep_for(std::chrono::seconds(1)); } @@ -129,7 +165,7 @@ Similarly, you can use the asynchronous method and block std::cout << "Waiting for device to be ready" << std::endl; auto prom = std::make_shared>(); auto future_result = prom->get_future(); - device.telemetry().health_all_ok_async( + telemetry->health_all_ok_async( [prom](bool result) { //fulfill promise if health is OK if (result) {// health OK diff --git a/en/guide/toolchain.md b/en/guide/toolchain.md index c6922a2..282e63e 100644 --- a/en/guide/toolchain.md +++ b/en/guide/toolchain.md @@ -22,7 +22,7 @@ The sections below show how you can set up the file for when DroneCore is [insta ### DroneCore Installed System-wide {#dronecore_installed_system} -A "template" **CMakeLists.txt** is shown below. Most of file is boilerplate - the only things you need to change are *your_project_name*, *your_executable_name* and *your_source_file*. +A "template" **CMakeLists.txt** is shown below. Most of file is boilerplate - the main things you need to change are *your_project_name*, *your_executable_name* and *your_source_file*. You should also make sure that any plugins used by your app are listed in the `target_link_libraries` section. ```cmake cmake_minimum_required(VERSION 2.8.12) @@ -35,6 +35,8 @@ if(NOT MSVC) add_definitions("-std=c++11 -Wall -Wextra -Werror") else() add_definitions("-std=c++11 -WX -W2") + include_directories(${CMAKE_SOURCE_DIR}/../../install/include) + link_directories(${CMAKE_SOURCE_DIR}/../../install/lib) endif() # Specify your app's executable name, and list of source files used to create it. @@ -46,7 +48,9 @@ add_executable(your_executable_name # Specify your app's executable name and a list of linked libraries target_link_libraries(your_executable_name dronecore #All apps link against dronecore library - # ... any other linked libraries + dronecore_action # If action plugin used by app ... + dronecore_telemetry If telemetry plugin used by app ... + # ... Any other linked libraries ) ``` diff --git a/en/guide/using_plugins.md b/en/guide/using_plugins.md new file mode 100644 index 0000000..5e0957c --- /dev/null +++ b/en/guide/using_plugins.md @@ -0,0 +1,34 @@ +# Using Plugins (Managing Devices) + +Access to drone information, telemetry and control objects are provided by a number of different *plugins*. For example, the [Action](../api_reference/classdronecore_1_1_action.md) plugin is used to arm, takeoff and land the vehicle, while the [Telemetry](../guide/telemetry.md) plugin can be used to query the device GPS status, flight mode, etc. A separate plugin instance must be created for each device that needs it. + +> **Note** All plugins are declared/used in the same way. This topic uses the `Action` plugin for the purposes of the demonstration. + +To use a plugin first link the plugin library into the application. Do this by adding it to the `target_link_libraries` section of the app's *cmake* build definition file: + +```cmake +target_link_libraries(takeoff_and_land + dronecore + ... + dronecore_action + ... +) +``` + +> **Note** Plugins are named using the convention **dronecore\__plugin\_name_.so**. For more information see [Building C++ Apps](../guide/toolchain.md) + + +In the application source code: +1. `#include` the header file for the plugin. + ```cpp + #include + ``` +1. [Create a connection](../guide/connections.md) to a `Device` object (below named: `device`). +1. Make a shared pointer to the plugin object, specifying the `Device` it is to be used with: + ```cpp + auto action = std::make_shared(&device); + ``` +1. The pointer can then be used to invoke actions on the specified device. For example, to takeoff you would call the API as shown: + ```cpp + action->takeoff(); + ```