From eefc3ab6cbb8a5901632f46d99e13c8d90b2415d Mon Sep 17 00:00:00 2001 From: growupboron Date: Fri, 9 Oct 2020 00:19:18 +0530 Subject: rewrote quickstart, build-process Revamped and updated documentation to install and build AGL images. (removed whitespaces, added contribution guide, corrected rcar-gen3 section 7, added aglsetup.h flags to hardware support, some minor changes) Bug-AGL: [SPEC-3633] Signed-off-by: Shankho Boron Ghosh Change-Id: Iedb6c7dc1661f4bc58b5f25ea5d188778c7ff908 Reviewed-on: https://gerrit.automotivelinux.org/gerrit/c/AGL/documentation/+/25407 Reviewed-by: Jan-Simon Moeller Tested-by: Jan-Simon Moeller --- .../4.1_API_Reference/0_api-introduction.md | 54 -- .../4.2_Application_Framework/.md | 595 ------------- .../4.2_Application_Framework/0_introduction.md | 273 ------ .../4.2_Application_Framework/1_afm-daemons.md | 656 -------------- .../4.2_Application_Framework/2_widgets.md | 16 - .../4.2_Application_Framework/3_widgets.md | 162 ---- .../4.2_Application_Framework/4_permissions.md | 138 --- .../4.2_Application_Framework/5_quick-tutorial.md | 276 ------ .../pictures/AppFW-APP_install_sequences.svg | 408 --------- .../pictures/Security_model_history.svg | 149 ---- .../pictures/afm-daemons.svg | 237 ----- .../pictures/make-units.svg | 436 --------- .../0_Overview/0_Overview.md | 100 --- .../1_Binder_daemon_vocabulary.md | 111 --- .../2_How_to_write_a_binding.md | 451 ---------- .../3_Binder_references/1_Types_and_globals.md | 252 ------ .../3_Binder_references/2_Macros_for-logging.md | 62 -- .../3_Functions_of_class_afb_api.md | 970 --------------------- .../4_Functions_of_class_afb_req.md | 851 ------------------ .../5_Functions_of_class_afb_event.md | 120 --- .../6_Functions_of_class_afb_daemon.md | 155 ---- .../7_Functions_of_class afb_service.md | 171 ---- .../4_Binder_events_guide/Binder_events_guide.md | 298 ------- .../Binder_Application_writing_guide.md | 328 ------- .../6_Annexes/1_Migration_to_bindings_v3.md | 209 ----- .../2_WebSocket_protocol_x-afb-ws-json1.md | 315 ------- .../3_Installing_the_binder_on_a_desktop.md | 51 -- .../6_Annexes/4_Options_of_afb-daemon.md | 363 -------- .../6_Annexes/5_Debuggin_binder_and_bindings.md | 45 - .../6_Annexes/6_LEGACY_Migration_from_v1_to_v2.md | 664 -------------- .../6_Annexes/7_LEGACY Binding V2 references.md | 765 ---------------- .../7_Document_revisions/Document_revisions.md | 23 - .../pictures/basis.svg | 356 -------- .../pictures/interconnection.svg | 854 ------------------ .../pictures/signaling-basis.svg | 145 --- .../0_Installation/Installation.md | 33 - .../1_Write_the_tests/Write_the_tests.md | 261 ------ .../2_The_test_widget/The_test_widget.md | 74 -- .../3_Launch_the_tests/Launch_the_tests.md | 336 ------- .../4_Tests_Examples/Tests_Examples.md | 119 --- .../1_BindingTestFunctions/BindingTestFunctions.md | 121 --- .../2_BindingAssertFunctions.md | 79 -- .../3_TestFrameworkFunctions.md | 70 -- .../0_General_Assertions.md | 41 - .../1_Value_Assertions.md | 67 -- .../2_Scientific_Assertions.md | 57 -- .../3_String_Assertions.md | 47 - .../4_Error_Assertions.md | 39 - .../5_Type_Assertions.md | 47 - .../6_Table_Assertions.md | 28 - .../1_Message_Signaling/architecture.md | 476 ---------- .../1_Message_Signaling/images/can-generator.svg | 244 ------ .../1_Message_Signaling/images/cloud-arch.svg | 837 ------------------ .../images/distributed-arch.png | Bin 73736 -> 0 bytes .../images/signal-service-arch.svg | 296 ------- .../2_AGL_Service_CAN_Low_Level/1_Architecture.md | 34 - .../2_AGL_Service_CAN_Low_Level/2_Installation.md | 196 ----- .../3_Installation-J1939.md | 90 -- .../4_Installation-ISOTP.md | 59 -- .../2_AGL_Service_CAN_Low_Level/5_Usage.md | 433 --------- .../images/CAN_bindings_communication.png | Bin 43504 -> 0 bytes .../images/CAN_level_mapping.png | Bin 56087 -> 0 bytes .../images/OpenXC_to_AGL.png | Bin 84031 -> 0 bytes .../1_Architecture_presentation.md | 32 - .../3_High_Level_VIWI_Service/2_Install_Usage.md | 208 ----- .../images/high-level-arch.png | Bin 30810 -> 0 bytes .../1_Architecture.md | 73 -- .../2_Configuration.md | 109 --- .../4_AGL_Service_Signal_Composer/3_Plugins.md | 32 - .../4_SignalComposerAPI.md | 71 -- .../pictures/Global_Signaling_Architecture.png | Bin 195325 -> 0 bytes ..._AGL-Message-Signaling-Developer-Guidelines.pdf | Bin 777644 -> 0 bytes .../AGL-Message-Signaling-Developer-Guidelines.md | 1 - .../4.5.6_AGL-AppFW-CAN-Signaling-Benchmark.pdf | Bin 305379 -> 0 bytes .../AGL-AppFW-CAN-Signaling-Benchmark.md | 1 - .../candevstudio/1_Usage.md | 26 - .../candevstudio/2_can_device_socketcan_backend.md | 44 - .../candevstudio/3_Add_CAN_Device.md | 41 - .../candevstudio/4_Configure_CanRawSender_Node.md | 28 - .../candevstudio/5_Using_CanRawView.md | 18 - .../candevstudio/pictures/CANdevStudio.png | Bin 52285 -> 0 bytes .../candevstudio/pictures/canrawsender.png | Bin 43850 -> 0 bytes .../candevstudio/pictures/canrawviewer.png | Bin 125506 -> 0 bytes .../4.5_Message_Signaling/8_Resources/index.md | 95 -- .../4.6_Audio_Framework/4.6.1_Overview.md | 167 ---- .../4.6.2_Session_Manager_Configuration.md | 450 ---------- .../4.6_Audio_Framework/4.6.3_Bluetooth.md | 122 --- .../4.7.1_Home_Screen_Developer_Guide.md | 532 ----------- .../4.7_HMI_Framework/4.7.2_WindowManager-Guide.md | 938 -------------------- .../4.7.3_Sound_Manager_Developer_Guide.md | 388 --------- .../4.7.4_Sound_Manager_Developer_Guide_2.md | 133 --- .../4.7.5_Sound_Manager_Developer_Guide_3.md | 343 -------- .../4.7_HMI_Framework/parts/am-component.png | Bin 90431 -> 0 bytes .../4.7_HMI_Framework/parts/change_layout_seq.png | Bin 34698 -> 0 bytes .../4.7_HMI_Framework/parts/deactivate_window.png | Bin 44618 -> 0 bytes .../4.7_HMI_Framework/parts/example_split.png | Bin 223071 -> 0 bytes .../parts/hmi_framework_designed_seq_toyota.png | Bin 54198 -> 0 bytes .../parts/initialize-set-event-handler.svg | 32 - .../4.7_HMI_Framework/parts/on_screen_message.svg | 36 - .../4.7_HMI_Framework/parts/request_role.png | Bin 26503 -> 0 bytes .../4.7_HMI_Framework/parts/seq_changevolume.svg | 117 --- .../parts/seq_connectsoundroute.svg | 145 --- .../parts/seq_disconnectsoundroute.svg | 110 --- .../4.7_HMI_Framework/parts/seq_registration.svg | 235 ----- .../parts/seq_releasesoundmode.svg | 119 --- .../parts/seq_requestsoundmode.svg | 165 ---- .../4.7_HMI_Framework/parts/seq_setmutestate.svg | 115 --- .../parts/seq_startsoundstreaming.svg | 129 --- .../4.7_HMI_Framework/parts/seq_startup.svg | 68 -- .../parts/seq_stopsoundstreaming.svg | 129 --- .../4.7_HMI_Framework/parts/showInformation.svg | 30 - .../4.7_HMI_Framework/parts/showNotification.svg | 34 - .../4.7_HMI_Framework/parts/showOnScreen.svg | 72 -- .../4.7_HMI_Framework/parts/showWindow.svg | 34 - .../4.7_HMI_Framework/parts/software-stack.png | Bin 197208 -> 0 bytes .../parts/state_change_example.png | Bin 182038 -> 0 bytes .../4.7_HMI_Framework/parts/tap_shortcut.svg | 26 - .../4.7_HMI_Framework/parts/typical-usecase.png | Bin 256665 -> 0 bytes .../4.7_HMI_Framework/parts/wm_area.png | Bin 12427 -> 0 bytes .../4.7_HMI_Framework/parts/wm_change_layout.png | Bin 86852 -> 0 bytes .../4.7_HMI_Framework/parts/wm_layer_stack.png | Bin 33482 -> 0 bytes .../4.7_HMI_Framework/parts/wm_software_stack.png | Bin 28935 -> 0 bytes .../4.8_HomeScreen_(old)/homescreen_api.md | 195 ----- .../pictures/api_getAllSurfacesOfProcess.png | Bin 10485 -> 0 bytes .../pictures/api_getSurfaceStatus_1.png | Bin 10168 -> 0 bytes .../pictures/api_getSurfaceStatus_2.png | Bin 9794 -> 0 bytes .../pictures/api_getSurfaceStatus_3.png | Bin 19030 -> 0 bytes .../pictures/api_hardKeyPressed.png | Bin 9241 -> 0 bytes .../pictures/api_renderSurfaceToArea.png | Bin 9060 -> 0 bytes .../pictures/api_renderSurfaceToAreaAllowed.png | Bin 14910 -> 0 bytes .../pictures/api_requestSurfaceIdToFullScreen.png | Bin 10056 -> 0 bytes .../pictures/api_surfaceVisibilityChanged.png | Bin 8882 -> 0 bytes 132 files changed, 20786 deletions(-) delete mode 100644 docs/4_APIs_and_Services/4.1_API_Reference/0_api-introduction.md delete mode 100644 docs/4_APIs_and_Services/4.2_Application_Framework/.md delete mode 100644 docs/4_APIs_and_Services/4.2_Application_Framework/0_introduction.md delete mode 100644 docs/4_APIs_and_Services/4.2_Application_Framework/1_afm-daemons.md delete mode 100644 docs/4_APIs_and_Services/4.2_Application_Framework/2_widgets.md delete mode 100644 docs/4_APIs_and_Services/4.2_Application_Framework/3_widgets.md delete mode 100644 docs/4_APIs_and_Services/4.2_Application_Framework/4_permissions.md delete mode 100644 docs/4_APIs_and_Services/4.2_Application_Framework/5_quick-tutorial.md delete mode 100644 docs/4_APIs_and_Services/4.2_Application_Framework/pictures/AppFW-APP_install_sequences.svg delete mode 100644 docs/4_APIs_and_Services/4.2_Application_Framework/pictures/Security_model_history.svg delete mode 100644 docs/4_APIs_and_Services/4.2_Application_Framework/pictures/afm-daemons.svg delete mode 100644 docs/4_APIs_and_Services/4.2_Application_Framework/pictures/make-units.svg delete mode 100644 docs/4_APIs_and_Services/4.3_Application_Framework_Binder/0_Overview/0_Overview.md delete mode 100644 docs/4_APIs_and_Services/4.3_Application_Framework_Binder/1_Binder_daemon_vocabulary/1_Binder_daemon_vocabulary.md delete mode 100644 docs/4_APIs_and_Services/4.3_Application_Framework_Binder/2_How_to_write_a_binding/2_How_to_write_a_binding.md delete mode 100644 docs/4_APIs_and_Services/4.3_Application_Framework_Binder/3_Binder_references/1_Types_and_globals.md delete mode 100644 docs/4_APIs_and_Services/4.3_Application_Framework_Binder/3_Binder_references/2_Macros_for-logging.md delete mode 100644 docs/4_APIs_and_Services/4.3_Application_Framework_Binder/3_Binder_references/3_Functions_of_class_afb_api.md delete mode 100644 docs/4_APIs_and_Services/4.3_Application_Framework_Binder/3_Binder_references/4_Functions_of_class_afb_req.md delete mode 100644 docs/4_APIs_and_Services/4.3_Application_Framework_Binder/3_Binder_references/5_Functions_of_class_afb_event.md delete mode 100644 docs/4_APIs_and_Services/4.3_Application_Framework_Binder/3_Binder_references/6_Functions_of_class_afb_daemon.md delete mode 100644 docs/4_APIs_and_Services/4.3_Application_Framework_Binder/3_Binder_references/7_Functions_of_class afb_service.md delete mode 100644 docs/4_APIs_and_Services/4.3_Application_Framework_Binder/4_Binder_events_guide/Binder_events_guide.md delete mode 100644 docs/4_APIs_and_Services/4.3_Application_Framework_Binder/5_Binder_Application_writing_guide/Binder_Application_writing_guide.md delete mode 100644 docs/4_APIs_and_Services/4.3_Application_Framework_Binder/6_Annexes/1_Migration_to_bindings_v3.md delete mode 100644 docs/4_APIs_and_Services/4.3_Application_Framework_Binder/6_Annexes/2_WebSocket_protocol_x-afb-ws-json1.md delete mode 100644 docs/4_APIs_and_Services/4.3_Application_Framework_Binder/6_Annexes/3_Installing_the_binder_on_a_desktop.md delete mode 100644 docs/4_APIs_and_Services/4.3_Application_Framework_Binder/6_Annexes/4_Options_of_afb-daemon.md delete mode 100644 docs/4_APIs_and_Services/4.3_Application_Framework_Binder/6_Annexes/5_Debuggin_binder_and_bindings.md delete mode 100644 docs/4_APIs_and_Services/4.3_Application_Framework_Binder/6_Annexes/6_LEGACY_Migration_from_v1_to_v2.md delete mode 100644 docs/4_APIs_and_Services/4.3_Application_Framework_Binder/6_Annexes/7_LEGACY Binding V2 references.md delete mode 100644 docs/4_APIs_and_Services/4.3_Application_Framework_Binder/7_Document_revisions/Document_revisions.md delete mode 100644 docs/4_APIs_and_Services/4.3_Application_Framework_Binder/pictures/basis.svg delete mode 100644 docs/4_APIs_and_Services/4.3_Application_Framework_Binder/pictures/interconnection.svg delete mode 100644 docs/4_APIs_and_Services/4.3_Application_Framework_Binder/pictures/signaling-basis.svg delete mode 100644 docs/4_APIs_and_Services/4.4_AGL_Test_Framework/0_Installation/Installation.md delete mode 100644 docs/4_APIs_and_Services/4.4_AGL_Test_Framework/1_Write_the_tests/Write_the_tests.md delete mode 100644 docs/4_APIs_and_Services/4.4_AGL_Test_Framework/2_The_test_widget/The_test_widget.md delete mode 100644 docs/4_APIs_and_Services/4.4_AGL_Test_Framework/3_Launch_the_tests/Launch_the_tests.md delete mode 100644 docs/4_APIs_and_Services/4.4_AGL_Test_Framework/4_Tests_Examples/Tests_Examples.md delete mode 100644 docs/4_APIs_and_Services/4.4_AGL_Test_Framework/5_Reference/1_BindingTestFunctions/BindingTestFunctions.md delete mode 100644 docs/4_APIs_and_Services/4.4_AGL_Test_Framework/5_Reference/2_BindingAssertFunctions/2_BindingAssertFunctions.md delete mode 100644 docs/4_APIs_and_Services/4.4_AGL_Test_Framework/5_Reference/3_TestFrameworkFunctions/3_TestFrameworkFunctions.md delete mode 100644 docs/4_APIs_and_Services/4.4_AGL_Test_Framework/5_Reference/4_LuaUnit_Assertion_Functions/0_General_Assertions.md delete mode 100644 docs/4_APIs_and_Services/4.4_AGL_Test_Framework/5_Reference/4_LuaUnit_Assertion_Functions/1_Value_Assertions.md delete mode 100644 docs/4_APIs_and_Services/4.4_AGL_Test_Framework/5_Reference/4_LuaUnit_Assertion_Functions/2_Scientific_Assertions.md delete mode 100644 docs/4_APIs_and_Services/4.4_AGL_Test_Framework/5_Reference/4_LuaUnit_Assertion_Functions/3_String_Assertions.md delete mode 100644 docs/4_APIs_and_Services/4.4_AGL_Test_Framework/5_Reference/4_LuaUnit_Assertion_Functions/4_Error_Assertions.md delete mode 100644 docs/4_APIs_and_Services/4.4_AGL_Test_Framework/5_Reference/4_LuaUnit_Assertion_Functions/5_Type_Assertions.md delete mode 100644 docs/4_APIs_and_Services/4.4_AGL_Test_Framework/5_Reference/4_LuaUnit_Assertion_Functions/6_Table_Assertions.md delete mode 100644 docs/4_APIs_and_Services/4.5_Message_Signaling/1_Message_Signaling/architecture.md delete mode 100644 docs/4_APIs_and_Services/4.5_Message_Signaling/1_Message_Signaling/images/can-generator.svg delete mode 100644 docs/4_APIs_and_Services/4.5_Message_Signaling/1_Message_Signaling/images/cloud-arch.svg delete mode 100644 docs/4_APIs_and_Services/4.5_Message_Signaling/1_Message_Signaling/images/distributed-arch.png delete mode 100644 docs/4_APIs_and_Services/4.5_Message_Signaling/1_Message_Signaling/images/signal-service-arch.svg delete mode 100644 docs/4_APIs_and_Services/4.5_Message_Signaling/2_AGL_Service_CAN_Low_Level/1_Architecture.md delete mode 100644 docs/4_APIs_and_Services/4.5_Message_Signaling/2_AGL_Service_CAN_Low_Level/2_Installation.md delete mode 100644 docs/4_APIs_and_Services/4.5_Message_Signaling/2_AGL_Service_CAN_Low_Level/3_Installation-J1939.md delete mode 100644 docs/4_APIs_and_Services/4.5_Message_Signaling/2_AGL_Service_CAN_Low_Level/4_Installation-ISOTP.md delete mode 100644 docs/4_APIs_and_Services/4.5_Message_Signaling/2_AGL_Service_CAN_Low_Level/5_Usage.md delete mode 100644 docs/4_APIs_and_Services/4.5_Message_Signaling/2_AGL_Service_CAN_Low_Level/images/CAN_bindings_communication.png delete mode 100644 docs/4_APIs_and_Services/4.5_Message_Signaling/2_AGL_Service_CAN_Low_Level/images/CAN_level_mapping.png delete mode 100644 docs/4_APIs_and_Services/4.5_Message_Signaling/2_AGL_Service_CAN_Low_Level/images/OpenXC_to_AGL.png delete mode 100644 docs/4_APIs_and_Services/4.5_Message_Signaling/3_High_Level_VIWI_Service/1_Architecture_presentation.md delete mode 100644 docs/4_APIs_and_Services/4.5_Message_Signaling/3_High_Level_VIWI_Service/2_Install_Usage.md delete mode 100644 docs/4_APIs_and_Services/4.5_Message_Signaling/3_High_Level_VIWI_Service/images/high-level-arch.png delete mode 100644 docs/4_APIs_and_Services/4.5_Message_Signaling/4_AGL_Service_Signal_Composer/1_Architecture.md delete mode 100644 docs/4_APIs_and_Services/4.5_Message_Signaling/4_AGL_Service_Signal_Composer/2_Configuration.md delete mode 100644 docs/4_APIs_and_Services/4.5_Message_Signaling/4_AGL_Service_Signal_Composer/3_Plugins.md delete mode 100644 docs/4_APIs_and_Services/4.5_Message_Signaling/4_AGL_Service_Signal_Composer/4_SignalComposerAPI.md delete mode 100644 docs/4_APIs_and_Services/4.5_Message_Signaling/4_AGL_Service_Signal_Composer/pictures/Global_Signaling_Architecture.png delete mode 100644 docs/4_APIs_and_Services/4.5_Message_Signaling/5_AGL-Message-Signaling-Developer-Guidelines/4.5.5_AGL-Message-Signaling-Developer-Guidelines.pdf delete mode 100644 docs/4_APIs_and_Services/4.5_Message_Signaling/5_AGL-Message-Signaling-Developer-Guidelines/AGL-Message-Signaling-Developer-Guidelines.md delete mode 100644 docs/4_APIs_and_Services/4.5_Message_Signaling/6_AGL-AppFW-CAN-Signaling-Benchmark/4.5.6_AGL-AppFW-CAN-Signaling-Benchmark.pdf delete mode 100644 docs/4_APIs_and_Services/4.5_Message_Signaling/6_AGL-AppFW-CAN-Signaling-Benchmark/AGL-AppFW-CAN-Signaling-Benchmark.md delete mode 100644 docs/4_APIs_and_Services/4.5_Message_Signaling/7_CanDevStudio_Quickstart/candevstudio/1_Usage.md delete mode 100644 docs/4_APIs_and_Services/4.5_Message_Signaling/7_CanDevStudio_Quickstart/candevstudio/2_can_device_socketcan_backend.md delete mode 100644 docs/4_APIs_and_Services/4.5_Message_Signaling/7_CanDevStudio_Quickstart/candevstudio/3_Add_CAN_Device.md delete mode 100644 docs/4_APIs_and_Services/4.5_Message_Signaling/7_CanDevStudio_Quickstart/candevstudio/4_Configure_CanRawSender_Node.md delete mode 100644 docs/4_APIs_and_Services/4.5_Message_Signaling/7_CanDevStudio_Quickstart/candevstudio/5_Using_CanRawView.md delete mode 100644 docs/4_APIs_and_Services/4.5_Message_Signaling/7_CanDevStudio_Quickstart/candevstudio/pictures/CANdevStudio.png delete mode 100644 docs/4_APIs_and_Services/4.5_Message_Signaling/7_CanDevStudio_Quickstart/candevstudio/pictures/canrawsender.png delete mode 100644 docs/4_APIs_and_Services/4.5_Message_Signaling/7_CanDevStudio_Quickstart/candevstudio/pictures/canrawviewer.png delete mode 100644 docs/4_APIs_and_Services/4.5_Message_Signaling/8_Resources/index.md delete mode 100644 docs/4_APIs_and_Services/4.6_Audio_Framework/4.6.1_Overview.md delete mode 100644 docs/4_APIs_and_Services/4.6_Audio_Framework/4.6.2_Session_Manager_Configuration.md delete mode 100644 docs/4_APIs_and_Services/4.6_Audio_Framework/4.6.3_Bluetooth.md delete mode 100644 docs/4_APIs_and_Services/4.7_HMI_Framework/4.7.1_Home_Screen_Developer_Guide.md delete mode 100644 docs/4_APIs_and_Services/4.7_HMI_Framework/4.7.2_WindowManager-Guide.md delete mode 100644 docs/4_APIs_and_Services/4.7_HMI_Framework/4.7.3_Sound_Manager_Developer_Guide.md delete mode 100644 docs/4_APIs_and_Services/4.7_HMI_Framework/4.7.4_Sound_Manager_Developer_Guide_2.md delete mode 100644 docs/4_APIs_and_Services/4.7_HMI_Framework/4.7.5_Sound_Manager_Developer_Guide_3.md delete mode 100644 docs/4_APIs_and_Services/4.7_HMI_Framework/parts/am-component.png delete mode 100644 docs/4_APIs_and_Services/4.7_HMI_Framework/parts/change_layout_seq.png delete mode 100644 docs/4_APIs_and_Services/4.7_HMI_Framework/parts/deactivate_window.png delete mode 100644 docs/4_APIs_and_Services/4.7_HMI_Framework/parts/example_split.png delete mode 100644 docs/4_APIs_and_Services/4.7_HMI_Framework/parts/hmi_framework_designed_seq_toyota.png delete mode 100644 docs/4_APIs_and_Services/4.7_HMI_Framework/parts/initialize-set-event-handler.svg delete mode 100644 docs/4_APIs_and_Services/4.7_HMI_Framework/parts/on_screen_message.svg delete mode 100644 docs/4_APIs_and_Services/4.7_HMI_Framework/parts/request_role.png delete mode 100644 docs/4_APIs_and_Services/4.7_HMI_Framework/parts/seq_changevolume.svg delete mode 100644 docs/4_APIs_and_Services/4.7_HMI_Framework/parts/seq_connectsoundroute.svg delete mode 100644 docs/4_APIs_and_Services/4.7_HMI_Framework/parts/seq_disconnectsoundroute.svg delete mode 100644 docs/4_APIs_and_Services/4.7_HMI_Framework/parts/seq_registration.svg delete mode 100644 docs/4_APIs_and_Services/4.7_HMI_Framework/parts/seq_releasesoundmode.svg delete mode 100644 docs/4_APIs_and_Services/4.7_HMI_Framework/parts/seq_requestsoundmode.svg delete mode 100644 docs/4_APIs_and_Services/4.7_HMI_Framework/parts/seq_setmutestate.svg delete mode 100644 docs/4_APIs_and_Services/4.7_HMI_Framework/parts/seq_startsoundstreaming.svg delete mode 100644 docs/4_APIs_and_Services/4.7_HMI_Framework/parts/seq_startup.svg delete mode 100644 docs/4_APIs_and_Services/4.7_HMI_Framework/parts/seq_stopsoundstreaming.svg delete mode 100644 docs/4_APIs_and_Services/4.7_HMI_Framework/parts/showInformation.svg delete mode 100644 docs/4_APIs_and_Services/4.7_HMI_Framework/parts/showNotification.svg delete mode 100644 docs/4_APIs_and_Services/4.7_HMI_Framework/parts/showOnScreen.svg delete mode 100644 docs/4_APIs_and_Services/4.7_HMI_Framework/parts/showWindow.svg delete mode 100644 docs/4_APIs_and_Services/4.7_HMI_Framework/parts/software-stack.png delete mode 100644 docs/4_APIs_and_Services/4.7_HMI_Framework/parts/state_change_example.png delete mode 100644 docs/4_APIs_and_Services/4.7_HMI_Framework/parts/tap_shortcut.svg delete mode 100644 docs/4_APIs_and_Services/4.7_HMI_Framework/parts/typical-usecase.png delete mode 100644 docs/4_APIs_and_Services/4.7_HMI_Framework/parts/wm_area.png delete mode 100644 docs/4_APIs_and_Services/4.7_HMI_Framework/parts/wm_change_layout.png delete mode 100644 docs/4_APIs_and_Services/4.7_HMI_Framework/parts/wm_layer_stack.png delete mode 100644 docs/4_APIs_and_Services/4.7_HMI_Framework/parts/wm_software_stack.png delete mode 100644 docs/4_APIs_and_Services/4.8_HomeScreen_(old)/homescreen_api.md delete mode 100644 docs/4_APIs_and_Services/4.8_HomeScreen_(old)/pictures/api_getAllSurfacesOfProcess.png delete mode 100644 docs/4_APIs_and_Services/4.8_HomeScreen_(old)/pictures/api_getSurfaceStatus_1.png delete mode 100644 docs/4_APIs_and_Services/4.8_HomeScreen_(old)/pictures/api_getSurfaceStatus_2.png delete mode 100644 docs/4_APIs_and_Services/4.8_HomeScreen_(old)/pictures/api_getSurfaceStatus_3.png delete mode 100644 docs/4_APIs_and_Services/4.8_HomeScreen_(old)/pictures/api_hardKeyPressed.png delete mode 100644 docs/4_APIs_and_Services/4.8_HomeScreen_(old)/pictures/api_renderSurfaceToArea.png delete mode 100644 docs/4_APIs_and_Services/4.8_HomeScreen_(old)/pictures/api_renderSurfaceToAreaAllowed.png delete mode 100644 docs/4_APIs_and_Services/4.8_HomeScreen_(old)/pictures/api_requestSurfaceIdToFullScreen.png delete mode 100644 docs/4_APIs_and_Services/4.8_HomeScreen_(old)/pictures/api_surfaceVisibilityChanged.png (limited to 'docs/4_APIs_and_Services') diff --git a/docs/4_APIs_and_Services/4.1_API_Reference/0_api-introduction.md b/docs/4_APIs_and_Services/4.1_API_Reference/0_api-introduction.md deleted file mode 100644 index c536962..0000000 --- a/docs/4_APIs_and_Services/4.1_API_Reference/0_api-introduction.md +++ /dev/null @@ -1,54 +0,0 @@ - - - -# Available APIs - -Introduction of Available APIs with categorization. If multiple categories apply, they will all be listed in the third column (e.g. first row in the following). - - - -| API | Description | Profile | -| --- | --- | --- | -| [agl-service-audiomixer](https://git.automotivelinux.org/apps/agl-service-audiomixer/about/) | Audio Mixer API | | -| [agl-service-bluetooth](https://git.automotivelinux.org/apps/agl-service-bluetooth/about/) | bluetooth binding | Infotainment | -| [agl-service-bluetooth-avrcp](https://git.automotivelinux.org/apps/agl-service-bluetooth-avrcp/) | AGL service that allow multimedia control over Bluetooth AVRCP profile | Infotainment | -| [agl-service-bluetooth-pbap](https://git.automotivelinux.org/apps/agl-service-bluetooth-pbap/about/) | Bluetooth Phone Book Access Protocoll service | Infotainment | -| [agl-service-can-low-level](https://git.automotivelinux.org/apps/agl-service-can-low-level/about/) | Low level CAN service made to decode and write on CAN bus. | Instrument Cluster | -| [agl-service-data-persistence](https://git.automotivelinux.org/apps/agl-service-data-persistence/about/) | AGL binding for data persistence | Instrument Cluster | -| [agl-service-geoclue](https://git.automotivelinux.org/apps/agl-service-geoclue/about/) | AGL Geoclue service to backup GPS positioning with network-based
positioning | Infotainment | -| [agl-service-geofence](https://git.automotivelinux.org/apps/agl-service-geofence/about/) | AGL geofence binding to signal vehicle POI bounding box events | Infotainment | -| [agl-service-gps](https://git.automotivelinux.org/apps/agl-service-gps/about/) | GPS binding | Infotainment | -| [agl-service-gstreamer](https://git.automotivelinux.org/apps/agl-service-gstreamer/) | (deprecated) GStreamer binding for multimedia control and playback | Infotainment | -| [agl-service-harvester](https://git.automotivelinux.org/apps/agl-service-harvester/about/) | V2C interface that collect data to TimeSeries database | | -| [agl-service-homescreen](https://git.automotivelinux.org/apps/agl-service-homescreen/about/) | Applications need a new binding to communicate with homescreen | Infotainment | -| [agl-service-homescreen-2017](https://git.automotivelinux.org/apps/agl-service-homescreen-2017/about/) | Binding for applications to communicate with the homescreen-2017 | Infotainment | -| [agl-service-hvac](https://git.automotivelinux.org/apps/agl-service-hvac/) | Unnamed repository | | -| [agl-service-identity-agent](https://git.automotivelinux.org/apps/agl-service-identity-agent/about/) | Identity Agent | | -| [agl-service-iiodevices](https://git.automotivelinux.org/apps/agl-service-iiodevices/about/) | iiodevices support | Telematics/Connectivity | -| [agl-service-mediaplayer](https://git.automotivelinux.org/apps/agl-service-mediaplayer/about/) | AGL Media Player service that allows applications to control
playing media. | Infotainment | -| [agl-service-mediascanner](https://git.automotivelinux.org/apps/agl-service-mediascanner/about/) | AGL Media Scanning service that allows applications to detect
and index media at... | Telematics/Connectivity | -| [agl-service-navigation](https://git.automotivelinux.org/apps/agl-service-navigation/) | Navigation API with binding | Infotainment | -| [agl-service-network](https://git.automotivelinux.org/apps/agl-service-network/about/) | AGL Network service providing support for management of networking
interfaces in... | | -| [agl-service-nfc](https://git.automotivelinux.org/apps/agl-service-nfc/about/) | AGL service NFC binding | | -| [agl-service-radio](https://git.automotivelinux.org/apps/agl-service-radio/about/) | radio binding | | -| [agl-service-signal-composer](https://git.automotivelinux.org/apps/agl-service-signal-composer/about/) | AGL High Level Signaling service to handle CAN, LIN, and others
signaling source... | Instrument Cluster | -| [agl-service-soundmanager](https://git.automotivelinux.org/apps/agl-service-soundmanager/about/) | Binding for applications to communicate with the soundmanager | | -| [agl-service-soundmanager-2017](https://git.automotivelinux.org/apps/agl-service-soundmanager-2017/about/) | Binding for applications to communicate with the soundmanager-2017 | | -| [agl-service-speech](https://git.automotivelinux.org/apps/agl-service-speech/about/) | AGL App Framework Binding for Speech Services | Telematics/Connectivity | -| [agl-service-steering-wheel](https://git.automotivelinux.org/apps/agl-service-steering-wheel/about/) | And binding service for steering wheel demo | Instrument Cluster | -| [agl-service-taskmanager](https://git.automotivelinux.org/apps/agl-service-taskmanager/about/) | Simple taskmanager service to retrieve data from procps | | -| [agl-service-telephony](https://git.automotivelinux.org/apps/agl-service-telephony/about/) | Unnamed repository | | -| [agl-service-unicens](https://git.automotivelinux.org/apps/agl-service-unicens/about/) | Infotainment network setup and access (using Unified Centralized
Network Stack) | Infotainment | -| [agl-service-weather](https://git.automotivelinux.org/apps/agl-service-weather/about/) | AGL binding that uses OpenWeathermap data to display current
conditions on Homes... | Telematics/Connectivity | -| [agl-service-wifi](https://git.automotivelinux.org/apps/agl-service-wifi/) | wifi binding | Telematics/Connectivity | -| [agl-service-windowmanager](https://git.automotivelinux.org/apps/agl-service-windowmanager/about/) | Binding for applications to communicate with the windowmanager | | -| [agl-service-windowmanager-2017](https://git.automotivelinux.org/apps/agl-service-windowmanager-2017/about/) | Binding for applications to communicate with the windowmanager-2017 | | -| [agl-service-xds](https://git.automotivelinux.org/apps/agl-service-xds/) | AGL binding used to control collected data from AGL
supervision. (empty) | | -| [agl-service-xds-monitoring](https://git.automotivelinux.org/apps/agl-service-xds-monitoring/about/) | UNDER DEVELOPMENT | | diff --git a/docs/4_APIs_and_Services/4.2_Application_Framework/.md b/docs/4_APIs_and_Services/4.2_Application_Framework/.md deleted file mode 100644 index 3652d8d..0000000 --- a/docs/4_APIs_and_Services/4.2_Application_Framework/.md +++ /dev/null @@ -1,595 +0,0 @@ ---- -edit_link: '' -title: Widget configuration file -origin_url: >- - https://git.automotivelinux.org/src/app-framework-main/plain/docs/2.2-config.xml.md?h=master ---- - - - -# Configuration file - config.xml - -The widgets are described by the W3C's technical recommendations -[Packaged Web Apps (Widgets)][widgets] and [XML Digital Signatures for Widgets][widgets-digsig] - that specifies the configuration file **config.xml**. - -## Overview - -The file **config.xml** describes important data of the application -to the framework: - -- the unique identifier of the application -- the name of the application -- the type of the application -- the icon of the application -- the permissions linked to the application -- the services and dependencies of the application - -The file MUST be at the root of the widget and MUST be case sensitively name -***config.xml***. - -The file **config.xml** is a XML file described by the document -[widgets]. - -Here is the example of the config file for the QML application SmartHome. - -```xml - - - SmartHome - - - This is the Smarthome QML demo application. It shows some user interfaces for controlling an -automated house. The user interface is completely done with QML. - Qt team - GPL - -``` - -The most important items are: - -- ****: gives the id of the widget. It must be unique. - -- ****: gives the version of the widget - -- ****: gives a path to the icon of the application - (can be repeated with different sizes) - -- ****: this indicates the entry point and its type. - -## Standard elements of "config.xml" - -### The element widget - -#### the attribute id of widget - -The attribute *id* is mandatory (for version 2.x, blowfish) and must be unique. - -Values for *id* are any non empty string containing only latin letters, -arabic digits, and the three characters '.' (dot), '-' (dash) and -'\_' (underscore). - -Authors can use a mnemonic id or can pick a unique id using -command **uuid** or **uuidgen**. - -### the attribute version of widget - -The attribute *version* is mandatory (for version 2.x, blowfish). - -Values for *version* are any non empty string containing only latin letters, -arabic digits, and the three characters '.' (dot), '-' (dash) and -'\_' (underscore). - -Version values are dot separated fields MAJOR.MINOR.REVISION. -Such version would preferably follow guidelines of -[semantic versioning][semantic-version]. - -### The element content - -The element *content* is mandatory (for version 2.x, blowfish) and must designate a file -(subject to localization) with its attribute *src*. - -The content designed depends on its type. See below for the known types. - -### The element icon - -The element *icon* is mandatory (for version 2.x, blowfish) and must -be unique. It must designate an image file with its attribute *src*. - -## AGL features - -The AGL framework uses the feature tag for specifying security and binding -requirement of the widget. - -Since the migration of the framework to leverage systemd power, -the features are of important use to: - -- declare more than just an application -- declare the expected dependencies -- declare the expected permissions -- declare the exported apis - -The specification of [widgets][widgets] is intended to describe -only one application. -In the present case, we expect to describe more than just an application. -For example, a publisher could provide a widget containing a service, -an application for tuning that service, an application that -leverage the service. -Here, the term of service means a background application that -runs without IHM and whose public api can be accessed by other -applications. - -So the features are used to describe each of the possible -units of widgets. -The "standard" unit in the meaning of [widgets][widgets] -is called the "main" unit. - -### required-api: feature name="urn:AGL:widget:required-api" - -List of the api required by the widget. - -Each required api must be explicit using a `` entry. - -Example: - -```xml - - - - - -``` - -This will be *virtually* translated for mustaches to the JSON - -```json -"required-api": [ - { "name": "gps", "value": "auto" }, - { "name": "afm-main", "value": "link" } - ] -``` - -#### required-api: param name="#target" - -OPTIONAL - -Declares the name of the unit requiring the listed apis. -Only one instance of the param "#target" is allowed. -When there is not instance of this param, it behave as if -the target main was specified. - -#### required-api: param name=[required api name] - -The name is the name of the required API. - -The value describes how to connect to the required api. -It is either: - -- local: OBSOLETE SINCE FF (AGL6), PROVIDED FOR COMPATIBILITY - Use the feature **urn:AGL:widget:required-binding** instead. - The binding is a local shared object. - In that case, the name is the relative path of the - shared object to be loaded. - -- auto: - The framework set automatically the kind of - the connection to the API - -- ws: - The framework connect using internal websockets - -- dbus: [OBSOLETE, shouldn't be used currently] - The framework connect using internal dbus - -- tcp: - In that case, the name is the URI to access the service. - The framework connect using a URI of type - HOST:PORT/API - API gives the name of the imported api. - -- cloud: [PROPOSAL - NOT IMPLEMENTED] - The framework connect externally using websock. - In that case, the name includes data to access the service. - Example: `` - -### required-binding: feature name="urn:AGL:widget:required-binding" - -List of the bindings required by the widget. - -Note: Since AGL 6 (FF - Funky Flounder), -the binder implements bindings version 3 that allow the declaration -of 0, 1 or more APIs by one binding. In other words, the equivalency -one binding = one API is lost. At the same time the framework added -the ability to use bindings exported by other widgets. - -Each required binding must be explicit using a `` entry. - -Example: - -```xml - - - - -``` - -This will be *virtually* translated for mustaches to the JSON - -```json -"required-binding": [ - { "name": "libexec/binding-gps.so", "value": "local" }, - { "name": "extra", "value": "extern" } - ] -``` - -#### required-binding: param name=[name or path] - -The name or the path of the required BINDING. - -The value describes how to connect to the required binding. -It is either: - -- local: - The binding is a local shared object. - In that case, the name is the relative path of the - shared object to be loaded. - -- extern: - The binding is external. The name is the exported binding name. - See provided-binding. - -### provided-binding: feature name="urn:AGL:widget:provided-binding" - -This feature allows to export a binding to other binders. -The bindings whose relative name is given as value is exported to -other binders under the given name. - -Each provided binding must be explicit using a `` entry. - -Example: - -```xml - - - -``` - -This will be *virtually* translated for mustaches to the JSON - -```json -"provided-binding": [ - { "name": "extra", "value": "export/binding-gps.so" } - ] -``` - -#### provided-binding: param name=[exported name] - -Exports a local binding to other applications. - -The value must contain the path to the exported binding. - -### required-permission: feature name="urn:AGL:widget:required-permission" - -List of the permissions required by the unit. - -Each required permission must be explicit using a `` entry. - -Example: - -```xml - - - - - -``` - -This will be *virtually* translated for mustaches to the JSON - -```json -"required-permission":{ - "urn:AGL:permission:real-time":{ - "name":"urn:AGL:permission:real-time", - "value":"required" - }, - "urn:AGL:permission:syscall:*":{ - "name":"urn:AGL:permission:syscall:*", - "value":"required" - } -} -``` - -#### required-permission: param name="#target" - -OPTIONAL - -Declares the name of the unit requiring the listed permissions. -Only one instance of the param "#target" is allowed. -When there is not instance of this param, it behave as if -the target main was specified. - -#### required-permission: param name=[required permission name] - -The value is either: - -- required: the permission is mandatorily needed except if the feature - isn't required (required="false") and in that case it is optional. -- optional: the permission is optional - -### provided-unit: feature name="urn:AGL:widget:provided-unit" - -This feature is made for declaring new units -for the widget. -Using this feature, a software publisher -can provide more than one application in the same widget. - -Example: - -```xml - - - - - - -``` - -This will be *virtually* translated for mustaches to the JSON - -```json - { - "#target":"geoloc", - "description":"binding of name geoloc", - "content":{ - "src":"index.html", - "type":"application\/vnd.agl.service" - }, - ... - } -``` - -#### provided-unit: param name="#target" - -REQUIRED - -Declares the name of the unit. The default unit, the unit -of the main of the widget, has the name "main". -The value given here must be unique within the widget file. -It will be used in other places of the widget config.xml file to -designate the unit. - -Only one instance of the param "#target" is allowed. -The value can't be "main". - -#### provided-unit: param name="content.type" - -REQUIRED - -The mimetype of the provided unit. - -#### provided-unit: param name="content.src" - -A path to the source - -#### other parameters - -The items that can be set for the main unit -can also be set using the params if needed. - -- description -- name.content -- name.short -- ... - -### provided-api: feature name="urn:AGL:widget:provided-api" - -Use this feature for exporting one or more API of a unit -to other widgets of the platform. - -This feature is an important feature of the framework. - -Example: - -```xml - - - - - -``` - -This will be *virtually* translated for mustaches to the JSON - -```json - "provided-api":[ - { - "name":"geoloc", - "value":"auto" - }, - { - "name":"moonloc", - "value":"auto" - } - ], -``` - -#### provided-api: param name="#target" - -OPTIONAL - -Declares the name of the unit exporting the listed apis. -Only one instance of the param "#target" is allowed. -When there is not instance of this param, it behave as if -the target main was specified. - -#### provided-api: param name=[name of exported api] - -The name give the name of the api that is exported. - -The value is one of the following values: - -- ws: - export the api using UNIX websocket - -- dbus: [OBSOLETE, shouldn't be used currently] - export the API using dbus - -- auto: - export the api using the default method(s). - -- tcp: - In that case, the name is the URI used for exposing the service. - The URI is of type - HOST:PORT/API - API gives the name of the exported api. - -### file-properties: feature name="urn:AGL:widget:file-properties" - -Use this feature for setting properties to files of the widget. -At this time, this feature only allows to set executable flag -for making companion program executable explicitly. - -Example: - -```xml - - - - -``` - -#### file-properties: param name="path" - -The name is the relative path of the file whose property -must be set. - -The value must be "executable" to make the file executable. - -## Known content types - -The configuration file ***/etc/afm/afm-unit.conf*** defines -how to create systemd units for widgets. - -Known types for the type of content are: - -- ***text/html***: - HTML application, - content.src designates the home page of the application - -- ***application/vnd.agl.native*** - AGL compatible native, - content.src designates the relative path of the binary. - -- ***application/vnd.agl.service***: - AGL service, content.src is not used. - -- ***application/x-executable***: - Native application, - content.src designates the relative path of the binary. - For such application, only security setup is made. - -Adding more types is easy, it just need to edit the configuration -file ***afm-unit.conf***. - -### Older content type currently not supported at the moment - -This types were defined previously when the framework was not -leveraging systemd. -The transition to systemd let these types out at the moment. - -- ***application/vnd.agl.url*** -- ***text/vnd.qt.qml***, ***application/vnd.agl.qml*** -- ***application/vnd.agl.qml.hybrid*** -- ***application/vnd.agl.html.hybrid*** - - - -## The configuration file afm-unit.conf - -The integration of the framework with systemd -mainly consists of creating the systemd unit -files corresponding to the need and requirements -of the installed widgets. - -This configuration file named `afm-unit.conf` installed -on the system with the path `/etc/afm/afm-unit.conf` -describes how to generate all units from the *config.xml* -configuration files of widgets. -The description uses an extended version of the templating -formalism of [mustache][] to describes all the units. - -Let present how it works using the following diagram that -describes graphically the workflow of creating the unit -files for systemd `afm-unit.conf` from the configuration -file of the widget `config.xml`: - -![make-units](pictures/make-units.svg) - -In a first step, and because [mustache][] is intended -to work on JSON representations, the configuration file is -translated to an internal JSON representation. -This representation is shown along the examples of the documentation -of the config files of widgets. - -In a second step, the mustache template `afm-unit.conf` -is instantiated using the C library [mustach][] that follows -the rules of [mustache][mustache] and with all its available -extensions: - -- use of colon (:) for explicit substitution -- test of values with = or =! - -In a third step, the result of instantiating `afm-unit.conf` -for the widget is split in units. -To achieve that goal, the lines containing specific directives are searched. -Any directive occupy one full line. -The directives are: - -- %nl - Produce an empty line at the end -- %begin systemd-unit -- %end systemd-unit - Delimit the produced unit, its begin and its end -- %systemd-unit user -- %systemd-unit system - Tells the kind of unit (user/system) -- %systemd-unit service NAME -- %systemd-unit socket NAME - Gives the name and type (service or socket) of the unit. - The extension is automatically computed from the type - and must not be set in the name. -- %systemd-unit wanted-by NAME - Tells to install a link to the unit in the wants of NAME - -Then the computed units are then written to the filesystem -and inserted in systemd. - -The generated unit files will contain variables for internal -use of the framework. -These variables are starting with `X-AFM-`. -The variables starting with `X-AFM-` but not with `X-AFM--` are -the public variables. -These variables will be returned by the -framework as the details of an application (see **afm-util detail ...**). - -Variables starting with `X-AFM--` are private to the framework. -By example, the variable `X-AFM--http-port` is used to -record the allocated port for applications. - -[mustach]: https://gitlab.com/jobol/mustach "basic C implementation of mustache" -[mustache]: http://mustache.github.io/mustache.5.html "mustache - Logic-less templates" -[widgets]: http://www.w3.org/TR/widgets "Packaged Web Apps" -[widgets-digsig]: http://www.w3.org/TR/widgets-digsig "XML Digital Signatures for Widgets" -[libxml2]: http://xmlsoft.org/html/index.html "libxml2" -[app-manifest]: http://www.w3.org/TR/appmanifest "Web App Manifest" -[meta-intel]: https://github.com/01org/meta-intel-iot-security "A collection of layers providing security technologies" -[openssl]: https://www.openssl.org "OpenSSL" -[xmlsec]: https://www.aleksey.com/xmlsec "XMLSec" -[json-c]: https://github.com/json-c/json-c "JSON-c" -[d-bus]: http://www.freedesktop.org/wiki/Software/dbus "D-Bus" -[libzip]: http://www.nih.at/libzip "libzip" -[cmake]: https://cmake.org "CMake" -[security-manager]: https://wiki.tizen.org/wiki/Security/Tizen_3.X_Security_Manager "Security-Manager" -[tizen-security]: https://wiki.tizen.org/wiki/Security "Tizen security home page" -[tizen-secu-3]: https://wiki.tizen.org/wiki/Security/Tizen_3.X_Overview "Tizen 3 security overview" -[semantic-version]: http://semver.org/ "Semantic versioning" diff --git a/docs/4_APIs_and_Services/4.2_Application_Framework/0_introduction.md b/docs/4_APIs_and_Services/4.2_Application_Framework/0_introduction.md deleted file mode 100644 index 88e1c78..0000000 --- a/docs/4_APIs_and_Services/4.2_Application_Framework/0_introduction.md +++ /dev/null @@ -1,273 +0,0 @@ ---- -edit_link: '' -title: Introduction -origin_url: >- - https://git.automotivelinux.org/src/app-framework-main/plain/docs/0-introduction.md?h=master ---- - - - -# AGL framework overview - -## Foreword - -This document describes what we intend to do. -It may happen that our current implementation and the content of this document differ. - -In case of differences, it is assumed that this document is right -and the implementation is wrong. - -## Introduction - -During the first works in having the security model of Tizen -integrated in AGL (Automotive Grade Linux) distribution, it became -quickly obvious that the count of components specific to Tizen -to integrate was huge. - -Here is a minimal list of what was needed: - -- platform/appfw/app-installers -- platform/core/security/cert-svc -- platform/core/appfw/ail -- platform/core/appfw/aul-1 -- platform/core/appfw/libslp-db-util -- platform/core/appfw/pkgmgr-info -- platform/core/appfw/slp-pkgmgr - -But this list isn't complete because many dependencies are hidden. -Those hidden dependencies are including some common libraries but also many -tizen specific sub-components: - -- iniparser -- bundle -- dlog, -- libtzplatform-config -- db-util -- vconf-buxton -- ... - -This is an issue because AGL is not expected to be Tizen. -Taking it would either need to patch it for removing unwanted components or to take all of them. - -However, a careful study of the core components of the security framework -of Tizen showed that their dependencies to Tizen are light (and since some -of our work, there is no more dependency to tizen). -Those components are : - -- **cynara** -- **security-manager** -- **D-Bus aware of cynara** - -Luckily, these core security components of Tizen are provided -by [meta-intel-iot-security][meta-intel], a set of yocto layers. -These layers were created by Intel to isolate Tizen specific security -components from the initial port of Tizen to Yocto. -The 3 layers are providing components for: - -- Implementing Smack LSM -- Implementing Integrity Measurement Architecture -- Implementing Tizen Security Framework - -The figure below shows the history of these layers. - -![Security_model_history][Security_model_history] - -We took the decision to use these security layers that provide the -basis of the Tizen security, the security framework. - -For the components of the application framework, built top of -the security framework, instead of pulling the huge set of packages -from Tizen, we decided to refit it by developing a tiny set of -components that would implement the same behaviour but without all -the dependencies and with minor architectural improvements for AGL. - -These components are : - -- **afm-system-daemon** -- **afm-user-daemon** - -They provides infrastructure for installing, uninstalling, -launching, terminating, pausing and resuming applications in -a multi user secure environment. - -A third component exists in the framework, the binder **afb-daemon**. -The binder provides the easiest way to provide secured API for -any tier. -Currently, the use of the binder is not absolutely mandatory. - -This documentation explains the framework created by IoT.bzh -by rewriting the Tizen Application Framework. -Be aware of the previous foreword. - - - -## Overview - -The figure below shows the major components of the framework -and their interactions going through the following scenario: - -- APPLICATION installs an other application and then launch it. - -![AppFW-APP_install_sequences][AppFW-APP_install_sequences]{:: style="width:70%;"} - -Let follow the sequence of calls: - -1. APPLICATION calls its **binder** to install the OTHER application. - -1. The binding **afm-main-binding** of the **binder** calls, through - **D-Bus** system, the system daemon to install the OTHER application. - -1. The system **D-Bus** checks wether APPLICATION has the permission - or not to install applications by calling **CYNARA**. - -1. The system **D-Bus** transmits the request to **afm-system-daemon**. - - **afm-system-daemon** checks the application to install, its - signatures and rights and install it. - -1. **afm-system-daemon** calls **SECURITY-MANAGER** for fulfilling - security context of the installed application. - -1. **SECURITY-MANAGER** calls **CYNARA** to install initial permissions - for the application. - -1. APPLICATION call its binder to start the nearly installed OTHER application. - -1. The binding **afm-main-binding** of the **binder** calls, through - **D-Bus** session, the user daemon to launch the OTHER application. - -1. The session **D-Bus** checks wether APPLICATION has the permission - or not to start an application by calling **CYNARA**. - -1. The session **D-Bus** transmits the request to **afm-user-daemon**. - -1. **afm-user-daemon** checks wether APPLICATION has the permission - or not to start the OTHER application **CYNARA**. - -1. **afm-user-daemon** uses **SECURITY-MANAGER** features to set - the security context for the OTHER application. - -1. **afm-user-daemon** launches the OTHER application. - -This scenario does not cover all the features of the frameworks. -Shortly because details will be revealed in the next chapters, -the components are: - -- ***SECURITY-MANAGER***: in charge of setting Smack contexts and rules, - of setting groups, and, of creating initial content of *CYNARA* rules - for applications. - -- ***CYNARA***: in charge of handling API access permissions by users and by - applications. - -- ***D-Bus***: in charge of checking security of messaging. The usual D-Bus - security rules are enhanced by *CYNARA* checking rules. - -- ***afm-system-daemon***: in charge of installing and uninstalling applications. - -- ***afm-user-daemon***: in charge of listing applications, querying application details, - starting, terminating, pausing, resuming applications and their instances - for a given user context. - -- ***afb-binder***: in charge of serving resources and features through an - HTTP interface. - -- ***afm-main-binding***: This binding allows applications to use the API - of the AGL framework. - -## Links between the "Security framework" and the "Application framework" - -The security framework refers to the security model used to ensure -security and to the tools that are provided for implementing that model. - -The security model refers to how DAC (Discretionary Access Control), -MAC (Mandatory Access Control) and Capabilities are used by the system -to ensure security and privacy. -It also includes features of reporting using audit features and by managing -logs and alerts. - -The application framework manages the applications: - -- installing -- uninstalling -- starting -- pausing -- listing -- ... - -The application framework uses the security model/framework -to ensure the security and the privacy of the applications that -it manages. - -The application framework must be compliant with the underlying -security model/framework. -But it should hide it to the applications. - -## The security framework - -The implemented security model is the security model of Tizen 3. -This model is described [here][tizen-secu-3]. - -The security framework then comes from Tizen 3 but through -the [meta-intel]. -It includes: - -- **Security-Manager** -- **Cynara** -- **D-Bus** compliant to Cynara. - -Two patches are applied to the security-manager. -The goal of these patches is to remove specific dependencies with Tizen packages that are not needed by AGL. -None of these patches adds or removes any behaviour. - -**In theory, the security framework/model is an implementation details -that should not impact the layers above the application framework**. - -The security framework of Tizen provides "nice lad" a valuable component to -scan log files and analyse auditing. -This component is still in development. - -## The application framework - -The application framework on top of the security framework -provides the components to install and uninstall applications -and to run it in a secured environment. - -The goal is to manage applications and to hide the details of -the security framework to the applications. - -For the reasons explained in introduction, we did not used the -application framework of Tizen as is but used an adaptation of it. - -The basis is kept identical: - -- The applications are distributed in a digitally signed container that must - match the specifications of widgets (web applications). - -This is described by the technical recommendations [widgets] and -[widgets-digsig] of the W3 consortium. - -This model allows: - -- The distribution of HTML, QML and binary applications. -- The management of signatures of the widget packages. - -This basis is not meant as being rigid and it can be extended in the -future to include for example incremental delivery. - -[meta-intel]: https://github.com/01org/meta-intel-iot-security "A collection of layers providing security technologies" -[widgets]: http://www.w3.org/TR/widgets "Packaged Web Apps" -[widgets-digsig]: http://www.w3.org/TR/widgets-digsig "XML Digital Signatures for Widgets" -[libxml2]: http://xmlsoft.org/html/index.html "libxml2" -[openssl]: https://www.openssl.org "OpenSSL" -[xmlsec]: https://www.aleksey.com/xmlsec "XMLSec" -[json-c]: https://github.com/json-c/json-c "JSON-c" -[d-bus]: http://www.freedesktop.org/wiki/Software/dbus "D-Bus" -[libzip]: http://www.nih.at/libzip "libzip" -[cmake]: https://cmake.org "CMake" -[security-manager]: https://wiki.tizen.org/wiki/Security/Tizen_3.X_Security_Manager "Security-Manager" -[app-manifest]: http://www.w3.org/TR/appmanifest "Web App Manifest" -[tizen-security]: https://wiki.tizen.org/wiki/Security "Tizen security home page" -[tizen-secu-3]: https://wiki.tizen.org/wiki/Security/Tizen_3.X_Overview "Tizen 3 security overview" -[AppFW-APP_install_sequences]: pictures/AppFW-APP_install_sequences.svg -[Security_model_history]: pictures/Security_model_history.svg diff --git a/docs/4_APIs_and_Services/4.2_Application_Framework/1_afm-daemons.md b/docs/4_APIs_and_Services/4.2_Application_Framework/1_afm-daemons.md deleted file mode 100644 index 55cec4d..0000000 --- a/docs/4_APIs_and_Services/4.2_Application_Framework/1_afm-daemons.md +++ /dev/null @@ -1,656 +0,0 @@ ---- -edit_link: '' -title: The afm daemons -origin_url: >- - https://git.automotivelinux.org/src/app-framework-main/plain/docs/1-afm-daemons.md?h=master ---- - - - -# The application framework daemons - -## Foreword - -This document describes application framework daemons -FCS (Fully Conform to Specification) implementation is still under development. -It may happen that current implementation somehow diverges with specifications. - -## Introduction - -Daemons ***afm-user-daemon*** and ***afm-system-daemon*** handle applications -life. -Understand that they will manage operations like: - -- ***installation*** -- ***uninstallation*** -- ***running*** -- ***suspend*** -- ***inventory*** -- ... - -In addition, they ensure that operations use the security framework as needed -and that applications are executed in the correct context. - -***D-Bus*** is in charge of transmitting orders to the appropriate daemon -depending upon ***D-Bus*** destination. - -The figure below summarizes the situation of both **afm-system-daemon** and -**afm-user-daemon** in the system. - -![afm-daemons][afm-daemons]{:: style="width:65%;"} - -## The D-Bus interface - -### Overview of the dbus interface - -The ***afm daemons*** takes theirs orders from the session instance -of D-Bus. -The use of D-Bus is great because it allows to implement -discovery and signaling. - -The dbus session is by default addressed by environment -variable *DBUS_SESSION_BUS_ADDRESS*. Using **systemd** -variable *DBUS_SESSION_BUS_ADDRESS* is automatically set for -user sessions. - -They are listening with the destination name ***org.AGL.afm.[user|system]*** -at the object of path ***/org/AGL/afm/[user|system]*** on the interface -***org.AGL.afm.[user|system]*** for the below detailed members for the -***afm-system-daemon***: - -- ***install*** -- ***uninstall*** - -And for ***afm-user-daemon***: - -- ***runnables*** -- ***detail*** -- ***start*** -- ***once*** -- ***terminate*** -- ***pause*** -- ***resume*** -- ***runners*** -- ***state*** -- ***install*** -- ***uninstall*** - -D-Bus is mainly used for signaling and discovery. -Its optimized typed protocol is not used except for transmitting - only one string in both directions. - -The client and the service are using JSON serialization to -exchange data. -Signature of any member of the D-Bus interface is -***string -> string*** for ***JSON -> JSON***. -This is the normal case, if there is an error, current implementation -returns a dbus error that is a string. - -Here are examples using *dbus-send*, here to install an application from a -widget file: - -```bash -dbus-send --session --print-reply \ - --dest=org.AGL.afm.system \ - /org/AGL/afm/system \ - org.AGL.afm.system.install 'string:"/tmp/appli.wgt" -``` - -And here, to query data on installed applications that can be run: - -```bash -dbus-send --session --print-reply \ - --dest=org.AGL.afm.user \ - /org/AGL/afm/user \ - org.AGL.afm.user.runnables string:true -``` - -### The protocol over D-Bus - -On all following sub-chapters we assume that we talk about either -***afm-system-daemon*** or ***afm-user-daemon***. Method and D-Bus parameters -are considered as self-explanatory. - -The D-Bus interface is defined by: - -- **DESTINATION**: org.AGL.afm.[user|system] -- **PATH**: /org/AGL/afm/[user|system] -- **INTERFACE**: org.AGL.afm.[user|system] - -#### Method org.AGL.afm.system.install - -**Description**: Install an application from a widget file. - -When an application with the same *id* and *version* already exists. Outside of -using *force=true* the application is not reinstalled. - -Applications are installed the subdirectories of applications common directory. -If *root* is specified, the application is installed under the -sub-directories of the *root* defined. - -Note that this methods is a simple accessor method of -***org.AGL.afm.system.install*** from ***afm-system-daemon***. - -After the installation and before returning to the sender, -***afm-system-daemon*** sends a signal ***org.AGL.afm.system.changed***. - -**Input**: The *path* of the widget file to install and, optionally, -a flag to *force* reinstallation, and, optionally, a *root* directory. - -Either just a string being the absolute path of the widget file: - -```bash -"/a/path/driving/to/the/widget" -``` - -Or an object: - -```json -{ - "wgt": "/a/path/to/the/widget", - "force": false, - "root": "/a/path/to/the/root" -} -``` - -"wgt" and "root" must be absolute paths. - -**output**: An object with the field "added" being the string for -the id of the added application. - -```json -{"added":"appli@x.y"} -``` - ---- - -#### Method org.AGL.afm.system.uninstall - -**Description**: Uninstall an application from its id. - -Note that this methods is a simple method accessor of -***org.AGL.afm.system.uninstall*** from ***afm-system-daemon***. - -After the uninstallation and before returning to the sender, -***afm-system-daemon*** sends a signal ***org.AGL.afm.system.changed***. - -**Input**: the *id* of the application and optionally the application *root* path. - -Either a string: - -```bash -"appli@x.y" -``` - -Or an object: - -```json -{ - "id": "appli@x.y", - "root": "/a/path/to/the/root" -} -``` - -**output**: the value 'true'. - ---- - -#### Method org.AGL.afm.user.detail - -**Description**: Get details about an application from its id. - -**Input**: the id of the application as below. - -Either just a string: - -```bash -"appli@x.y" -``` - -Or an object having the field "id" of type string: - -```json -{"id":"appli@x.y"} -``` - -**Output**: A JSON object describing the application containing -the fields described below. - -```json -{ - "id": string, the application id (id@version) - "version": string, the version of the application - "width": integer, requested width of the application - "height": integer, requested height of the application - "name": string, the name of the application - "description": string, the description of the application - "shortname": string, the short name of the application - "author": string, the author of the application -} -``` - ---- - -#### Method org.AGL.afm.user.runnables - -**Description**: Get the list of applications that can be run. - -**Input**: any valid json entry, can be anything except null. - -**output**: An array of description of the runnable applications. -Each item of the array contains an object containing the detail of -an application as described above for the method -*org.AGL.afm.user.detail*. - ---- - -#### Method org.AGL.afm.user.install - -**Description**: Install an application from its widget file. - -If an application of the same *id* and *version* exists, it is not -reinstalled except when *force=true*. - -Applications are installed in the subdirectories of the common directory -reserved for applications. -If *root* is specified, the application is installed under -sub-directories of defined *root*. - -Note that this methods is a simple accessor to the method -***org.AGL.afm.system.install*** of ***afm-system-daemon***. - -After the installation and before returning to the sender, -***afm-user-daemon*** sends the signal ***org.AGL.afm.user.changed***. - -**Input**: The *path* of widget file to be installed. Optionally, -a flag to *force* reinstallation and/or a *root* directory. - -Simple form a simple string containing the absolute widget path: - -```bash -"/a/path/driving/to/the/widget" -``` - -Or an object: - -```json -{ - "wgt": "/a/path/to/the/widget", - "force": false, - "root": "/a/path/to/the/root" -} -``` - -***wgt*** and ***root*** MUST be absolute paths. - -**output**: An object containing field "added" to use as application ID. - -```json -{"added":"appli@x.y"} -``` - ---- - -#### Method org.AGL.afm.user.uninstall - -**Description**: Uninstall an application from its id. - -Note that this methods is a simple accessor to -***org.AGL.afm.system.uninstall*** method from ***afm-system-daemon***. - -After the uninstallation and before returning to the sender, -***afm-user-daemon*** sends the signal ***org.AGL.afm.user.changed***. - -**Input**: the *id* of the application and, optionally, the path to -application *root*. - -Either a string: - -```bash -"appli@x.y" -``` - -Or an object: - -```json -{ - "id": "appli@x.y", - "root": "/a/path/to/the/root" -} -``` - -**output**: the value 'true'. - ---- - -#### Method org.AGL.afm.user.start - -**Description**: - -**Input**: the *id* of the application and, optionally, the -start *mode* as below. - -Either just a string: - -```bash -"appli@x.y" -``` - -Or an object containing field "id" of type string and -optionally a field mode: - -```json -{"id":"appli@x.y","mode":"local"} -``` - -The field "mode" is a string equal to either "local" or "remote". - -[Currently the mode is not available in the systemd version] - -**output**: The *runid* of the application launched. *runid* is an integer. - ---- - -#### Method org.AGL.afm.user.once - -**Description**: - -**Input**: the *id* of the application - -Either just a string: - -```bash -"appli@x.y" -``` - -Or an object containing field "id" of type string. - -```json -{"id":"appli@x.y"} -``` - -**output**: The *state* of the application retrieved or launched. -See *org.AGL.afm.user.state* to get a description of the returned -object. - ---- - -#### Method org.AGL.afm.user.terminate - -**Description**: Terminates the application attached to *runid*. - -**Input**: The *runid* (an integer) of running instance to terminate. - -**output**: the value 'true'. - ---- - -#### Method org.AGL.afm.user.stop - -Obsolete since 8th November 2016 (2016/11/08). -Kept for compatibility. - -Use **org.AGL.afm.user.pause** instead. - ---- - -#### Method org.AGL.afm.user.continue - -Obsolete since 8th November 2016 (2016/11/08). -Kept for compatibility. - -Use **org.AGL.afm.user.resume** instead. - ---- - -#### Method org.AGL.afm.user.pause - -[Currently not available in the systemd version] - -**Description**: Pauses the application attached to *runid* until terminate or resume. - -**Input**: The *runid* (integer) of the running instance to pause. - -**output**: the value 'true'. - ---- - -#### Method org.AGL.afm.user.resume - -[Currently not available in the systemd version] - -**Description**: Resumes the application attached to *runid* previously paused. - -**Input**: The *runid* (integer) of the running instance to resume. - -**output**: the value 'true'. - ---- - -#### Method org.AGL.afm.user.state - -**Description**: Get information about a running instance of *runid*. - -**Input**: The *runid* (integer) of the running instance inspected. - -**output**: An object describing instance state. -It contains: - -- the runid (integer) -- the pids of the processes as an array starting -- with the group leader -- the id of the running application (string) -- the state of the application (string either: "starting", "running", "paused"). - -Example of returned state: - -```json - { - "runid": 2, - "pids": [ 435, 436 ], - "state": "running", - "id": "appli@x.y" - } -``` - ---- - -#### Method org.AGL.afm.user.runners - -**Description**: Get the list of currently running instances. - -**Input**: anything. - -**output**: An array of states, one per running instance, as returned by -the method ***org.AGL.afm.user.state***. - -## Starting **afm daemons** - -***afm-system-daemon*** and ***afm-user-daemon*** are launched as systemd -services attached to system and user respectively. -Normally, service files are locatedat */lib/systemd/system/afm-system-daemon.service* and -*/usr/lib/systemd/user/afm-user-daemon.service*. - -### ***afm-system-daemon*** options - -The options for launching **afm-system-daemon** are: - -```bash - -r - --root directory - - Set the root application directory. - - Note that the default root directory is defined - to be /usr/share/afm/applications (may change). - - -d - --daemon - - Daemonizes the process. It is not needed by systemd. - - -q - --quiet - - Reduces the verbosity (can be repeated). - - -v - --verbose - - Increases the verbosity (can be repeated). - - -h - --help - - Prints a short help. -``` - -### ***afm-user-daemon*** options - -The options for launching **afm-user-daemon** are: - -```bash - -a - --application directory - - [Currently not available in the systemd version] - - Includes the given application directory to - the database base of applications. - - Can be repeated. - - -r - --root directory - - [Currently not available in the systemd version] - - Includes root application directory or directories when - passing multiple rootdir to - applications database. - - Note that default root directory for - applications is always added. In current version - /usr/share/afm/applications is used as default. - - -m - --mode (local|remote) - - [Currently not available in the systemd version] - - Set the default launch mode. - The default value is 'local' - - -d - --daemon - - Daemonizes the process. It is not needed by systemd. - - -q - --quiet - - Reduces the verbosity (can be repeated). - - -v - --verbose - - Increases the verbosity (can be repeated). - - -h - --help - - Prints a short help. -``` - -## Tasks of **afm-user-daemon** - -### Maintaining list of applications - -At start **afm-user-daemon** scans the directories containing -applications and load in memory a list of available applications -accessible by current user. - -When **afm-system-daemon** installs or removes an application. -On success it sends the signal *org.AGL.afm.system.changed*. -When receiving such a signal, **afm-user-daemon** rebuilds its -applications list. - -**afm-user-daemon** provides the data it collects about -applications to its clients. -Clients may either request the full list -of available applications or a more specific information about a -given application. - -### Launching application - -**afm-user-daemon** launches application by using systemd. -Systemd builds a secure environment for the application -before starting it. - -Once launched, running instances of application receive -a runid that identify them. -To make interface with systemd evident, the pid is the runid. - -### Managing instances of running applications - -**afm-user-daemon** manages the list of applications -that it launched. - -When owning the right permissions, a client can get the list -of running instances and details about a specific -running instance. -It can also terminate a given application. - -### Installing and uninstalling applications - -If the client own the right permissions, -**afm-user-daemon** delegates that task -to **afm-system-daemon**. - -## Using ***afm-util*** - -The command line tool ***afm-util*** uses dbus-send to send -orders to **afm-user-daemon**. -This small scripts allows to send command to ***afm-user-daemon*** either -interactively at shell prompt or scriptically. - -The syntax is simple: - -- it accept a command and when requires attached arguments. - -Here is the summary of ***afm-util***: - -- **afm-util runnables **: - list the runnable widgets installed - -- **afm-util install wgt **: - install the wgt file - -- **afm-util uninstall id **: - remove the installed widget of id - -- **afm-util detail id **: - print detail about the installed widget of id - -- **afm-util runners **: - list the running instance - -- **afm-util start id **: - start an instance of the widget of id - -- **afm-util once id **: - run once an instance of the widget of id - -- **afm-util terminate rid **: - terminate the running instance rid - -- **afm-util state rid **: - get status of the running instance rid - -Here is how to list applications using ***afm-util***: - -```bash - afm-util runnables -``` - -[afm-daemons]: pictures/afm-daemons.svg diff --git a/docs/4_APIs_and_Services/4.2_Application_Framework/2_widgets.md b/docs/4_APIs_and_Services/4.2_Application_Framework/2_widgets.md deleted file mode 100644 index d0d57e2..0000000 --- a/docs/4_APIs_and_Services/4.2_Application_Framework/2_widgets.md +++ /dev/null @@ -1,16 +0,0 @@ ---- -edit_link: '' -title: Widgets -origin_url: >- - https://git.automotivelinux.org/src/app-framework-main/plain/docs/2-widgets.md?h=master ---- - - - -# The widgets - -The widgets are described by the W3C's technical recommendations -[Packaged Web Apps (Widgets)](http://www.w3.org/TR/widgets) and [XML Digital Signatures for Widgets](http://www.w3.org/TR/widgets-digsig) - -In summary, **widgets are ZIP files that can be signed and -whose content is described by the file **. diff --git a/docs/4_APIs_and_Services/4.2_Application_Framework/3_widgets.md b/docs/4_APIs_and_Services/4.2_Application_Framework/3_widgets.md deleted file mode 100644 index c69efdd..0000000 --- a/docs/4_APIs_and_Services/4.2_Application_Framework/3_widgets.md +++ /dev/null @@ -1,162 +0,0 @@ ---- -edit_link: '' -title: Overview of widgets -origin_url: >- - https://git.automotivelinux.org/src/app-framework-main/plain/docs/2.1-widgets.md?h=master ---- - - - -# Tools for managing widgets - -This project includes tools for managing widgets. -These tools are: - -- ***wgtpkg-info***: command line tool to display - informations about a widget file. - -- ***wgtpkg-install***: command line tool to - install a widget file. - -- ***wgtpkg-pack***: command line tool to create - a widget file from a widget directory. - -- ***wgtpkg-sign***: command line tool to add a signature - to a widget directory. - -For all these commands, a tiny help is available with -options **-h** or **--help**. - -There is no tool for unpacking a widget. -For doing such operation, you can use the command **unzip**. - -To list the files of a widget: - -```bash -unzip -l WIDGET -``` - -To extract a widget in some directory: - -```bash -unzip WIDGET -d DIRECTORY -``` - -*Note: that DIRECTORY will be created if needed*. - -## Getting data about a widget file - -The command **wgtpkg-info** opens a widget file, reads its **config.xml** -file and displays its content in a human readable way. - -## Signing and packing widget - -### Signing - -To sign a widget, you need a private key and its certificate. - -The tool **wgtpkg-sign** creates or replace a signature file in -the directory of the widget BEFORE its packaging. - -There are two types of signature files: author and distributor. - -Example 1: add an author signature - -```bash -wgtpkg-sign -a -k me.key.pem -c me.cert.pem DIRECTORY -``` - -Example 2: add a distributor signature - -```bash -wgtpkg-sign -k authority.key.pem -c authority.cert.pem DIRECTORY -``` - -### Packing - -This operation can be done using the command **zip** but -we provide the tool **wgtpkg-pack** that may add checking. - -Example: - -```bash -wgtpkg-pack DIRECTORY -o file.wgt -``` - -## Writing a widget - -### App directory organization - -There are few directories that are by default used in the binder. At the root -directory of the widget folder, here are the directories that could be used: - -- *lib* : default directory where lies external libraries needed for - the binding. Binding could be stored here too or in another directory of your - choice. -- *htdocs* : root HTTP directory if binding has web UI. - -### The steps for writing a widget - -1. make your application -1. create its configuration file **config.xml** -1. sign it -1. pack it - -Fairly easy, no? - -## Organization of directory of applications - -### directory where are stored applications - -Applications can be installed in different places: - -- the system itself, extension device. - -On a phone application are typically installed on the sd card. - -This translates to: - -- /var/local/lib/afm/applications - -From here this path is referenced as: "APPDIR". - -The main path for applications is: APPDIR/PKGID/VER. - -Where: - -- APPDIR is as defined above -- PKGID is a directory whose name is the package identifier -- VER is the version of the package MAJOR.MINOR - -This organization has the advantage to allow several versions -to leave together. -This is needed for some good reasons (rolling back) and also for less good reasons (user habits). - -### Identity of installed files - -All files are installed as user "afm" and group "afm". -All files have rw(x) for user and r-(x) for group and others. - -This allows every user to read every file. - -### labeling the directories of applications - -The data of a user are in its directory and are labelled by the security-manager using the application labels. - -[widgets]: http://www.w3.org/TR/widgets "Packaged Web Apps" -[widgets-digsig]: http://www.w3.org/TR/widgets-digsig "XML Digital Signatures for Widgets" -[app-manifest]: http://www.w3.org/TR/appmanifest "Web App Manifest" -[meta-intel]: https://github.com/01org/meta-intel-iot-security "A collection of layers providing security technologies" -[widgets]: http://www.w3.org/TR/widgets "Packaged Web Apps" -[widgets-digsig]: http://www.w3.org/TR/widgets-digsig "XML Digital Signatures for Widgets" -[libxml2]: http://xmlsoft.org/html/index.html "libxml2" -[openssl]: https://www.openssl.org "OpenSSL" -[xmlsec]: https://www.aleksey.com/xmlsec "XMLSec" -[json-c]: https://github.com/json-c/json-c "JSON-c" -[d-bus]: http://www.freedesktop.org/wiki/Software/dbus "D-Bus" -[libzip]: http://www.nih.at/libzip "libzip" -[cmake]: https://cmake.org "CMake" -[security-manager]: https://wiki.tizen.org/wiki/Security/Tizen_3.X_Security_Manager "Security-Manager" -[app-manifest]: http://www.w3.org/TR/appmanifest "Web App Manifest" -[tizen-security]: https://wiki.tizen.org/wiki/Security "Tizen security home page" -[tizen-secu-3]: https://wiki.tizen.org/wiki/Security/Tizen_3.X_Overview "Tizen 3 security overview" diff --git a/docs/4_APIs_and_Services/4.2_Application_Framework/4_permissions.md b/docs/4_APIs_and_Services/4.2_Application_Framework/4_permissions.md deleted file mode 100644 index b4038e3..0000000 --- a/docs/4_APIs_and_Services/4.2_Application_Framework/4_permissions.md +++ /dev/null @@ -1,138 +0,0 @@ ---- -edit_link: '' -title: Permissions -origin_url: >- - https://git.automotivelinux.org/src/app-framework-main/plain/docs/3-permissions.md?h=master ---- - - - -# The permissions - -## Permission's names - -The proposal here is to specify a naming scheme for permissions -that allows the system to be as stateless as possible. -The current specification includes in the naming of permissions either -the name of the bound binding when existing and the level of the -permission itself. -Doing this, there is no real need for the -framework to keep installed permissions in a database. - -The permission names are [URN][URN] of the form: - -```bash - urn:AGL:permission::: -``` - -where "AGL" is the NID (the namespace identifier) dedicated to AGL. -(note: a RFC should be produced to standardize this name space) - -The permission names are made of NSS (the namespace specific string) -starting with "permission:" and followed by colon separated -fields. -The 2 first fields are `` and `` and the remaining -fields are grouped to form the ``. - -```bash - ::= [ ] - - ::= 1* - - ::= | | | - - ::= "-" | "." | "_" | "@" -``` - -The field `` can be made of any valid character for NSS except -the characters colon and star (:*). -This field designates the api providing the permission. -This scheme is used to deduce binding requirements -from permission requirements. -The field `` can be the empty string when the permission -is defined by the AGL system itself. - -[PROPOSAL 1] The field `` if starting with the character "@" represents -a transversal/cross permission not bound to any binding. - -[PROPOSAL 2]The field `` if starting with the 2 characters "@@" -in addition to a permission not bound to any binding, represents a -permission that must be set at installation and that can not be -revoked later. - - ::= 1* - -The field `` is made only of letters in lower case. -The field `` can only take some predefined values: - -- system -- platform -- partner -- tiers -- owner -- public - -The field `` is made of `` separated -by colons. - - ::= 0*(":" ) - -The names at left are hierarchically grouping the -names at right. -This hierarchical behaviour is intended to -be used to request permissions using hierarchical grouping. - -## Permission value - -In some case, it could be worth to add a value to a permission. - -Currently, the framework allows it for permissions linked to -systemd. -But this not currently used. - -Conversely, permissions linked to cynara can't carry data -except in their name. - -Thus to have a simple and cleaner model, it is better to forbid -attachment of value to permission. - -## Example of permissions - -Here is a list of some possible permissions. -These permissions are available the 21th of May 2019. - -- urn:AGL:permission::platform:no-oom - Set OOMScoreAdjust=-500 to keep the out-of-memory - killer away. -- urn:AGL:permission::partner:real-time - Set IOSchedulingClass=realtime to give to the process - realtime scheduling. - Conversely, not having this permission set RestrictRealtime=on - to forbid realtime features. -- urn:AGL:permission::public:display - Adds the group "display" to the list of supplementary groups - of the process. -- urn:AGL:permission::public:syscall:clock - Without this permission SystemCallFilter=~@clock is set to - forfid call to clock. -- urn:AGL:permission::public:no-htdocs - The http directory served is not "htdocs" but "." -- urn:AGL:permission::public:applications:read - Allows to read data of installed applications (and to - access icons). -- urn:AGL:permission::partner:service:no-ws - Forbids services to provide its API through websocket. -- urn:AGL:permission::partner:service:no-dbus - Forbids services to provide its API through D-Bus. -- urn:AGL:permission::system:run-by-default - Starts automatically the application. Example: home-screen. -- urn:AGL:permission::partner:scope-platform - Install the service at the scope of the platform. -- urn:AGL:permission::system:capability:keep-all - Keep all capabilities for the service. Note that implementing - that permission is not mandatory or can be adapted for the given - system. -- - Permission to use D-Bus. - -[URN]: https://tools.ietf.org/rfc/rfc2141.txt "RFC 2141: URN Syntax" diff --git a/docs/4_APIs_and_Services/4.2_Application_Framework/5_quick-tutorial.md b/docs/4_APIs_and_Services/4.2_Application_Framework/5_quick-tutorial.md deleted file mode 100644 index fb98318..0000000 --- a/docs/4_APIs_and_Services/4.2_Application_Framework/5_quick-tutorial.md +++ /dev/null @@ -1,276 +0,0 @@ ---- -edit_link: '' -title: Quick Tutorial -origin_url: >- - https://git.automotivelinux.org/src/app-framework-main/plain/docs/4-quick-tutorial.md?h=master ---- - - - -# AGL Application Framework: A Quick Tutorial - -## Introduction - -This document proposes a quick tutorial to demonstrate the major -functionalities of the AGL Application Framework. -For more complete information, please refer to the inline documentation -available in the main git repository: - -[https://gerrit.automotivelinux.org/gerrit/#/admin/projects/src/app-framework-main] -[https://gerrit.automotivelinux.org/gerrit/#/admin/projects/src/app-framework-binder] - -For more information on AGL, please visit: -[https://www.automotivelinux.org/] - ----------- - -## Sample applications - -4 sample applications (.wgt files) are prebuilt and available at the following address: -[https://github.com/iotbzh/afm-widget-examples] - -You can get them by cloning this git repository on your desktop (will be useful later in this tutorial): - -```bash -git clone https://github.com/iotbzh/afm-widget-examples -``` - -## Using the CLI tool - -### Setup Environment - -Connect your AGL target board to the network and copy some sample widgets on it through SSH (set BOARDIP with your board IP address) : - -```bash -cd afm-widget-examples -BOARDIP=1.2.3.4 -scp *.wgt root@$BOARDIP:~/ -``` - -Connect through SSH on the target board and check for Application Framework daemons: - -```bash -$ ssh root@$BOARDIP -root@porter:~# ps -ef|grep bin/afm -afm 409 1 0 13:00 ? 00:00:00 /usr/bin/afm-system-daemon -root 505 499 0 13:01 ? 00:00:00 /usr/bin/afm-user-daemon -root 596 550 0 13:22 pts/0 00:00:00 grep afm -``` - -We can see that there are two daemons running: - -* **afm-system-daemon** runs with a system user 'afm' and is responsible for - installing/uninstalling packages -* **afm-user-daemon** runs as a user daemon (currently as root because it's the - only real user on the target board) and is responsible for the whole life - cycle of the applications running inside the user session. - -The application framework has a tool running on the -Command Line Interface (CLI). -Using the **afm-util** command, you can install, uninstall, list, run, pause ... applications. - -To begin, run '**afm-util help**' to get a quick help on commands: - -```bash -root@porter:~# afm-util help -usage: afm-util command [arg] -``` - -The commands are: - -```bash -list -runnables list the runnable widgets installed - -add wgt -install wgt install the wgt file - -remove id -uninstall id remove the installed widget of id - -info id -detail id print detail about the installed widget of id - -ps -runners list the running instance - -run id -start id start an instance of the widget of id - -kill rid -terminate rid terminate the running instance rid - -status rid -state rid get status of the running instance rid -``` - -### Install an application - -You can then install your first application: - -```bash -root@porter:~# afm-util install /home/root/annex.wgt -{ "added": "webapps-annex@0.0" } -``` - -Let's install a second application: - -```bash -root@porter:~# afm-util install /home/root/memory-match.wgt -{ "added": "webapps-memory-match@1.1" } -``` - -Note that usually, **afm-util** will return a **JSON result**, which is the common format for messages returned by the Application Framework daemons. - -### List installed applications - -You can then list all installed applications: - -```bash -root@porter:~# afm-util list -[ { "id": "webapps-annex@0.0", "version": "0.0.10", "width": 0, "height": 0, "name": "Annex", "description": "Reversi\/Othello", "shortname": "", "author": "Todd Brandt " }, -{ "id": "webapps-memory-match@1.1", "version": "1.1.7", "width": 0, "height": 0, "name": "MemoryMatch", "description": "Memory match", "shortname": "", "author": "Todd Brandt " } ] -``` - -Here, we can see the two previously installed applications. - -### Get information about an application - -Let's get some details about the first application: - -```bash -root@porter:~# afm-util info webapps-annex@0.0 -{ "id": "webapps-annex@0.0", "version": "0.0.10", "width": 0, "height": 0, "name": "Annex", "description": "Reversi\/Othello", "shortname": "", "author": "Todd Brandt " } -``` - -Note: that AGL applications are mostly handled by afm-util through their IDs. -In our example, the application ID is 'webapps-annex@0.0'. - -### Start application - -Let's start the first application Annex: - -```bash -root@porter:~# afm-util start webapps-annex@0.0 -1 -``` - -As the application is a HTML5 game, you should then get a webview running with QML on the board display. - -### Security Context - -The application has been started in the user session, with a dedicated security context, enforced by SMACK. -To illustrate this, we can take a look at the running processes and their respective SMACK labels: - -```bash -root@porter:~# ps -efZ |grep webapps-annex | grep -v grep -User::App::webapps-annex root 716 491 0 13:19 ? 00:00:00 /usr/bin/afb-daemon --mode=local --readyfd=8 --alias=/icons /usr/share/afm/icons --port=12348 --rootdir=/usr/share/afm/applications/webapps-annex/0.0 --token=7D6D2F16 --sessiondir=/home/root/app-data/webapps-annex/.afb-daemon -User::App::webapps-annex root 717 491 0 13:19 ? 00:00:00 /usr/bin/qt5/qmlscene http://localhost:12348/index.html?token=7D6D2F16 /usr/bin/web-runtime-webkit.qml -``` - -In the previous result, we see that the application is composed of two processes: - -* the application binder (afb-daemon) -* the application UI (qmlscene ...) - -While most system processes run with the label 'System', we see that the -application runs with a specific SMACK label 'User::App::webapps-annex': this -label is used to force the application to follow -a Mandatory Access Control (MAC) scheme. -This means that those processes run in their own security context, -isolated from the rest of the system (and other applications). -Global security rules can then be applied to restrict access -to all other user or system resources. - -### Check running applications - -To check for running applications, just run: - -```bash -root@porter:~# afm-util ps -[ { "runid": 1, "state": "running", "id": "webapps-annex@0.0" } ] -``` - -The 'runid' is the application instance ID and is used as an argument for the -subcommands controlling the application runtime state (kill/pause/resume/status) - -### Uninstall application - -To uninstall an application, simply use its ID: - -```bash -root@porter:~# afm-util uninstall webapps-annex@0.0 -true -``` - -Then list the installed apps to confirm the removal: - -```bash -root@porter:~# afm-util list -[ { "id": "webapps-memory-match@1.1", "version": "1.1.7", "width": 0, "height": 0, "name": "MemoryMatch", "description": "Memory match", "shortname": "", "author": "Todd Brandt " } ] -``` - -## afm-client: a sample HTML5 'Homescreen' - -**afm-client** is a HTML5 UI that allows to install/uninstall applications as well as starting/pausing them as already demonstrated with afm-util. - -The HTML5 UI is accessible remotely through this URL: - - -### Installing an application - -By clicking on the '**Upload**' button on the right, -you can send an application package (WGT file) and install it. -Select for example the file '**rabbit.wgt**' that was cloned initially - from the git repository afm-widget-examples. - -Then a popup requester ask for a confirmation: -'Upload Application rabbit.wgt ?'. Click on the '**Install**' button. - -You should then see some changes in the toolbar: -a new icon appeared, representing the freshly installed application. - -### Running an application - -In the toolbar, click on the button representing the Rabbit application. -You'll get a popup asking to: - -* start the application -* or get some info about it -* or uninstall it - -Click on the 'start' item: the application starts and should be visible - as a webview on the target board display. -Note that at this point, we could also run the application remotely, -that is in the same browser as the Homescreen app. -By default, the application framework is configured -to run applications 'locally' on the board display. - -### Uninstalling an application - -From the same popup menu, you can select 'uninstall' -to remove the application from the system. -As a consequence, the application icon should disappear from the toolbar. - -## afb-client: a template for Angular Applications - -Another package '**afb-client**' is also available for testing. -This is a sample HTML5 application demonstrating various basic -capabilities of the Binder daemon. -It can be used by developers as a template to start writing real AGL Applications. - -This application is not available as WGT file yet and it should be started manually without any specific security context: - -```bash -root@porter:~# /usr/bin/afb-daemon --port=1235 --token='' --sessiondir=/home/root/.afm-daemon --rootdir=/usr/share/agl/afb-client --alias=/icons:/usr/share/afm/icons -``` - -Then you can access it from a browser: - - -afb-client is a simple application to demonstrate the built-in capabilities of the binder daemon (handling sessions and security tokens, testing POSTs uploads...) and was used during the application framework development to validate the proposed features. - -[https://github.com/iotbzh/afm-widget-examples]: https://github.com/iotbzh/afm-widget-examples -[https://www.automotivelinux.org/]: https://www.automotivelinux.org/ -[https://gerrit.automotivelinux.org/gerrit/#/admin/projects/src/app-framework-binder]: https://gerrit.automotivelinux.org/gerrit/#/admin/projects/src/app-framework-binder -[https://gerrit.automotivelinux.org/gerrit/#/admin/projects/src/app-framework-main]: https://gerrit.automotivelinux.org/gerrit/#/admin/projects/src/app-framework-main diff --git a/docs/4_APIs_and_Services/4.2_Application_Framework/pictures/AppFW-APP_install_sequences.svg b/docs/4_APIs_and_Services/4.2_Application_Framework/pictures/AppFW-APP_install_sequences.svg deleted file mode 100644 index fab8399..0000000 --- a/docs/4_APIs_and_Services/4.2_Application_Framework/pictures/AppFW-APP_install_sequences.svg +++ /dev/null @@ -1,408 +0,0 @@ - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - System - - - - - - - - - - - - - - - User - - - - - - - - - - - D-Bus session - - - - - - - - - - SMACK isolatedother application - - - - - - - - - - SECURITY MANAGER - - - - - - - - - - afm-system-daemon - - - - - - - - - - CYNARA - - - - - - - - - - D-Bus system - - - - - - - - - - afm-user-daemon - - - - - - - - - - SMACK isolated Application - - - - - - - - - - - - - - - - - Application UI - - - - - - - - - - - binder afb-daemon - - - - - - - - - - afm-main-binding - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - (1), (7) - - - - - - (2) - - - - - - (3) - - - - - - (4) - - - - - - (5) - - - - - - (6) - - - - - - (9) - - - - - - (11) - - - - - - (12) - - - - - - (10) - - - - - - (13) - - - - - - (8) - - - - - - - diff --git a/docs/4_APIs_and_Services/4.2_Application_Framework/pictures/Security_model_history.svg b/docs/4_APIs_and_Services/4.2_Application_Framework/pictures/Security_model_history.svg deleted file mode 100644 index 7935437..0000000 --- a/docs/4_APIs_and_Services/4.2_Application_Framework/pictures/Security_model_history.svg +++ /dev/null @@ -1,149 +0,0 @@ - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - Tizen OBS - - - - - - Tizen Yocto - - - - - - meta-intel-iot-security - - - - - - 2014 - - - - - - 2015 - - - - - - - \ No newline at end of file diff --git a/docs/4_APIs_and_Services/4.2_Application_Framework/pictures/afm-daemons.svg b/docs/4_APIs_and_Services/4.2_Application_Framework/pictures/afm-daemons.svg deleted file mode 100644 index 02b2c92..0000000 --- a/docs/4_APIs_and_Services/4.2_Application_Framework/pictures/afm-daemons.svg +++ /dev/null @@ -1,237 +0,0 @@ - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - System - - - - - - - - - - - - - - - User - - - - - - - - - - - D-Bus session - - - - - - - - - - SMACK isolatedApplication - - - - - - - - - - SECURITY MANAGER - - - - - - - - - - afm-system-daemon - - - - - - - - - - CYNARA - - - - - - - - - - D-Bus system - - - - - - - - - - afm-user-daemon - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - \ No newline at end of file diff --git a/docs/4_APIs_and_Services/4.2_Application_Framework/pictures/make-units.svg b/docs/4_APIs_and_Services/4.2_Application_Framework/pictures/make-units.svg deleted file mode 100644 index d52a8c7..0000000 --- a/docs/4_APIs_and_Services/4.2_Application_Framework/pictures/make-units.svg +++ /dev/null @@ -1,436 +0,0 @@ - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - <number> - - - - - - - - - - - - - - config.xml - - - - - - - /etc/afm/afm-unit.conf - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - json description - - - - - - - - - Mustache engine - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - units description - - - - - - - *.service - - - - - - - *.socket - - - - - - virtualdata - - - - - - - - - - - - - - - - - - - - - - - Unit installer - - - - - - - - - Config engine - - - - - - - ... - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - configurationfile - - - - - - systemdunits - - - - - - - \ No newline at end of file diff --git a/docs/4_APIs_and_Services/4.3_Application_Framework_Binder/0_Overview/0_Overview.md b/docs/4_APIs_and_Services/4.3_Application_Framework_Binder/0_Overview/0_Overview.md deleted file mode 100644 index f265558..0000000 --- a/docs/4_APIs_and_Services/4.3_Application_Framework_Binder/0_Overview/0_Overview.md +++ /dev/null @@ -1,100 +0,0 @@ ---- -edit_link: '' -title: Overview -origin_url: >- - https://git.automotivelinux.org/src/app-framework-binder/plain/docs/afb-overview.md?h=master ---- - - - -# Binder Overview - -The ***binder*** provides the way to connect applications to -the services that it needs. - -It provides a fast way to securely offer APIs to applications -written in any language and running almost anywhere. - -- The ***binder*** is developed for AGL (Automotive Grade Linux) but it is not bound to AGL. -- The ***binder*** is the usual name. -- The binary is named **afb-daemon**. -- The name **afb-daemon** stands for ***Application Framework Binder Daemon***. - -The word *daemon*, here, denote the fact that the ***binder*** makes witchcraft to -connect applications to their expected services. (note: that usually the term of -daemon denotes background process but not here). - -Each ***binder*** **afb-daemon** is in charge to bind one instance of -an application or service to the rest of the system, applications and services. -Within AGL, the connection between services and/or applications -is tuned by the AGL framework and the AGL system. - -## The basis of the binder - -The following figure shows main concepts linked to the ***binder***. - - -![Figure: binder basis](pictures/basis.svg) - -The shown elements are: - -- The SECURITY CONTEXT - - The primary intention of any ***binder*** is to provide - a secured environment for any application. - On AGL, the **security context** is ensured by [Smack] - , the security context of the application or service. - -- The BINDER - - This is the central element. - It makes possible to run HTML5 applications and provides - the unified access to APIs provided by the ***bindings***. - - Running a pure HTML5 application doesn't require any ***binding***. - In that case , the ***binder*** acts as a simple HTTP server for - the web runtime. - -- The BINDINGs - - A ***binding*** adds one **API** to the ***binder***. - - An **API** is a set of **verbs** that can be called - using either REST over HTTP or a kind of JSON RPC. - - ***bindings*** are either: - - - dynamically loaded libraries in the ***binder*** process - - remote service running on the same host - - remote service running on other hosts - - When acting as an HTTP server, the binder treats the language - settings of the HTTP requests to provide internationalized - content as specified by - [widget specifications](https://www.w3.org/TR/widgets/#internationalization-and-localization). -- The APPLICATION - - An ***application*** connects to the binder to get access to - the **API** that it provides or to get its HTTP services to access - resources. - - - -## Interconnection of binders - -The AGL framework interprets the **widget/application** manifests -to setup the ***bindings*** configuration of the ***binders***. - -The figure below shows that ***binders*** are interconnected. - - -![Figure: binder interconnection](pictures/interconnection.svg) - -The figure shows 4 several **application/service**: **A**, **B**, -**C** and **D**. - -The application **A** might use an **API** that is shown as a -local ***binding*** but that in reality runs within the context -of **D**. - -The framework AGL takes care of making the plumbing working. diff --git a/docs/4_APIs_and_Services/4.3_Application_Framework_Binder/1_Binder_daemon_vocabulary/1_Binder_daemon_vocabulary.md b/docs/4_APIs_and_Services/4.3_Application_Framework_Binder/1_Binder_daemon_vocabulary/1_Binder_daemon_vocabulary.md deleted file mode 100644 index 6c93add..0000000 --- a/docs/4_APIs_and_Services/4.3_Application_Framework_Binder/1_Binder_daemon_vocabulary/1_Binder_daemon_vocabulary.md +++ /dev/null @@ -1,111 +0,0 @@ ---- -edit_link: '' -title: Binder daemon vocabulary -origin_url: >- - https://git.automotivelinux.org/src/app-framework-binder/plain/docs/afb-daemon-vocabulary.md?h=master ---- - - - -# Vocabulary for AFB-DAEMON - -## Binding - -A shared library object intended to add a functionality to an afb-daemon -instance. -It implements an API and may provide a service. - -Binding made for services can have specific entry points called after -initialization and before serving. - -## Event - -Messages with data propagated from the services to the client and not expecting -any reply. - -The current implementation allows to widely broadcast events to all clients. - -## Level of assurance (LOA) - -This level that can be from 0 to 3 represent the level of -assurance that the services can expect from the session. - -The exact definition of the meaning of these levels and how to use it remains to -be achieved. - -## Request - -A request is an invocation by a client to a binding method using a message -transferred through some protocol: - -- HTTP -- WebSocket -- ... - -and served by ***afb-daemon*** - -## Reply/Response - -This is a message sent to client as the result of the request. - -## Service - -Service are made of bindings running on a binder -The binder is in charge of connecting services and applications. -A service can serve many clients. - -The framework establishes connection between the services and the clients. -Using sockets currently but other protocols are considered. - -The term of service is tightly bound to the notion of API. - -## Session - -A session is meant to be the unique instance context of a client, -which identify that instance across requests. - -Each session has an identifier. -Session identifier generated by afb-daemon are UUIDs. -A client can present its own session id. - -Internally, afb-daemon offers a mechanism to attach data to sessions. -When a session is closed or disappears, data attached to that session -are freed. - -## Token - -The token is an identifier that the client must give to be authenticated. - -At start, afb-daemon get an initial token. -This initial token must be presented by incoming client to be authenticated. - -A token is valid only for a period. - -The token must be renewed periodically. -When the token is renewed, afb-daemon sends the new token to the client. - -Tokens generated by afb-daemon are UUIDs. - -## UUID - -It stand for Universal Unique IDentifier. - -It is designed to create identifier in a way that avoid has much as possible -conflicts. -It means that if two different instances create an UUID, the -probability that they create the same UUID is very low, near to zero. - -## x-afb-reqid - -Argument name that can be used with HTTP request. -When this argument is given, it is automatically added to the "request" object of the answer. - -## x-afb-token - -Argument name meant to give the token without ambiguity. -You can also use the name **token** but it may conflicts with others arguments. - -## x-afb-uuid - -Argument name for giving explicitly the session identifier without ambiguity. -You can also use the name **uuid** but it may conflicts with others arguments. diff --git a/docs/4_APIs_and_Services/4.3_Application_Framework_Binder/2_How_to_write_a_binding/2_How_to_write_a_binding.md b/docs/4_APIs_and_Services/4.3_Application_Framework_Binder/2_How_to_write_a_binding/2_How_to_write_a_binding.md deleted file mode 100644 index fd54151..0000000 --- a/docs/4_APIs_and_Services/4.3_Application_Framework_Binder/2_How_to_write_a_binding/2_How_to_write_a_binding.md +++ /dev/null @@ -1,451 +0,0 @@ ---- -edit_link: '' -title: How to write a binding ? -origin_url: >- - https://git.automotivelinux.org/src/app-framework-binder/plain/docs/afb-binding-writing.md?h=master ---- - - - -# Overview of the bindings - -The ***binder*** serves files through HTTP protocol and offers developers the capability to offer application API methods through HTTP or -WebSocket protocol. - -The ***bindings*** are used to add **API** to ***binders***. -This part describes how to write a ***binding*** for ***binder*** -or in other words how to add a new **API** to the system. - -This section target developers. - -This section shortly explain how to write a binding -using the C programming language. - -It is convenient to install the ***binder*** on the -desktop used for writing the binding. -It allows for easy debug and test. - -## Nature of a binding - -A ***binding*** is an independent piece of software compiled as a shared -library and dynamically loaded by a ***binder***. -It is intended to provide one **API** (**A**pplication **P**rogramming -**I**nterface). - -The **API** is designated and accessed through its name. -It contains several **verbs** that implement the ***binding*** -functionalities. -Each of these **verbs** is a **method** that -processes requests of applications and sends results. - -The ***binding***'s methods are invoked by HTTP or websocket -requests. - -The **methods** of the ***bindings*** are noted **api/verb** -where **api** is the **API** name of the binding and **verb** is -the **method**'s name within the **API**. -This notation comes from HTTP invocations that rely on URL path terminated -with **api/verb**. - -The name of an **API** can be made of any characters except: - -- the control characters (\u0000 .. \u001f) -- the characters of the set { ' ', '"', '#', '%', '&', - '\'', '/', '?', '`', '\x7f' } - -The names of the **verbs** can be any character. - -The binder makes no distinctions between upper case and lower case -latin letters. -So **API/VERB** matches **Api/Verb** or **api/verb**. - -## Versions of the bindings - -Since introduction of the binder, the way how bindings are written -evolved a little. While changing, attention was made to ensure binary -compatibility between the different versions. - -Actually it exists 3 ways of writing ***bindings***. -You can either write: - -- a binding version 1 (not more supported); -- a binding version 2 (not recommended); -- a binding version 3 (RECOMMENDED). - -A ***binder*** loads and runs any of these version in any combination. -This document explain how to write bindings version 3. - - - -## Sample binding: tuto-1 - -This is the code of the binding **tuto-1.c**: - -```C - 1 #define AFB_BINDING_VERSION 3 - 2 #include - 3 - 4 void hello(afb_req_t req) - 5 { - 6 AFB_REQ_DEBUG(req, "hello world"); - 7 afb_req_reply(req, NULL, NULL, "hello world"); - 8 } - 9 - 10 const afb_verb_t verbs[] = { - 11 { .verb="hello", .callback=hello }, - 12 { .verb=NULL } - 13 }; - 14 - 15 const afb_binding_t afbBindingExport = { - 16 .api = "tuto-1", - 17 .verbs = verbs - 18 }; -``` - -Compiling: - -```bash -gcc -fPIC -shared tuto-1.c -o tuto-1.so $(pkg-config --cflags-only-I afb-daemon) -``` - -> Note: the variable environment variable PKG_CONFIG_PATH might be necessary -> tuned to get **pkg-config** working properly - -Running: - -```bash -afb-daemon --binding ./tuto-1.so --port 3333 --token '' -``` - -At this point, afb-daemon has started, it loaded the binding tuto-1.so and now -listen at localhost on the port 3333. - -Testing using **curl**: - -```bash -$ curl http://localhost:3333/api/tuto-1/hello -{"jtype":"afb-reply","request":{"status":"success","info":"hello world","uuid":"1e587b54-900b-49ab-9940-46141bc2e1d6"}} -``` - -Testing using **afb-client-demo** (with option -H for -getting a human readable output): - -```bash -$ afb-client-demo -H ws://localhost:3333/api?token=x tuto-1 hello -ON-REPLY 1:tuto-1/hello: OK -{ - "jtype":"afb-reply", - "request":{ - "status":"success", - "info":"hello world", - "uuid":"03a84ad1-458a-4ace-af74-b1da917391b9" - } -} -``` - -This shows basic things: - -- The include to get for creating a binding -- How to declare the API offered by the binding -- How to handle requests made to the binding - -### Getting declarations for the binding - -The lines 1 and 2 show how to get the include file **afb-binding.h**. - -```C - 1 #define AFB_BINDING_VERSION 3 - 2 #include -``` - -You must define the version of ***binding*** that you are using. -This is done line 1 where we define that this is the version 3 (earlier -versions 1 and 2 are deprecated). - -If you don't define it, an error is reported and the compilation aborts. - -To include **afb-binding.h** successfully, the include search path -should be set correctly if needed (not needed only if installed in -/usr/include/afb directory that is the default). - -Setting the include path is easy using **pkg-config**: - -```bash -pkg-config --cflags-only-I afb-daemon -``` - -> Note for **C++** developers: -> -> The ***binder*** currently expose a draft version of **C++** api. -> To get it include the file <**afb/afb-binding**> (without **.h**). - - -### Declaring the API of the binding - -Lines 10 to 18 show the declaration of the ***binding***. - -The ***binder*** knows that this is a ***binding*** because -it finds the exported symbol **afbBindingExport** that is expected to be -a structure of type **afb_binding_t**. - -```C - 10 const afb_verb_t verbs[] = { - 11 { .verb="hello", .callback=hello }, - 12 { .verb=NULL } - 13 }; - 14 - 15 const afb_binding_t afbBindingExport = { - 16 .api = "tuto-1", - 17 .verbs = verbs - 18 }; -``` - -The structure **afbBindingExport** actually tells that: - -- the exported **API** name is **tuto-1** (line 16) -- the array of verbs is the above defined one - -The exported list of verb is specified by an array of structures of -type **afb_verb_t**, each describing a verb, ended with a verb NULL (line 12). - -The only defined verb here (line 11) is named **hello** (field **.verb**) -and the function that handle the related request is **hello** -(field **.callback**). - -### Handling binder's requests - -As shown above this is by default the common include directory where -the AGL stuff is installed. - -```C - 4 void hello(afb_req_t req) - 5 { - 6 AFB_REQ_DEBUG(req, "hello world"); - 7 afb_req_reply(req, NULL, NULL, "hello world"); - 8 } -``` - -When the ***binder*** receives a request for the verb **hello** of -of the api **tuto-1**, it invoke the callback **hello** of the **binding** -with the argument **req** that handles the client request. - -The callback has to treat synchronously or asynchronously the request and -should at the end emit a reply for the request. - -At the line 7, the callback for **tuto-1/hello** replies to the request **req**. -Parameters of the reply are: - - 1. The first parameter is the replied request - 2. The second parameter is a json object (here NULL) - 3. The third parameter is the error string indication (here NULL: no error) - 4. The fourth parameter is an informative string (that can be NULL) that can be used to provide meta data. - -The 3 last parameters are sent back to the client as the reply content. - - - -## Sample binding: tuto-2 - -The second tutorial shows many important feature that can -commonly be used when writing a ***binding***: - -- initialization, getting arguments, sending replies, pushing events. - -This is the code of the binding **tuto-2.c**: - -```C - 1 #include - 2 #include - 3 - 4 #define AFB_BINDING_VERSION 3 - 5 #include - 6 - 7 afb_event_t event_login, event_logout; - 8 - 9 void login(afb_req_t req) - 10 { - 11 json_object *args, *user, *passwd; - 12 char *usr; - 13 - 14 args = afb_req_json(req); - 15 if (!json_object_object_get_ex(args, "user", &user) - 16 || !json_object_object_get_ex(args, "password", &passwd)) { - 17 AFB_REQ_ERROR(req, "login, bad request: %s", json_object_get_string(args)); - 18 afb_req_reply(req, NULL, "bad-request", NULL); - 19 } else if (afb_req_context_get(req)) { - 20 AFB_REQ_ERROR(req, "login, bad state, logout first"); - 21 afb_req_reply(req, NULL, "bad-state", NULL); - 22 } else if (strcmp(json_object_get_string(passwd), "please")) { - 23 AFB_REQ_ERROR(req, "login, unauthorized: %s", json_object_get_string(args)); - 24 afb_req_reply(req, NULL, "unauthorized", NULL); - 25 } else { - 26 usr = strdup(json_object_get_string(user)); - 27 AFB_REQ_NOTICE(req, "login user: %s", usr); - 28 afb_req_session_set_LOA(req, 1); - 29 afb_req_context_set(req, usr, free); - 30 afb_req_reply(req, NULL, NULL, NULL); - 31 afb_event_push(event_login, json_object_new_string(usr)); - 32 } - 33 } - 34 - 35 void action(afb_req_t req) - 36 { - 37 json_object *args, *val; - 38 char *usr; - 39 - 40 args = afb_req_json(req); - 41 usr = afb_req_context_get(req); - 42 AFB_REQ_NOTICE(req, "action for user %s: %s", usr, json_object_get_string(args)); - 43 if (json_object_object_get_ex(args, "subscribe", &val)) { - 44 if (json_object_get_boolean(val)) { - 45 AFB_REQ_NOTICE(req, "user %s subscribes to events", usr); - 46 afb_req_subscribe(req, event_login); - 47 afb_req_subscribe(req, event_logout); - 48 } else { - 49 AFB_REQ_NOTICE(req, "user %s unsubscribes to events", usr); - 50 afb_req_unsubscribe(req, event_login); - 51 afb_req_unsubscribe(req, event_logout); - 52 } - 53 } - 54 afb_req_reply(req, json_object_get(args), NULL, NULL); - 55 } - 56 - 57 void logout(afb_req_t req) - 58 { - 59 char *usr; - 60 - 61 usr = afb_req_context_get(req); - 62 AFB_REQ_NOTICE(req, "login user %s out", usr); - 63 afb_event_push(event_logout, json_object_new_string(usr)); - 64 afb_req_session_set_LOA(req, 0); - 65 afb_req_context_clear(req); - 66 afb_req_reply(req, NULL, NULL, NULL); - 67 } - 68 - 69 int preinit(afb_api_t api) - 70 { - 71 AFB_API_NOTICE(api, "preinit"); - 72 return 0; - 73 } - 74 - 75 int init(afb_api_t api) - 76 { - 77 AFB_API_NOTICE(api, "init"); - 78 event_login = afb_api_make_event(api, "login"); - 79 event_logout = afb_api_make_event(api, "logout"); - 80 if (afb_event_is_valid(event_login) && afb_event_is_valid(event_logout)) - 81 return 0; - 82 AFB_API_ERROR(api, "Can't create events"); - 83 return -1; - 84 } - 85 - 86 const afb_verb_t verbs[] = { - 87 { .verb="login", .callback=login }, - 88 { .verb="action", .callback=action, .session=AFB_SESSION_LOA_1 }, - 89 { .verb="logout", .callback=logout, .session=AFB_SESSION_LOA_1 }, - 90 { .verb=NULL } - 91 }; - 92 - 93 const afb_binding_t afbBindingExport = { - 94 .api = "tuto-2", - 95 .specification = NULL, - 96 .verbs = verbs, - 97 .preinit = preinit, - 98 .init = init, - 99 .noconcurrency = 0 - 100 }; -``` - -Compiling: - -```bash -gcc -fPIC -shared tuto-2.c -o tuto-2.so $(pkg-config --cflags --libs afb-daemon) -``` - -Running: - -```bash -afb-daemon --binding ./tuto-2.so --port 3333 --token '' -``` - -Testing: - -```bash -$ afb-client-demo -H localhost:3333/api?token=toto -tuto-2 login {"help":true} -ON-REPLY 1:tuto-2/login: ERROR -{ - "jtype":"afb-reply", - "request":{ - "status":"bad-request", - "uuid":"e2b24a13-fc43-487e-a5f4-9266dd1e60a9" - } -} -tuto-2 login {"user":"jose","password":"please"} -ON-REPLY 2:tuto-2/login: OK -{ - "jtype":"afb-reply", - "request":{ - "status":"success" - } -} -tuto-2 login {"user":"jobol","password":"please"} -ON-REPLY 3:tuto-2/login: ERROR -{ - "jtype":"afb-reply", - "request":{ - "status":"bad-state" - } -} -tuto-2 action {"subscribe":true} -ON-REPLY 4:tuto-2/action: OK -{ - "response":{ - "subscribe":true - }, - "jtype":"afb-reply", - "request":{ - "status":"success" - } -} -``` - -In another terminal: - -```bash -$ afb-client-demo -H localhost:3333/api?token=toto -tuto-2 login {"user":"jobol","password":"please"} -ON-REPLY 1:tuto-2/login: OK -{ - "jtype":"afb-reply", - "request":{ - "status":"success", - "uuid":"a09f55ff-0e89-4f4e-8415-c6e0e7f439be" - } -} -tuto-2 logout true -ON-REPLY 2:tuto-2/logout: OK -{ - "jtype":"afb-reply", - "request":{ - "status":"success" - } -} -``` - -It produced in the first terminal: - -```bash -ON-EVENT tuto-2/login: -{ - "event":"tuto-2\/login", - "data":"jobol", - "jtype":"afb-event" -} -ON-EVENT tuto-2/logout: -{ - "event":"tuto-2\/logout", - "data":"jobol", - "jtype":"afb-event" -} -``` diff --git a/docs/4_APIs_and_Services/4.3_Application_Framework_Binder/3_Binder_references/1_Types_and_globals.md b/docs/4_APIs_and_Services/4.3_Application_Framework_Binder/3_Binder_references/1_Types_and_globals.md deleted file mode 100644 index bec8fea..0000000 --- a/docs/4_APIs_and_Services/4.3_Application_Framework_Binder/3_Binder_references/1_Types_and_globals.md +++ /dev/null @@ -1,252 +0,0 @@ ---- -edit_link: '' -title: Types and globals -origin_url: >- - https://git.automotivelinux.org/src/app-framework-binder/plain/docs/reference-v3/types-and-globals.md?h=master ---- - - - -# Types and globals - -## The global afbBindingRoot - -The global **afbBindingRoot** of type **afb_api_t** is always implicitly -defined for bindings of version 3 or upper. It records the root api of -the binding. - -When the binding has a defined **afbBindingExport**, the root api -**afbBindingRoot** is the **afb_pi_t** relative to the api created for -this static description. - -When the binding has no defined **afbBindingExport**, the root api is -a virtual api representing the shared object of the binding. In that case -the name of the api is the path of the shared object. Its use is restricted -but allows log messages. - -## The global afbBindingExport - -The global **afbBindingExport** is not mandatory. - -If **afbBindingExport** is defined and exported, it must be of the type -**const afb_binding_t** and must describe the *root* api of the binding. - -## The type afb_api_t - -Bindings now can declare more than one api. The counter part is that -a new handle is needed to manage apis. These handles are of the type -**afb_api_t**. - -It is defined as below. - -```C -typedef struct afb_api_x3 afb_api_t; -``` - -## The type afb_binding_t - -The main structure, of type **afb_binding_t**, for describing the binding -must be exported under the name **afbBindingExport**. - -This structure is defined as below. - -```C -typedef struct afb_binding_v3 afb_binding_t; -``` - -Where: - -```C -/** - * Description of the bindings of type version 3 - */ -struct afb_binding_v3 -{ - /** api name for the binding, can't be NULL */ - const char *api; - - /** textual specification of the binding, can be NULL */ - const char *specification; - - /** some info about the api, can be NULL */ - const char *info; - - /** array of descriptions of verbs terminated by a NULL name, can be NULL */ - const struct afb_verb_v3 *verbs; - - /** callback at load of the binding */ - int (*preinit)(struct afb_api_x3 *api); - - /** callback for starting the service */ - int (*init)(struct afb_api_x3 *api); - - /** callback for handling events */ - void (*onevent)(struct afb_api_x3 *api, const char *event, struct json_object *object); - - /** userdata for afb_api_x3 */ - void *userdata; - - /** space separated list of provided class(es) */ - const char *provide_class; - - /** space separated list of required class(es) */ - const char *require_class; - - /** space separated list of required API(es) */ - const char *require_api; - - /** avoids concurrent requests to verbs */ - unsigned noconcurrency: 1; -}; -``` - -## The type afb_verb_t - -Each verb is described with a structure of type **afb_verb_t** -defined below: - -```C -typedef struct afb_verb_v3 afb_verb_t; -``` - -```C -/** - * Description of one verb as provided for binding API version 3 - */ -struct afb_verb_v3 -{ - /** name of the verb, NULL only at end of the array */ - const char *verb; - - /** callback function implementing the verb */ - void (*callback)(afb_req_t_x2 *req); - - /** required authorization, can be NULL */ - const struct afb_auth *auth; - - /** some info about the verb, can be NULL */ - const char *info; - - /**< data for the verb callback */ - void *vcbdata; - - /** authorization and session requirements of the verb */ - uint16_t session; - - /** is the verb glob name */ - uint16_t glob: 1; -}; -``` - -The **session** flags is one of the constant defined below: - -| Name | Description -|:----------------------:|------------------------------------------------------ -| AFB_SESSION_NONE | no flag, synonym to 0 -| AFB_SESSION_LOA_0 | Requires the LOA to be 0 or more, synonym to 0 or AFB_SESSION_NONE -| AFB_SESSION_LOA_1 | Requires the LOA to be 1 or more -| AFB_SESSION_LOA_2 | Requires the LOA to be 2 or more -| AFB_SESSION_LOA_3 | Requires the LOA to be 3 or more -| AFB_SESSION_CHECK | Requires the token to be set and valid -| AFB_SESSION_REFRESH | Implies a token refresh -| AFB_SESSION_CLOSE | Implies closing the session after request processed - -The LOA (Level Of Assurance) is set, by binding api, using the function **afb_req_session_set_LOA**. - -The session can be closed, by binding api, using the function **afb_req_session_close**. - -## The types afb_auth_t and afb_auth_type_t - -The structure **afb_auth_t** is used within verb description to -set security requirements. -The interpretation of the structure depends on the value of the field **type**. - -```C -typedef struct afb_auth afb_auth_t; - -/** - * Definition of an authorization entry - */ -struct afb_auth -{ - /** type of entry @see afb_auth_type */ - enum afb_auth_type type; - - union { - /** text when @ref type == @ref afb_auth_Permission */ - const char *text; - - /** level of assurancy when @ref type == @ref afb_auth_LOA */ - unsigned loa; - - /** first child when @ref type in { @ref afb_auth_Or, @ref afb_auth_And, @ref afb_auth_Not } */ - const struct afb_auth *first; - }; - - /** second child when @ref type in { @ref afb_auth_Or, @ref afb_auth_And } */ - const struct afb_auth *next; -}; - -``` - -The possible values for **type** is defined here: - -```C -typedef enum afb_auth_type afb_auth_type_t; - -/** - * Enumeration for authority (Session/Token/Assurance) definitions. - * - * @see afb_auth - */ -enum afb_auth_type -{ - /** never authorized, no data */ - afb_auth_No = 0, - - /** authorized if token valid, no data */ - afb_auth_Token, - - /** authorized if LOA greater than or equal to data 'loa' */ - afb_auth_LOA, - - /** authorized if permission 'text' is granted */ - afb_auth_Permission, - - /** authorized if 'first' or 'next' is authorized */ - afb_auth_Or, - - /** authorized if 'first' and 'next' are authorized */ - afb_auth_And, - - /** authorized if 'first' is not authorized */ - afb_auth_Not, - - /** always authorized, no data */ - afb_auth_Yes -}; -``` - -Example: - -```C -static const afb_auth_t myauth[] = { - { .type = afb_auth_Permission, .text = "urn:AGL:permission:me:public:set" }, - { .type = afb_auth_Permission, .text = "urn:AGL:permission:me:public:get" }, - { .type = afb_auth_Or, .first = &myauth[1], .next = &myauth[0] } -}; -``` - - -## The type afb_req_subcall_flags_t - -This is an enumeration that defines bit's positions for setting behaviour -of subcalls. - -| flag | value | description -|----------------------------|-------|-------------- -| afb_req_subcall_catch_events | 1 | the calling API wants to receive the events from subscription -| afb_req_subcall_pass_events | 2 | the original request will receive the events from subscription -| afb_req_subcall_on_behalf | 4 | the calling API wants to use the credentials of the original request -| afb_req_subcall_api_session | 8 | the calling API wants to use its session instead of the one of the original request - diff --git a/docs/4_APIs_and_Services/4.3_Application_Framework_Binder/3_Binder_references/2_Macros_for-logging.md b/docs/4_APIs_and_Services/4.3_Application_Framework_Binder/3_Binder_references/2_Macros_for-logging.md deleted file mode 100644 index 07e1a4a..0000000 --- a/docs/4_APIs_and_Services/4.3_Application_Framework_Binder/3_Binder_references/2_Macros_for-logging.md +++ /dev/null @@ -1,62 +0,0 @@ ---- -edit_link: '' -title: Macros for logging -origin_url: >- - https://git.automotivelinux.org/src/app-framework-binder/plain/docs/reference-v3/macro-log.md?h=master ---- - - - -Macro for logging -================= - -The final behaviour of macros can be tuned using 2 defines that must be defined -before including ****. - -| define | action -|---------------------------------------|-------------------- -| AFB_BINDING_PRAGMA_NO_VERBOSE_DATA | show file and line, remove function and text message -| AFB_BINDING_PRAGMA_NO_VERBOSE_DETAILS | show text, remove function, line and file - -## Logging for an api - -The following macros must be used for logging for an **api** of type -**afb_api_t**. - -```C -AFB_API_ERROR(api,fmt,...) -AFB_API_WARNING(api,fmt,...) -AFB_API_NOTICE(api,fmt,...) -AFB_API_INFO(api,fmt,...) -AFB_API_DEBUG(api,fmt,...) -``` - -## Logging for a request - - -The following macros can be used for logging in the context -of a request **req** of type **afb_req_t**: - -```C -AFB_REQ_ERROR(req,fmt,...) -AFB_REQ_WARNING(req,fmt,...) -AFB_REQ_NOTICE(req,fmt,...) -AFB_REQ_INFO(req,fmt,...) -AFB_REQ_DEBUG(req,fmt,...) -``` - -By default, the logging macros add file, line and function -indication. - -## Logging legacy - -The following macros are provided for legacy. - -```C -AFB_ERROR(fmt,...) -AFB_WARNING(fmt,...) -AFB_NOTICE(fmt,...) -AFB_INFO(fmt,...) -AFB_DEBUG(fmt,...) -``` - diff --git a/docs/4_APIs_and_Services/4.3_Application_Framework_Binder/3_Binder_references/3_Functions_of_class_afb_api.md b/docs/4_APIs_and_Services/4.3_Application_Framework_Binder/3_Binder_references/3_Functions_of_class_afb_api.md deleted file mode 100644 index 0699fc0..0000000 --- a/docs/4_APIs_and_Services/4.3_Application_Framework_Binder/3_Binder_references/3_Functions_of_class_afb_api.md +++ /dev/null @@ -1,970 +0,0 @@ ---- -edit_link: '' -title: Functions of class afb_api -origin_url: >- - https://git.automotivelinux.org/src/app-framework-binder/plain/docs/reference-v3/func-api.md?h=master ---- - - - -Functions of class **afb_api** -============================ - -## General functions - -### afb_api_name - -```C -/** - * Get the name of the 'api'. - * - * @param api the api whose name is to be returned - * - * @return the name of the api. - * - * The returned value must not be changed nor freed. - */ -const char *afb_api_name( - afb_api_t api); -``` - -### afb_api_get_userdata - -```C -/** - * Get the "userdata" pointer of the 'api' - * - * @param api the api whose user's data is to be returned - * - * @return the user's data pointer of the api. - * - * @see afb_api_set_userdata - */ -void *afb_api_get_userdata( - afb_api_t api); -``` - -### afb_api_set_userdata - -```C -/** - * Set the "userdata" pointer of the 'api' to 'value' - * - * @param api the api whose user's data is to be set - * @param value the data to set - * - * @see afb_api_get_userdata - */ -void afb_api_set_userdata( - afb_api_t api, - void *value); -``` - -### afb_api_require_api - -```C -/** - * Check that it requires the API of 'name'. - * If 'initialized' is not zero it requests the API to be - * initialized, implying its initialization if needed. - * - * Calling this function is only allowed within init. - * - * A single request allows to require multiple apis. - * - * @param api the api that requires the other api by its name - * @param name a space separated list of required api names - * @param initialized if zero, the api is just required to exist. If not zero, - * the api is required to exist and to be initialized at return of the call - * (initializing it if needed and possible as a side effect of the call). - * - * @return 0 in case of success or -1 in case of error with errno set appropriately. - */ -int afb_api_require_api( - afb_api_t api, - const char *name, - int initialized); -``` - - -## Verbosity functions - -### afb_api_wants_log_level - -```C -/** - * Is the log message of 'level (as defined for syslog) required for the api? - * - * @param api the api to check - * @param level the level to check as defined for syslog: - * - * EMERGENCY 0 System is unusable - * ALERT 1 Action must be taken immediately - * CRITICAL 2 Critical conditions - * ERROR 3 Error conditions - * WARNING 4 Warning conditions - * NOTICE 5 Normal but significant condition - * INFO 6 Informational - * DEBUG 7 Debug-level messages - * - * @return 0 if not required or a value not null if required - * - * @see syslog - */ -int afb_api_wants_log_level( - afb_api_t api, - int level); -``` - -### afb_api_vverbose - -```C -/** - * Send to the journal with the logging 'level' a message described - * by 'fmt' applied to the va-list 'args'. - * - * 'file', 'line' and 'func' are indicators of code position in source files - * (see macros __FILE__, __LINE__ and __func__). - * - * 'level' is defined by syslog standard: - * - * EMERGENCY 0 System is unusable - * ALERT 1 Action must be taken immediately - * CRITICAL 2 Critical conditions - * ERROR 3 Error conditions - * WARNING 4 Warning conditions - * NOTICE 5 Normal but significant condition - * INFO 6 Informational - * DEBUG 7 Debug-level messages - * - * @param api the api that collects the logging message - * @param level the level of the message - * @param file the source file that logs the messages or NULL - * @param line the line in the source file that logs the message - * @param func the name of the function in the source file that logs - * @param fmt the format of the message as in printf - * @param args the arguments to the format string of the message as a va_list - * - * @see syslog - * @see printf - */ -void afb_api_vverbose( - afb_api_t api, - int level, - const char *file, - int line, - const char *func, - const char *fmt, - va_list args); -``` - -### afb_api_verbose - -```C -/** - * Send to the journal with the log 'level' a message described - * by 'fmt' and following parameters. - * - * 'file', 'line' and 'func' are indicators of position of the code in source files - * (see macros __FILE__, __LINE__ and __func__). - * - * 'level' is defined by syslog standard: - * EMERGENCY 0 System is unusable - * ALERT 1 Action must be taken immediately - * CRITICAL 2 Critical conditions - * ERROR 3 Error conditions - * WARNING 4 Warning conditions - * NOTICE 5 Normal but significant condition - * INFO 6 Informational - * DEBUG 7 Debug-level messages - * - * @param api the api that collects the logging message - * @param level the level of the message - * @param file the source file that logs the messages or NULL - * @param line the line in the source file that logs the message - * @param func the name of the function in the source file that logs - * @param fmt the format of the message as in printf - * @param ... the arguments to the format string of the message - * - * @see syslog - * @see printf - */ -void afb_api_verbose( - afb_api_t api, - int level, - const char *file, - int line, - const char *func, - const char *fmt, - ...); -``` - -## Data retrieval functions - -### afb_api_rootdir_get_fd - -```C -/** - * Get the root directory file descriptor. This file descriptor can - * be used with functions 'openat', 'fstatat', ... - * - * CAUTION, manipulate this descriptor with care, in particular, don't close - * it. - * - * This can be used to get the path of the root directory using: - * - * char buffer[MAX_PATH], proc[100]; - * int dirfd = afb_api_rootdir_get_fd(api); - * snprintf(proc, sizeof proc, "/proc/self/fd/%d", dirfd); - * readlink(proc, buffer, sizeof buffer); - * - * But note that within AGL this is the value given by the environment variable - * AFM_APP_INSTALL_DIR. - * - * @param api the api that uses the directory file descriptor - * - * @return the file descriptor of the root directory. - * - * @see afb_api_rootdir_open_locale - */ -int afb_api_rootdir_get_fd( - afb_api_t api); -``` - -### afb_api_rootdir_open_locale - -```C -/** - * Opens 'filename' within the root directory with 'flags' (see function openat) - * using the 'locale' definition (example: "jp,en-US") that can be NULL. - * - * The filename must be relative to the root of the bindings. - * - * The opening mode must be for read or write but not for O_CREAT. - * - * The definition of locales and of how files are searched can be checked - * here: https://www.w3.org/TR/widgets/#folder-based-localization - * and https://tools.ietf.org/html/rfc7231#section-5.3.5 - * - * @param api the api that queries the file - * @param filename the relative path to the file to open - * @param flags the flags for opening as for C function 'open' - * @param locale string indicating how to search content, can be NULL - * - * @return the file descriptor or -1 in case of error and errno is set with the - * error indication. - * - * @see open - * @see afb_api_rootdir_get_fd - */ -int afb_api_rootdir_open_locale( - afb_api_t api, - const char *filename, - int flags, - const char *locale); -``` - -### afb_api_settings - -```C -/** - * Settings of the api. - * - * Get the settings of the API. The settings are recorded - * as a JSON object. The returned object should not be modified. - * It MUST NOT be released using json_object_put. - * - * @param api the api whose settings are required - * - * @returns The setting object. - */ -struct json_object *afb_api_settings( - struct afb_api_x3 *api); -``` - -## Calls and job functions - -### afb_api_call - -```C -/** - * Calls the 'verb' of the 'apiname' with the arguments 'args' and 'verb' in the name of the binding 'api'. - * The result of the call is delivered to the 'callback' function with the 'callback_closure'. - * - * For convenience, the function calls 'json_object_put' for 'args'. - * Thus, in the case where 'args' should remain available after - * the function returns, the function 'json_object_get' shall be used. - * - * The 'callback' receives 5 arguments: - * 1. 'closure' the user defined closure pointer 'closure', - * 2. 'object' a JSON object returned (can be NULL) - * 3. 'error' a string not NULL in case of error but NULL on success - * 4. 'info' a string handling some info (can be NULL) - * 5. 'api' the api - * - * NOTE: For convenience, *json_object_put* is called on 'object' after the - * callback returns. So, it is wrong to call *json_object_put* in the callback. - * - * @param api The api that makes the call - * @param apiname The api name of the method to call - * @param verb The verb name of the method to call - * @param args The arguments to pass to the method - * @param callback The to call on completion - * @param closure The closure to pass to the callback - * - * - * @see afb_req_subcall - * @see afb_req_subcall_sync - * @see afb_api_call_sync - */ -void afb_api_call( - afb_api_t api, - const char *apiname, - const char *verb, - struct json_object *args, - void (*callback)( - void *closure, - struct json_object *object, - const char *error, - const char * info, - afb_api_t api), - void *closure); -``` - -### afb_api_call_sync - -```C -/** - * Calls the 'verb' of the 'apiname' with the arguments 'args' and 'verb' in the name of the binding 'api'. - * 'result' will receive the response. - * - * For convenience, the function calls 'json_object_put' for 'args'. - * Thus, in the case where 'args' should remain available after - * the function returns, the function 'json_object_get' shall be used. - * - * @param api The api that makes the call - * @param apiname The api name of the method to call - * @param verb The verb name of the method to call - * @param args The arguments to pass to the method - * @param object Where to store the returned object - should call json_object_put on it - can be NULL - * @param error Where to store the copied returned error - should call free on it - can be NULL - * @param info Where to store the copied returned info - should call free on it - can be NULL - * - * @returns 0 in case of success or a negative value in case of error. - * - * @see afb_req_subcall - * @see afb_req_subcall_sync - * @see afb_api_call - */ -int afb_api_call_sync( - afb_api_t api, - const char *apiname, - const char *verb, - struct json_object *args, - struct json_object **object, - char **error, - char **info); -``` - -### afb_api_queue_job - -```C -/** - * Queue the job defined by 'callback' and 'argument' for being executed asynchronously - * in this thread (later) or in an other thread. - * - * If 'group' is not NULL, the jobs queued with a same value (as the pointer value 'group') - * are executed in sequence in the order of there submission. - * - * If 'timeout' is not 0, it represent the maximum execution time for the job in seconds. - * At first, the job is called with 0 as signum and the given argument. - * - * The job is executed with the monitoring of its time and some signals like SIGSEGV and - * SIGFPE. When a such signal is catched, the job is terminated and reexecuted but with - * signum being the signal number (SIGALRM when timeout expired). - * - * When executed, the callback function receives 2 arguments: - * - * - int signum: the signal catched if any or zero at the beginning - * - void *arg: the parameter 'argument' - * - * A typical implementation of the job callback is: - * - * void my_job_cb(int signum, void *arg) - * { - * struct myarg_t *myarg = arg; - * if (signum) - * AFB_API_ERROR(myarg->api, "job interrupted with signal %s", strsignal(signum)); - * else - * really_do_my_job(myarg); - * } - * - * @param api the api that queue the job - * @param callback the job as a callback function - * @param argument the argument to pass to the queued job - * @param group the group of the job, NULL if no group - * @param timeout the timeout of execution of the job - * - * @return 0 in case of success or -1 in case of error with errno set appropriately. - */ -int afb_api_queue_job( - afb_api_t api, - void (*callback)(int signum, void *arg), - void *argument, - void *group, - int timeout); -``` - -## Event functions - -### afb_api_broadcast_event - -```C -/** - * Broadcasts widely the event of 'name' with the data 'object'. - * 'object' can be NULL. - * - * For convenience, the function calls 'json_object_put' for 'object'. - * Thus, in the case where 'object' should remain available after - * the function returns, the function 'json_object_get' shall be used. - * - * Calling this function is only forbidden during preinit. - * - * The event sent as the name API/name where API is the name of the - * api. - * - * @param api the api that broadcast the event - * @param name the event name suffix - * @param object the object that comes with the event - * - * @return 0 in case of success or -1 in case of error - */ -int afb_api_broadcast_event( - afb_api_t api, - const char *name, - struct json_object *object); -``` - -### afb_api_make_event - -```C -/** - * Creates an event of 'name' and returns it. - * - * Calling this function is only forbidden during preinit. - * - * See afb_event_is_valid to check if there is an error. - * - * The event created as the name API/name where API is the name of the - * api. - * - * @param api the api that creates the event - * @param name the event name suffix - * - * @return the created event. Use the function afb_event_is_valid to check - * whether the event is valid (created) or not (error as reported by errno). - * - * @see afb_event_is_valid - */ -afb_event_t afb_api_make_event( - afb_api_t api, - const char *name); -``` - -### afb_api_event_handler_add - -```C -/** - * Add a specific event handler for the api - * - * The handler callback is called when an event matching the given pattern - * is received (it is received if broadcasted or after subscription through - * a call or a subcall). - * - * The handler callback receive 4 arguments: - * - * - the closure given here - * - the event full name - * - the companion JSON object of the event - * - the api that subscribed the event - * - * @param api the api that creates the handler - * @param pattern the global pattern of the event to handle - * @param callback the handler callback function - * @param closure the closure of the handler - * - * @return 0 in case of success or -1 on failure with errno set - * - * @see afb_api_on_event - * @see afb_api_event_handler_del - */ -int afb_api_event_handler_add( - afb_api_t api, - const char *pattern, - void (*callback)( - void *, - const char*, - struct json_object*, - afb_api_t), - void *closure); -``` - -### afb_api_event_handler_del - -```C -/** - * Delete a specific event handler for the api - * - * @param api the api that the handler belongs to - * @param pattern the global pattern of the handler to remove - * @param closure if not NULL it will receive the closure set to the handler - * - * @return 0 in case of success or -1 on failure with errno set - * - * @see afb_api_on_event - * @see afb_api_event_handler_add - */ -int afb_api_event_handler_del( - afb_api_t api, - const char *pattern, - void **closure); - -``` - -## Systemd functions - -### afb_api_get_event_loop - -```C -/** - * Retrieves the common systemd's event loop of AFB - * - * @param api the api that uses the event loop - * - * @return the systemd event loop if active, NULL otherwise - * - * @see afb_api_get_user_bus - * @see afb_api_get_system_bus - */ -struct sd_event *afb_api_get_event_loop( - afb_api_t api); -``` - -### afb_api_get_user_bus - -```C -/** - * Retrieves the common systemd's user/session d-bus of AFB - * - * @param api the api that uses the user dbus - * - * @return the systemd user connection to dbus if active, NULL otherwise - * - * @see afb_api_get_event_loop - * @see afb_api_get_system_bus - */ -struct sd_bus *afb_api_get_user_bus( - afb_api_t api); -``` - -### afb_api_get_system_bus - -```C -/** - * Retrieves the common systemd's system d-bus of AFB - * - * @param api the api that uses the system dbus - * - * @return the systemd system connection to dbus if active, NULL otherwise - * - * @see afb_api_get_event_loop - * @see afb_api_get_user_bus - */ -struct sd_bus *afb_api_get_system_bus( - afb_api_t api); -``` - - -## Dynamic api functions - -### afb_api_new_api - -```C -/** - * Creates a new api of name 'apiname' briefly described by 'info' (that can - * be NULL). - * - * When the pre-initialization function is given, it is a function that - * receives 2 parameters: - * - * - the closure as given in the call - * - the created api that can be initialised - * - * This pre-initialization function must return a negative value to abort - * the creation of the api. Otherwise, it returns a non-negative value to - * continue. - * - * @param api the api that creates the other one - * @param apiname the name of the new api - * @param info the brief description of the new api (can be NULL) - * @param noconcurrency zero or not zero whether the new api is reentrant or not - * @param preinit the pre-initialization function if any (can be NULL) - * @param closure the closure for the pre-initialization preinit - * - * @return the created api in case of success or NULL on error - * - * @see afb_api_delete_api - */ -afb_api_t afb_api_new_api( - afb_api_t api, - const char *apiname, - const char *info, - int noconcurrency, - int (*preinit)(void*, afb_api_t ), - void *closure); -``` - -### afb_api_set_verbs_v2 - -```C -/** - * @deprecated use @ref afb_api_set_verbs_v3 instead - * - * Set the verbs of the 'api' using description of verbs of the api v2 - * - * @param api the api that will get the verbs - * @param verbs the array of verbs to add terminated with an item with name=NULL - * - * @return 0 in case of success or -1 on failure with errno set - * - * @see afb_verb_v2 - * @see afb_api_add_verb - * @see afb_api_set_verbs_v3 - */ -int afb_api_set_verbs_v2( - afb_api_t api, - const struct afb_verb_v2 *verbs); -``` - -### afb_api_set_verbs_v3 - -```C -/** - * Set the verbs of the 'api' using description of verbs of the api v2 - * - * @param api the api that will get the verbs - * @param verbs the array of verbs to add terminated with an item with name=NULL - * - * @return 0 in case of success or -1 on failure with errno set - * - * @see afb_verb_v3 - * @see afb_api_add_verb - * @see afb_api_del_verb - */ -int afb_api_set_verbs_v3( - afb_api_t api, - const struct afb_verb_v3 *verbs); -``` - -### afb_api_add_verb - -```C -/** - * Add one verb to the dynamic set of the api - * - * @param api the api to change - * @param verb name of the verb - * @param info brief description of the verb, can be NULL - * @param callback callback function implementing the verb - * @param vcbdata data for the verb callback, available through req - * @param auth required authorization, can be NULL - * @param session authorization and session requirements of the verb - * @param glob is the verb glob name - * - * @return 0 in case of success or -1 on failure with errno set - * - * @see afb_verb_v3 - * @see afb_api_del_verb - * @see afb_api_set_verbs_v3 - * @see fnmatch for matching names using glob - */ -int afb_api_add_verb( - afb_api_t api, - const char *verb, - const char *info, - void (*callback)(struct afb_req_x2 *req), - void *vcbdata, - const struct afb_auth *auth, - uint32_t session, - int glob); -``` - -### afb_api_del_verb - -```C -/** - * Delete one verb from the dynamic set of the api - * - * @param api the api to change - * @param verb name of the verb to delete - * @param vcbdata if not NULL will receive the vcbdata of the deleted verb - * - * @return 0 in case of success or -1 on failure with errno set - * - * @see afb_api_add_verb - */ -int afb_api_del_verb( - afb_api_t api, - const char *verb, - void **vcbdata); -``` - -### afb_api_on_event - -```C -/** - * Set the callback 'onevent' to process events in the name of the 'api'. - * - * This setting can be done statically using the global variable - * @ref afbBindingV3. - * - * This function replace any previously global event callback set. - * - * When an event is received, the callback 'onevent' is called with 3 parameters - * - * - the api that recorded the event handler - * - the full name of the event - * - the companion JSON object of the event - * - * @param api the api that wants to process events - * @param onevent the callback function that will process events (can be NULL - * to remove event callback) - * - * @return 0 in case of success or -1 on failure with errno set - * - * @see afbBindingV3 - * @see afb_binding_v3 - * @see afb_api_event_handler_add - * @see afb_api_event_handler_del - */ -int afb_api_on_event( - afb_api_t api, - void (*onevent)( - afb_api_t api, - const char *event, - struct json_object *object)); -``` - -### afb_api_on_init - -```C -/** - * Set the callback 'oninit' to process initialization of the 'api'. - * - * This setting can be done statically using the global variable - * @ref afbBindingV3 - * - * This function replace any previously initialization callback set. - * - * This function is only valid during the pre-initialization stage. - * - * The callback initialization function will receive one argument: the api - * to initialize. - * - * @param api the api that wants to process events - * @param oninit the callback function that initialize the api - * - * @return 0 in case of success or -1 on failure with errno set - * - * @see afbBindingV3 - * @see afb_binding_v3 - */ -int afb_api_on_init( - afb_api_t api, - int (*oninit)(afb_api_t api)); -``` - -### afb_api_provide_class - -```C -/** - * Tells that the api provides a class of features. Classes are intended to - * allow ordering of initializations: apis that provides a given class are - * initialized before apis requiring it. - * - * This function is only valid during the pre-initialization stage. - * - * @param api the api that provides the classes - * @param name a space separated list of the names of the provided classes - * - * @returns 0 in case of success or a negative value in case of error. - * - * @see afb_api_require_class - */ -int afb_api_provide_class( - afb_api_t api, - const char *name); -``` - -### afb_api_require_class - -```C -/** - * Tells that the api requires a set of class features. Classes are intended to - * allow ordering of initializations: apis that provides a given class are - * initialized before apis requiring it. - * - * This function is only valid during the pre-initialization stage. - * - * @param api the api that requires the classes - * @param name a space separated list of the names of the required classes - * - * @returns 0 in case of success or a negative value in case of error. - * - * @see afb_api_provide_class - */ -int afb_api_require_class( - afb_api_t api, - const char *name); -``` - -### afb_api_seal - -```C -/** - * Seal the api. After a call to this function the api can not be modified - * anymore. - * - * @param api the api to be sealed - */ -void afb_api_seal( - afb_api_t api); -``` - -### afb_api_delete_api - -```C -/** - * Delete the given api. - * - * It is of the responsibility of the caller to don't used the deleted api - * anymore after this function returned. - * - * @param api the api to delete - * - * @returns 0 in case of success or a negative value in case of error. - * - * @see afb_api_new_api - */ -int afb_api_delete_api( - afb_api_t api); -``` - -### afb_api_add_alias - -```C -/** - * Create an aliased name 'as_name' for the api 'name'. - * Calling this function is only allowed within preinit. - * - * @param api the api that requires the aliasing - * @param name the api to alias - * @param as_name the aliased name of the aliased api - * - * @return 0 in case of success or -1 in case of error with errno set appropriately. - */ -int afb_api_add_alias( - afb_api_t api, - const char *name, - const char *as_name); -``` - - -## Legacy functions - -The function for legacy calls are still provided for some time because -adaptation of existing code to the new call functions require a small amount -of work. - -### afb_api_call_legacy - -```C -/** - * @deprecated try to use @ref afb_api_call instead - * - * Calls the 'verb' of the 'apiname' with the arguments 'args' and 'verb' - * in the name of the binding. - * The result of the call is delivered to the 'callback' function - * with the 'callback_closure'. - * - * For convenience, the function calls 'json_object_put' for 'args'. - * Thus, in the case where 'args' should remain available after - * the function returns, the function 'json_object_get' shall be used. - * - * The 'callback' receives 3 arguments: - * 1. 'closure' the user defined closure pointer 'closure', - * 2. 'status' a status being 0 on success or negative when an error occurred, - * 2. 'result' the resulting data as a JSON object. - * - * @param api The api - * @param apiname The api name of the method to call - * @param verb The verb name of the method to call - * @param args The arguments to pass to the method - * @param callback The to call on completion - * @param closure The closure to pass to the callback - * - * @see also 'afb_api_call' - * @see also 'afb_api_call_sync' - * @see also 'afb_api_call_sync_legacy' - * @see also 'afb_req_subcall' - * @see also 'afb_req_subcall_sync' - */ -void afb_api_call_legacy( - afb_api_t api, - const char *apiname, - const char *verb, - struct json_object *args, - void (*callback)( - void *closure, - int status, - struct json_object *result, - afb_api_t api), - void *closure); -``` - -### afb_api_call_sync_legacy - -```C -/** - * @deprecated try to use @ref afb_api_call_sync instead - * - * Calls the 'verb' of the 'apiname' with the arguments 'args' and 'verb' - * in the name of the binding. - * 'result' will receive the response. - * - * For convenience, the function calls 'json_object_put' for 'args'. - * Thus, in the case where 'args' should remain available after - * the function returns, the function 'json_object_get' shall be used. - * - * @param api The api - * @param apiname The api name of the method to call - * @param verb The verb name of the method to call - * @param args The arguments to pass to the method - * @param result Where to store the result - should call json_object_put on it - - * - * @returns 0 in case of success or a negative value in case of error. - * - * @see also 'afb_api_call' - * @see also 'afb_api_call_sync' - * @see also 'afb_api_call_legacy' - * @see also 'afb_req_subcall' - * @see also 'afb_req_subcall_sync' - */ -int afb_api_call_sync_legacy( - afb_api_t api, - const char *apiname, - const char *verb, - struct json_object *args, - struct json_object **result); -``` - diff --git a/docs/4_APIs_and_Services/4.3_Application_Framework_Binder/3_Binder_references/4_Functions_of_class_afb_req.md b/docs/4_APIs_and_Services/4.3_Application_Framework_Binder/3_Binder_references/4_Functions_of_class_afb_req.md deleted file mode 100644 index 773bae0..0000000 --- a/docs/4_APIs_and_Services/4.3_Application_Framework_Binder/3_Binder_references/4_Functions_of_class_afb_req.md +++ /dev/null @@ -1,851 +0,0 @@ ---- -edit_link: '' -title: Functions of class afb_req -origin_url: >- - https://git.automotivelinux.org/src/app-framework-binder/plain/docs/reference-v3/func-req.md?h=master ---- - - - -Functions of class **afb_req** -============================ - -## General function - -### afb_req_is_valid - -```C -/** - * Checks whether the request 'req' is valid or not. - * - * @param req the request to check - * - * @return 0 if not valid or 1 if valid. - */ -int afb_req_is_valid( - afb_req_t req); -``` - -### afb_req_get_api - -```C -/** - * Retrieves the api that serves the request - * - * @param req the request whose serving api is queried - * - * @return the api serving the request - */ -afb_api_t afb_req_get_api( - afb_req_t req); -``` - -### afb_req_get_vcbdata - -```C -/** - * Retrieves the callback data of the verb. This callback data is set - * when the verb is created. - * - * @param req whose verb vcbdata is queried - * - * @return the callback data attached to the verb description - */ -void *afb_req_get_vcbdata( - afb_req_t req); -``` - -### afb_req_get_called_api - -```C -/** - * Retrieve the name of the called api. - * - * @param req the request - * - * @return the name of the called api - * - * @see afb_api_new_api - * @see afb_api_add_alias - */ -const char *afb_req_get_called_api( - afb_req_t req); -``` - -### afb_req_get_called_verb - -```C -/** - * Retrieve the name of the called verb - * - * @param req the request - * - * @return the name of the called verb - */ -const char *afb_req_get_called_verb( - afb_req_t req); -``` - -### afb_req_addref - -```C -/** - * Increments the count of references of 'req'. - * - * @param req the request - * - * @return returns the request req - */ -afb_req_t *afb_req_addref( - afb_req_t req); -``` - -### afb_req_unref - -```C -/** - * Decrement the count of references of 'req'. - * - * @param req the request - */ -void afb_req_unref( - afb_req_t req); -``` - - -## Logging functions - -### afb_req_wants_log_level - -```C -/** - * Is the log message of 'level (as defined for syslog) required for the - * request 'req'? - * - * @param req the request - * @param level the level to check as defined for syslog: - * - * EMERGENCY 0 System is unusable - * ALERT 1 Action must be taken immediately - * CRITICAL 2 Critical conditions - * ERROR 3 Error conditions - * WARNING 4 Warning conditions - * NOTICE 5 Normal but significant condition - * INFO 6 Informational - * DEBUG 7 Debug-level messages - * - * @return 0 if not required or a value not null if required - * - * @see syslog - */ -int afb_req_wants_log_level( - afb_req_t req, - int level); -``` - -### afb_req_vverbose - -```C -/** - * Send associated to 'req' a message described by 'fmt' and its 'args' - * to the journal for the verbosity 'level'. - * - * 'file', 'line' and 'func' are indicators of position of the code in source files - * (see macros __FILE__, __LINE__ and __func__). - * - * 'level' is defined by syslog standard: - * EMERGENCY 0 System is unusable - * ALERT 1 Action must be taken immediately - * CRITICAL 2 Critical conditions - * ERROR 3 Error conditions - * WARNING 4 Warning conditions - * NOTICE 5 Normal but significant condition - * INFO 6 Informational - * DEBUG 7 Debug-level messages - * - * @param req the request - * @param level the level of the message - * @param file the source filename that emits the message or NULL - * @param line the line number in the source filename that emits the message - * @param func the name of the function that emits the message or NULL - * @param fmt the message format as for printf - * @param args the arguments to the format - * - * @see printf - * @see afb_req_verbose - */ -void afb_req_vverbose( - afb_req_t req, - int level, const char *file, - int line, - const char * func, - const char *fmt, - va_list args); -``` - -### afb_req_verbose - -```C -/** - * Send associated to 'req' a message described by 'fmt' and following parameters - * to the journal for the verbosity 'level'. - * - * 'file', 'line' and 'func' are indicators of position of the code in source files - * (see macros __FILE__, __LINE__ and __func__). - * - * 'level' is defined by syslog standard: - * EMERGENCY 0 System is unusable - * ALERT 1 Action must be taken immediately - * CRITICAL 2 Critical conditions - * ERROR 3 Error conditions - * WARNING 4 Warning conditions - * NOTICE 5 Normal but significant condition - * INFO 6 Informational - * DEBUG 7 Debug-level messages - * - * @param req the request - * @param level the level of the message - * @param file the source filename that emits the message or NULL - * @param line the line number in the source filename that emits the message - * @param func the name of the function that emits the message or NULL - * @param fmt the message format as for printf - * @param ... the arguments of the format 'fmt' - * - * @see printf - */ -void afb_req_verbose( - afb_req_t req, - int level, const char *file, - int line, - const char * func, - const char *fmt, - ...); -``` - -## Arguments/parameters function - -### afb_req_get - -```C -/** - * Gets from the request 'req' the argument of 'name'. - * - * Returns a PLAIN structure of type 'struct afb_arg'. - * - * When the argument of 'name' is not found, all fields of result are set to NULL. - * - * When the argument of 'name' is found, the fields are filled, - * in particular, the field 'result.name' is set to 'name'. - * - * There is a special name value: the empty string. - * The argument of name "" is defined only if the request was made using - * an HTTP POST of Content-Type "application/json". In that case, the - * argument of name "" receives the value of the body of the HTTP request. - * - * @param req the request - * @param name the name of the argument to get - * - * @return a structure describing the retrieved argument for the request - * - * @see afb_req_value - * @see afb_req_path - */ -struct afb_arg afb_req_get( - afb_req_t req, - const char *name); -``` - -### afb_req_value - -```C -/** - * Gets from the request 'req' the string value of the argument of 'name'. - * Returns NULL if when there is no argument of 'name'. - * Returns the value of the argument of 'name' otherwise. - * - * Shortcut for: afb_req_get(req, name).value - * - * @param req the request - * @param name the name of the argument's value to get - * - * @return the value as a string or NULL - * - * @see afb_req_get - * @see afb_req_path - */ -const char *afb_req_value( - afb_req_t req, - const char *name); -``` - -### afb_req_path - -```C -/** - * Gets from the request 'req' the path for file attached to the argument of 'name'. - * Returns NULL if when there is no argument of 'name' or when there is no file. - * Returns the path of the argument of 'name' otherwise. - * - * Shortcut for: afb_req_get(req, name).path - * - * @param req the request - * @param name the name of the argument's path to get - * - * @return the path if any or NULL - * - * @see afb_req_get - * @see afb_req_value - */ -const char *afb_req_path( - afb_req_t req, - const char *name); -``` - -### afb_req_json - -```C -/** - * Gets from the request 'req' the json object hashing the arguments. - * - * The returned object must not be released using 'json_object_put'. - * - * @param req the request - * - * @return the JSON object of the query - * - * @see afb_req_get - * @see afb_req_value - * @see afb_req_path - */ -struct json_object *afb_req_json( - afb_req_t req); -``` - -## Reply functions - -The functions **success** and **fail** are still supported. -These functions are now implemented as the following macros: - -```C -#define afb_req_success(r,o,i) afb_req_reply(r,o,NULL,i) -#define afb_req_success_f(r,o,...) afb_req_reply_f(r,o,NULL,__VA_ARGS__) -#define afb_req_success_v(r,o,f,v) afb_req_reply_v(r,o,NULL,f,v) -#define afb_req_fail(r,e,i) afb_req_reply(r,NULL,e,i) -#define afb_req_fail_f(r,e,...) afb_req_reply_f(r,NULL,e,__VA_ARGS__) -#define afb_req_fail_v(r,e,f,v) afb_req_reply_v(r,NULL,e,f,v) -``` - - -### afb_req_reply - -```C -/** - * Sends a reply to the request 'req'. - * - * The status of the reply is set to 'error' (that must be NULL on success). - * Its send the object 'obj' (can be NULL) with an - * informational comment 'info (can also be NULL). - * - * For convenience, the function calls 'json_object_put' for 'obj'. - * Thus, in the case where 'obj' should remain available after - * the function returns, the function 'json_object_get' shall be used. - * - * @param req the request - * @param obj the replied object or NULL - * @param error the error message if it is a reply error or NULL - * @param info an informative text or NULL - * - * @see afb_req_reply_v - * @see afb_req_reply_f - */ -void afb_req_reply( - afb_req_t req, - struct json_object *obj, - const char *error, - const char *info); -``` - -### afb_req_reply_v - -```C -/** - * Same as 'afb_req_reply_f' but the arguments to the format 'info' - * are given as a variable argument list instance. - * - * For convenience, the function calls 'json_object_put' for 'obj'. - * Thus, in the case where 'obj' should remain available after - * the function returns, the function 'json_object_get' shall be used. - * - * @param req the request - * @param obj the replied object or NULL - * @param error the error message if it is a reply error or NULL - * @param info an informative text containing a format as for vprintf - * @param args the va_list of arguments to the format as for vprintf - * - * @see afb_req_reply - * @see afb_req_reply_f - * @see vprintf - */ -void afb_req_reply_v( - afb_req_t req, - struct json_object *obj, - const char *error, - const char *info, - va_list args); -``` - -### afb_req_reply_f - -```C -/** - * Same as 'afb_req_reply' but the 'info' is a formatting - * string followed by arguments. - * - * For convenience, the function calls 'json_object_put' for 'obj'. - * Thus, in the case where 'obj' should remain available after - * the function returns, the function 'json_object_get' shall be used. - * - * @param req the request - * @param obj the replied object or NULL - * @param error the error message if it is a reply error or NULL - * @param info an informative text containing a format as for printf - * @param ... the arguments to the format as for printf - * - * @see afb_req_reply - * @see afb_req_reply_v - * @see printf - */ -void afb_req_reply_f( - afb_req_t req, - struct json_object *obj, - const char *error, - const char *info, - ...); -``` - -## Subcall functions - - - -### afb_req_subcall - -```C -/** - * Calls the 'verb' of the 'api' with the arguments 'args' and 'verb' in the name of the binding. - * The result of the call is delivered to the 'callback' function with the 'callback_closure'. - * - * For convenience, the function calls 'json_object_put' for 'args'. - * Thus, in the case where 'args' should remain available after - * the function returns, the function 'json_object_get' shall be used. - * - * The 'callback' receives 5 arguments: - * 1. 'closure' the user defined closure pointer 'closure', - * 2. 'object' a JSON object returned (can be NULL) - * 3. 'error' a string not NULL in case of error - * 4. 'info' a string handling some info (can be NULL) - * 5. 'req' the req - * - * NOTE: For convenience, *json_object_put* is called on 'object' after the - * callback returns. So, it is wrong to call *json_object_put* in the callback. - * - * @param req The request - * @param api The api name of the method to call - * @param verb The verb name of the method to call - * @param args The arguments to pass to the method - * @param flags The bit field of flags for the subcall as defined by @ref afb_req_subcall_flags_t - * @param callback The to call on completion - * @param closure The closure to pass to the callback - * - * The flags are any combination of the following values: - * - * - afb_req_x2_subcall_catch_events = 1 - * - * the calling API wants to receive the events from subscription - * - * - afb_req_x2_subcall_pass_events = 2 - * - * the original request will receive the events from subscription - * - * - afb_req_x2_subcall_on_behalf = 4 - * - * the calling API wants to use the credentials of the original request - * - * - afb_req_x2_subcall_api_session = 8 - * - * the calling API wants to use its session instead of the one of the - * original request - * - * @see also 'afb_req_subcall_sync' - */ -void afb_req_subcall( - afb_req_t req, - const char *api, - const char *verb, - struct json_object *args, - int flags, - void (*callback)( - void *closure, - struct json_object *object, - const char *error, - const char * info, - afb_req_t req), - void *closure); -``` - -### afb_req_subcall_sync - -```C -/** - * Makes a call to the method of name 'api' / 'verb' with the object 'args'. - * This call is made in the context of the request 'req'. - * This call is synchronous, it waits untill completion of the request. - * It returns 0 on success or a negative value on error answer. - * - * For convenience, the function calls 'json_object_put' for 'args'. - * Thus, in the case where 'args' should remain available after - * the function returns, the function 'json_object_get' shall be used. - * - * See also: - * - 'afb_req_subcall_req' that is convenient to keep request alive automatically. - * - 'afb_req_subcall' that doesn't keep request alive automatically. - * - * @param req The request - * @param api The api name of the method to call - * @param verb The verb name of the method to call - * @param args The arguments to pass to the method - * @param flags The bit field of flags for the subcall as defined by @ref afb_req_subcall_flags - * @param object a pointer where the replied JSON object is stored must be freed using @ref json_object_put (can be NULL) - * @param error a pointer where a copy of the replied error is stored must be freed using @ref free (can be NULL) - * @param info a pointer where a copy of the replied info is stored must be freed using @ref free (can be NULL) - * - * @return 0 in case of success or -1 in case of error - */ -int afb_req_subcall_sync( - afb_req_t req, - const char *api, - const char *verb, - struct json_object *args, - int flags, - struct json_object **object, - char **error, - char **info); -``` - -## Event functions - -### afb_req_subscribe - -```C -/** - * Establishes for the client link identified by 'req' a subscription - * to the 'event'. - * - * Establishing subscription MUST be called BEFORE replying to the request. - * - * @param req the request - * @param event the event to subscribe - * - * @return 0 in case of successful subscription or -1 in case of error. - */ -int afb_req_subscribe( - afb_req_t req, - afb_event_t event); -``` - -### afb_req_unsubscribe - -```C -/** - * Revokes the subscription established to the 'event' for the client - * link identified by 'req'. - * Returns 0 in case of successful subscription or -1 in case of error. - * - * Revoking subscription MUST be called BEFORE replying to the request. - * - * @param req the request - * @param event the event to revoke - * - * @return 0 in case of successful subscription or -1 in case of error. - */ -int afb_req_unsubscribe( - afb_req_t req, - afb_event_t event); -``` - -## Session functions - -### afb_req_context - -```C -/** - * Manage the pointer stored by the binding for the client session of 'req'. - * - * If no previous pointer is stored or if 'replace' is not zero, a new value - * is generated using the function 'create_context' called with the 'closure'. - * If 'create_context' is NULL the generated value is 'closure'. - * - * When a value is created, the function 'free_context' is recorded and will - * be called (with the created value as argument) to free the created value when - * it is not more used. - * - * This function is atomic: it ensures that 2 threads will not race together. - * - * @param req the request - * @param replace if not zero an existing value is replaced - * @param create_context the creation function or NULL - * @param free_context the destroying function or NULL - * @param closure the closure to the creation function - * - * @return the stored value - */ -void *afb_req_context( - afb_req_t req, - int replace, - void *(*create_context)(void *closure), - void (*free_context)(void*), - void *closure); -``` - -### afb_req_context_get - -```C -/** - * Gets the pointer stored by the binding for the session of 'req'. - * When the binding has not yet recorded a pointer, NULL is returned. - * - * Shortcut for: afb_req_context(req, 0, NULL, NULL, NULL) - * - * @param req the request - * - * @return the previously stored value - */ -void *afb_req_context_get( - afb_req_t req); -``` - -### afb_req_context_set - -```C -/** - * Stores for the binding the pointer 'context' to the session of 'req'. - * The function 'free_context' will be called when the session is closed - * or if binding stores an other pointer. - * - * Shortcut for: afb_req_context(req, 1, NULL, free_context, context) - * - * - * @param req the request - * @param context the context value to store - * @param free_context the cleaning function for the stored context (can be NULL) - */ -void afb_req_context_set( - afb_req_t req, - void *context, - void (*free_context)(void*)); -``` - -### afb_req_context_clear - -```C -/** - * Frees the pointer stored by the binding for the session of 'req' - * and sets it to NULL. - * - * Shortcut for: afb_req_context_set(req, NULL, NULL) - * - * @param req the request - */ -void afb_req_context_clear( - afb_req_t req); -``` - -### afb_req_session_close - -```C -/** - * Closes the session associated with 'req' - * and delete all associated contexts. - * - * @param req the request - */ -void afb_req_session_close( - afb_req_t req); -``` - -### afb_req_session_set_LOA - -```C -/** - * Sets the level of assurance of the session of 'req' - * to 'level'. The effect of this function is subject of - * security policies. - * - * @param req the request - * @param level of assurance from 0 to 7 - * - * @return 0 on success or -1 if failed. - */ -int afb_req_session_set_LOA( - afb_req_t req, - unsigned level); -``` - -## Credential/client functions - -### afb_req_has_permission - -```C -/** - * Check whether the 'permission' is granted or not to the client - * identified by 'req'. - * - * @param req the request - * @param permission string to check - * - * @return 1 if the permission is granted or 0 otherwise. - */ -int afb_req_has_permission( - afb_req_t req, - const char *permission); -``` - -### afb_req_get_application_id - -```C -/** - * Get the application identifier of the client application for the - * request 'req'. - * - * Returns the application identifier or NULL when the application - * can not be identified. - * - * The returned value if not NULL must be freed by the caller - * - * @param req the request - * - * @return the string for the application id of the client MUST BE FREED - */ -char *afb_req_get_application_id( - afb_req_t req); -``` - -### afb_req_get_uid - -```C -/** - * Get the user identifier (UID) of the client for the - * request 'req'. - * - * @param req the request - * - * @return -1 when the application can not be identified or the unix uid. - * - */ -int afb_req_get_uid( - afb_req_t req); -``` - -### afb_req_get_client_info - -```C -/** - * Get informations about the client of the - * request 'req'. - * - * Returns an object with client informations: - * { - * "pid": int, "uid": int, "gid": int, - * "label": string, "id": string, "user": string, - * "uuid": string, "LOA": int - * } - * - * If some of this information can't be computed, the field of the return - * object will not be set at all. - * - * @param req the request - * - * @return a JSON object that must be freed using @ref json_object_put - */ -struct json_object *afb_req_get_client_info( - afb_req_t req); -``` - -## Legacy functions - -### afb_req_subcall_legacy - -```C -/** - * @deprecated use @ref afb_req_subcall - * - * Makes a call to the method of name 'api' / 'verb' with the object 'args'. - * This call is made in the context of the request 'req'. - * On completion, the function 'callback' is invoked with the - * 'closure' given at call and two other parameters: 'iserror' and 'result'. - * 'status' is 0 on success or negative when on an error reply. - * 'result' is the json object of the reply, you must not call json_object_put - * on the result. - * - * For convenience, the function calls 'json_object_put' for 'args'. - * Thus, in the case where 'args' should remain available after - * the function returns, the function 'json_object_get' shall be used. - * - * @param req the request - * @param api the name of the api to call - * @param verb the name of the verb to call - * @param args the arguments of the call as a JSON object - * @param callback the call back that will receive the reply - * @param closure the closure passed back to the callback - * - * @see afb_req_subcall - * @see afb_req_subcall_sync - */ -void afb_req_subcall_legacy( - afb_req_t req, - const char *api, - const char *verb, - struct json_object *args, - void (*callback)( - void *closure, - int iserror, - struct json_object *result, - afb_req_t req), - void *closure); -``` - -### afb_req_subcall_sync_legacy - -```C -/** - * @deprecated use @ref afb_req_subcall_sync - * - * Makes a call to the method of name 'api' / 'verb' with the object 'args'. - * This call is made in the context of the request 'req'. - * This call is synchronous, it waits until completion of the request. - * It returns 0 on success or a negative value on error answer. - * The object pointed by 'result' is filled and must be released by the caller - * after its use by calling 'json_object_put'. - * - * For convenience, the function calls 'json_object_put' for 'args'. - * Thus, in the case where 'args' should remain available after - * the function returns, the function 'json_object_get' shall be used. - * - * @param req the request - * @param api the name of the api to call - * @param verb the name of the verb to call - * @param args the arguments of the call as a JSON object - * @param result the pointer to the JSON object pointer that will receive the result - * - * @return 0 on success or a negative value on error answer. - * - * @see afb_req_subcall - * @see afb_req_subcall_sync - */ -int afb_req_subcall_sync_legacy( - afb_req_t req, - const char *api, - const char *verb, - struct json_object *args, - struct json_object **result); -``` - diff --git a/docs/4_APIs_and_Services/4.3_Application_Framework_Binder/3_Binder_references/5_Functions_of_class_afb_event.md b/docs/4_APIs_and_Services/4.3_Application_Framework_Binder/3_Binder_references/5_Functions_of_class_afb_event.md deleted file mode 100644 index 87d9a44..0000000 --- a/docs/4_APIs_and_Services/4.3_Application_Framework_Binder/3_Binder_references/5_Functions_of_class_afb_event.md +++ /dev/null @@ -1,120 +0,0 @@ ---- -edit_link: '' -title: Functions of class afb_event -origin_url: >- - https://git.automotivelinux.org/src/app-framework-binder/plain/docs/reference-v3/func-event.md?h=master ---- - - - -Functions of class **afb_event** -============================== - -## General functions - -### afb_event_is_valid - -```C -/** - * Checks whether the 'event' is valid or not. - * - * @param event the event to check - * - * @return 0 if not valid or 1 if valid. - */ -int afb_event_is_valid( - afb_event_t event); -``` - -### afb_event_name - -```C -/** - * Gets the name associated to 'event'. - * - * @param event the event whose name is requested - * - * @return the name of the event - * - * The returned name can be used until call to 'afb_event_unref'. - * It shouldn't be freed. - */ -const char *afb_event_name( - afb_event_t event); -``` - -### afb_event_unref - -```C -/** - * Decrease the count of references to 'event'. - * Call this function when the evenid is no more used. - * It destroys the event_x2 when the reference count falls to zero. - * - * @param event the event - */ -void afb_event_unref( - afb_event_t event); -``` - -### afb_event_addref - -```C -/** - * Increases the count of references to 'event' - * - * @param event the event - * - * @return the event - */ -afb_event_t *afb_event_addref( - afb_event_t event); -``` - -## Pushing functions - -### afb_event_broadcast - -```C -/** - * Broadcasts widely an event of 'event' with the data 'object'. - * 'object' can be NULL. - * - * For convenience, the function calls 'json_object_put' for 'object'. - * Thus, in the case where 'object' should remain available after - * the function returns, the function 'json_object_get' shall be used. - * - * @param event the event to broadcast - * @param object the companion object to associate to the broadcasted event (can be NULL) - * - * @return 0 in case of success or -1 in case of error - */ -int afb_event_broadcast( - afb_event_t event, - struct json_object *object); -``` - -### afb_event_push - -```C -/** - * Pushes an event of 'event' with the data 'object' to its observers. - * 'object' can be NULL. - * - * For convenience, the function calls 'json_object_put' for 'object'. - * Thus, in the case where 'object' should remain available after - * the function returns, the function 'json_object_get' shall be used. - * - * @param event the event to push - * @param object the companion object to associate to the pushed event (can be NULL) - * - * @Return - * * 1 if at least one client listen for the event - * * 0 if no more client listen for the event - * * -1 in case of error (the event can't be delivered) - */ -int afb_event_push( - afb_event_t event, - struct json_object *object); -``` - diff --git a/docs/4_APIs_and_Services/4.3_Application_Framework_Binder/3_Binder_references/6_Functions_of_class_afb_daemon.md b/docs/4_APIs_and_Services/4.3_Application_Framework_Binder/3_Binder_references/6_Functions_of_class_afb_daemon.md deleted file mode 100644 index c9cb003..0000000 --- a/docs/4_APIs_and_Services/4.3_Application_Framework_Binder/3_Binder_references/6_Functions_of_class_afb_daemon.md +++ /dev/null @@ -1,155 +0,0 @@ ---- -edit_link: '' -title: Functions of class afb_daemon -origin_url: >- - https://git.automotivelinux.org/src/app-framework-binder/plain/docs/reference-v3/func-daemon.md?h=master ---- - - - -Functions of class **afb_daemon** -============================ - -All the functions of the class **afb_daemon** use the default api. -This are internally aliased to the corresponding function of class afb_api_t. - -```C -/** - * Retrieves the common systemd's event loop of AFB - */ -struct sd_event *afb_daemon_get_event_loop(); - -/** - * Retrieves the common systemd's user/session d-bus of AFB - */ -struct sd_bus *afb_daemon_get_user_bus(); - -/** - * Retrieves the common systemd's system d-bus of AFB - */ -struct sd_bus *afb_daemon_get_system_bus(); - -/** - * Broadcasts widely the event of 'name' with the data 'object'. - * 'object' can be NULL. - * - * For convenience, the function calls 'json_object_put' for 'object'. - * Thus, in the case where 'object' should remain available after - * the function returns, the function 'json_object_get' shall be used. - * - * Calling this function is only forbidden during preinit. - * - * Returns the count of clients that received the event. - */ -int afb_daemon_broadcast_event( - const char *name, - struct json_object *object); - -/** - * Creates an event of 'name' and returns it. - * - * Calling this function is only forbidden during preinit. - * - * See afb_event_is_valid to check if there is an error. - */ -afb_event_t afb_daemon_make_event( - const char *name); - -/** - * @deprecated use bindings version 3 - * - * Send a message described by 'fmt' and following parameters - * to the journal for the verbosity 'level'. - * - * 'file', 'line' and 'func' are indicators of position of the code in source files - * (see macros __FILE__, __LINE__ and __func__). - * - * 'level' is defined by syslog standard: - * EMERGENCY 0 System is unusable - * ALERT 1 Action must be taken immediately - * CRITICAL 2 Critical conditions - * ERROR 3 Error conditions - * WARNING 4 Warning conditions - * NOTICE 5 Normal but significant condition - * INFO 6 Informational - * DEBUG 7 Debug-level messages - */ -void afb_daemon_verbose( - int level, - const char *file, - int line, - const char * func, - const char *fmt, - ...); - -/** - * @deprecated use bindings version 3 - * - * Get the root directory file descriptor. This file descriptor can - * be used with functions 'openat', 'fstatat', ... - * - * Returns the file descriptor or -1 in case of error. - */ -int afb_daemon_rootdir_get_fd(); - -/** - * Opens 'filename' within the root directory with 'flags' (see function openat) - * using the 'locale' definition (example: "jp,en-US") that can be NULL. - * - * Returns the file descriptor or -1 in case of error. - */ -int afb_daemon_rootdir_open_locale( - const char *filename, - int flags, - const char *locale); - -/** - * Queue the job defined by 'callback' and 'argument' for being executed asynchronously - * in this thread (later) or in an other thread. - * If 'group' is not NUL, the jobs queued with a same value (as the pointer value 'group') - * are executed in sequence in the order of there submission. - * If 'timeout' is not 0, it represent the maximum execution time for the job in seconds. - * At first, the job is called with 0 as signum and the given argument. - * The job is executed with the monitoring of its time and some signals like SIGSEGV and - * SIGFPE. When a such signal is catched, the job is terminated and reexecuted but with - * signum being the signal number (SIGALRM when timeout expired). - * - * Returns 0 in case of success or -1 in case of error. - */ -int afb_daemon_queue_job( - void (*callback)(int signum, void *arg), - void *argument, - void *group, - int timeout); - -/** - * Tells that it requires the API of "name" to exist - * and if 'initialized' is not null to be initialized. - * Calling this function is only allowed within init. - * - * Returns 0 in case of success or -1 in case of error. - */ -int afb_daemon_require_api( - const char *name, - int initialized); - -/** - * Create an aliased name 'as_name' for the api 'name'. - * Calling this function is only allowed within preinit. - * - * Returns 0 in case of success or -1 in case of error. - */ -int afb_daemon_add_alias(const char *name, const char *as_name); - -/** - * Creates a new api of name 'api' with brief 'info'. - * - * Returns 0 in case of success or -1 in case of error. - */ -int afb_daemon_new_api( - const char *api, - const char *info, - int noconcurrency, - int (*preinit)(void*, struct afb_api_x3 *), - void *closure); -``` diff --git a/docs/4_APIs_and_Services/4.3_Application_Framework_Binder/3_Binder_references/7_Functions_of_class afb_service.md b/docs/4_APIs_and_Services/4.3_Application_Framework_Binder/3_Binder_references/7_Functions_of_class afb_service.md deleted file mode 100644 index 645f103..0000000 --- a/docs/4_APIs_and_Services/4.3_Application_Framework_Binder/3_Binder_references/7_Functions_of_class afb_service.md +++ /dev/null @@ -1,171 +0,0 @@ ---- -edit_link: '' -title: Functions of class afb_service -origin_url: >- - https://git.automotivelinux.org/src/app-framework-binder/plain/docs/reference-v3/func-service.md?h=master ---- - - - -Functions of class **afb_service** -============================== - -All the functions of the class **afb_service** use the default api. - -All these function are deprecated, try to use functions of class **afb_api** instead. - -## afb_service_call - -```C -/** - * @deprecated try to use @ref afb_api_call instead - * - * Calls the 'verb' of the 'api' with the arguments 'args' and 'verb' in the name of the binding. - * The result of the call is delivered to the 'callback' function with the 'callback_closure'. - * - * For convenience, the function calls 'json_object_put' for 'args'. - * Thus, in the case where 'args' should remain available after - * the function returns, the function 'json_object_get' shall be used. - * - * The 'callback' receives 5 arguments: - * 1. 'closure' the user defined closure pointer 'closure', - * 2. 'object' a JSON object returned (can be NULL) - * 3. 'error' a string not NULL in case of error but NULL on success - * 4. 'info' a string handling some info (can be NULL) - * 5. 'api' the api - * - * @param api The api name of the method to call - * @param verb The verb name of the method to call - * @param args The arguments to pass to the method - * @param callback The to call on completion - * @param closure The closure to pass to the callback - * - * - * @see afb_req_subcall - * @see afb_req_subcall_sync - * @see afb_api_call_sync - */ -void afb_service_call( - const char *api, - const char *verb, - struct json_object *args, - void (*callback)( - void *closure, - struct json_object *object, - const char *error, - const char * info, - afb_api_t api), - void *closure); -``` - -## afb_service_call_sync - -```C -/** - * @deprecated try to use @ref afb_api_call_sync instead - * - * Calls the 'verb' of the 'api' with the arguments 'args' and 'verb' in the name of the binding. - * 'result' will receive the response. - * - * For convenience, the function calls 'json_object_put' for 'args'. - * Thus, in the case where 'args' should remain available after - * the function returns, the function 'json_object_get' shall be used. - * - * @param api The api name of the method to call - * @param verb The verb name of the method to call - * @param args The arguments to pass to the method - * @param object Where to store the returned object - should call json_object_put on it - can be NULL - * @param error Where to store the copied returned error - should call free on it - can be NULL - * @param info Where to store the copied returned info - should call free on it - can be NULL - * - * @returns 0 in case of success or a negative value in case of error. - * - * @see afb_req_subcall - * @see afb_req_subcall_sync - * @see afb_api_call - */ -int afb_service_call_sync( - const char *api, - const char *verb, - struct json_object *args, - struct json_object **object, - char **error, - char **info); -``` - -## afb_service_call_legacy - -```C -/** - * @deprecated try to use @ref afb_api_call instead - * - * Calls the 'verb' of the 'api' with the arguments 'args' and 'verb' - * in the name of the binding. - * The result of the call is delivered to the 'callback' function with - * the 'callback_closure'. - * - * For convenience, the function calls 'json_object_put' for 'args'. - * Thus, in the case where 'args' should remain available after - * the function returns, the function 'json_object_get' shall be used. - * - * The 'callback' receives 3 arguments: - * 1. 'closure' the user defined closure pointer 'closure', - * 2. 'status' a status being 0 on success or negative when an error occurred, - * 2. 'result' the resulting data as a JSON object. - * - * @param api The api name of the method to call - * @param verb The verb name of the method to call - * @param args The arguments to pass to the method - * @param callback The to call on completion - * @param closure The closure to pass to the callback - * - * @see also 'afb_api_call' - * @see also 'afb_api_call_sync' - * @see also 'afb_api_call_sync_legacy' - * @see also 'afb_req_subcall' - * @see also 'afb_req_subcall_sync' - */ -void afb_service_call_legacy( - const char *api, - const char *verb, - struct json_object *args, - void (*callback)( - void *closure, - int status, - struct json_object *result, - afb_api_t api), - void *closure); -``` - -## afb_service_call_sync_legacy - -```C -/** - * @deprecated try to use @ref afb_api_call_sync instead - * - * Calls the 'verb' of the 'api' with the arguments 'args' and 'verb' in the - * name of the binding. 'result' will receive the response. - * - * For convenience, the function calls 'json_object_put' for 'args'. - * Thus, in the case where 'args' should remain available after - * the function returns, the function 'json_object_get' shall be used. - * - * @param api The api name of the method to call - * @param verb The verb name of the method to call - * @param args The arguments to pass to the method - * @param result Where to store the result - should call json_object_put on it - - * - * @returns 0 in case of success or a negative value in case of error. - * - * @see also 'afb_api_call' - * @see also 'afb_api_call_sync' - * @see also 'afb_api_call_legacy' - * @see also 'afb_req_subcall' - * @see also 'afb_req_subcall_sync' - */ -int afb_service_call_sync_legacy( - const char *api, - const char *verb, - struct json_object *args, - struct json_object **result); -``` diff --git a/docs/4_APIs_and_Services/4.3_Application_Framework_Binder/4_Binder_events_guide/Binder_events_guide.md b/docs/4_APIs_and_Services/4.3_Application_Framework_Binder/4_Binder_events_guide/Binder_events_guide.md deleted file mode 100644 index 51c105a..0000000 --- a/docs/4_APIs_and_Services/4.3_Application_Framework_Binder/4_Binder_events_guide/Binder_events_guide.md +++ /dev/null @@ -1,298 +0,0 @@ ---- -edit_link: '' -title: Binder events guide -origin_url: >- - https://git.automotivelinux.org/src/app-framework-binder/plain/docs/afb-events-guide.md?h=master ---- - - - -# Guide for developing with events - -Signaling agents are services that send events to any clients that -are subscribed to receive it. -The sent events carry any data. - -To have a good understanding of how to: - -- write a signaling agent. -- actions of subscribing. -- actions of unsubscribing. -- actions of producing. -- actions of sending and receiving. - -Events must be described and explained. - -## Overview of events - -The basis of a signaling agent is shown in the following figure: - -![scenario of using events](pictures/signaling-basis.svg) - -This figure shows the main role of the signaling framework for the events -propagation. - -For people not familiar with the framework, a signaling agent and -a “binding” are similar. - -### Subscribing and unsubscribing - -- Subscribing is the action that makes a client able to receive - data from a signaling agent. - -Subscription must : - -1. Create resources for generating the data. -1. Deliver the data to the client. - -These two aspects are not handled by the same piece of software. - -1. Generating the data is the responsibility of the developer of the signaling agent -1. Delivering the data is handled by the framework. - -When a client subscribes for data, the agent must: - -1. Check that the subscription request is correct. -1. Establish the computation chain of the required data (if not already done). -1. Create a named event for the computed data (if not already done). -1. Ask the framework to establish the subscription to the event for the request. -1. Optionally give indications about the event in the reply to the client. - -The first two steps do not involve the framework. -They are linked to the business logic of the binding. -The request can be any description of the requested data -and the computing stream can be of any nature, -this is specific to the binding. - -As said before, the framework uses and integrates **libsystemd** and its event -loop. -Within the framework, **libsystemd** is the standard API/library for -bindings expecting to setup and handle I/O, timer or signal events. - -Steps 3 and 4 are bound to the framework. - -The agent must create an object for handling the propagation of produced -data to its clients. -That object is called “event” in the framework. -An event has a name that allows clients to distinguish it from other -events. - -Events are created using the ***afb\_api\_make\_event*** function -that takes the api that creates the event and the name of the event. -Example: - -```C - event = afb_api_make_event(api, name); -``` - -Once created, the event can be used either to push data to its -subscribers or to broadcast data to any listener. - -The event must be used to establish the subscription for the requesting -client. -This is done using the ***afb\_req\_subscribe*** function -that takes the current request object and event and associates them -together. -Example: - -```C - rc = afb_req_subscribe(req, event); -``` - -When successful, this function make the connection between the event and -the client that emitted the request. -The client becomes a subscriber of the event until it unsubscribes or disconnects. -The ***afb\_req\_subscribe*** function will fail: - -- if the client connection is weak. -- if the request comes from a HTTP link. - -To receive signals, the client must be connected. - -The AGL framework allows connections using WebSocket. - -The name of the event is either a well known name or an ad hoc name -forged for the use case. - -Let's see a basic example: - -- client A expects to receive the speed in km/h every second. -- client B expects the speed in mph twice a second. - -In that case, there are two different events because it is not the same -unit and it is not the same frequency. -Having two different events allows to associate clients to the correct event. -But this doesn't tell any word about the name of these events. -The designer of the signaling agent has two options for naming: - -1. names can be the same (“speed” for example) with sent data - self describing itself or having a specific tag (requiring from - clients awareness about requesting both kinds of speed isn't safe). -1. names of the event include the variations (by example: - “speed-km/h-1Hz” and “speed-mph-2Hz”) and, in that case, sent data - can self describe itself or not. - -In both cases, the signaling agent might have to send the name of the -event and/or an associated tag to its client in the reply of the -subscription. -This is part of the step 5 above. - -The framework only uses the event (not its name) for: - -- subscription -- un-subscription -- pushing - -When the requested data is already generated and the event used for -pushing it already exists, the signaling agent must not instantiate a -new processing chain and must not create a new event object for pushing -data. -The signaling agent must reuse the existing chain and event. - -Unsubscribing is made by the signaling agent on a request of its client. -The ***afb\_req\_unsubscribe*** function tells the framework to -remove the requesting client from the event's list of subscribers. -Example: - -```C - afb_req_unsubscribe(req, event); -``` - -Subscription count does not matter to the framework: - -- Subscribing the same client several times has the same effect that subscribing only one time. - -Thus, when unsubscribing is invoked, it becomes immediately effective. - -#### More on naming events - -- Within the AGL framework, a signaling agent is a binding that has an API prefix. - -This prefix is meant to be unique and to identify the binding API. -The names of the events that this signaling agent creates are -automatically prefixed by the framework, using the API prefix of the -binding. - -Thus, if a signaling agent of API prefix ***api*** creates an event -of name ***event*** and pushes data to that event, the subscribers -will receive an event of name ***api/event***. - -### Generating and pushing signals and data - -- This of the responsibility of the designer of the signaling agent to establish the processing chain for generating events. - -In many cases, this can be achieved using I/O or timer or signal events inserted in the main loop. -For this case, the AGL framework uses **libsystemd** and -provide a way to integrates to the main loop of this library using -afb\_api\_get\_event\_loop. -Example: - -```C - sdev = afb_api_get_event_loop(api); - rc = sd_event_add_io(sdev, &source, fd, EPOLLIN, myfunction, NULL); -``` - -In some other cases, the events are coming from D-Bus. -In that case, the framework also uses **libsystemd** internally to access D-Bus. -It provides two methods to get the available D-Bus objects, already existing and -bound to the main **libsystemd** event loop. -Use either ***afb\_api\_get\_system\_bus*** or -***afb\_api\_get\_user\_bus*** to get the required instance. -Then use functions of **libsystemd** to handle D-Bus. - -In some rare cases, the generation of the data requires to start a new -thread. - -When a data is generated and ready to be pushed, the signaling agent -should call the function ***afb\_event\_push***. -Example: - -```C - rc = afb_event_push(event, JSON); - if (rc == 0) { - stop_generating(event); - afb_event_unref(event); - } -``` - -The function ***afb\_event\_push*** pushes json data to all the subscribers. -It then returns the count of subscribers. -When the count is zero, there is no subscriber listening for the event. -The example above shows that in that case, the signaling agent stops to -generate data for the event and tells that it doesn't use it anymore by calling -**afb\_event\_unref**. - -This is one possible option. -Other valuable options are: - -- do nothing and continue to generate and push the event. -- just stop to generate and push the data but keep the event existing. - -### Receiving the signals - -Understanding what a client expects when it receives signals, events or -data shall be the most important topic of the designer of a signaling -agent. -The good point here is that because JSON[^1] is the exchange -format, structured data can be sent in a flexible way. - -The good design is to allow as much as possible the client to describe -what is needed with the goal to optimize the processing to the -requirements only. - -### The exceptional case of wide broadcast - -Some data or events have so much importance that they can be widely -broadcasted to alert any listening client. -Examples of such an alert are: - -- system is entering/leaving “power safe” mode -- system is shutting down -- the car starts/stops moving -- ... - -An event can be broadcasted using one of the two following methods: - -- ***afb\_api\_broadcast\_event*** -- ***afb\_event\_broadcast*** - -Example 1: - -```C -afb_api_broadcast_event(api, name, json); -``` - -Example 2: - -```C -event = afb_api_make_event(api, name); -. . . . -afb_event_broadcast(event, json); -``` - -As for other events, the name of events broadcasted using -***afb\_api\_broadcast\_event*** are automatically prefixed by -the framework with API prefix. - -## Reference of functions - -See the [references for functions of class afb_event](reference-v3/func-event.html) - -### Function onevent (field of afbBindingExport) - -Binding can designate an event handling function using the field **onevent** -of the structure **afb_binding_t**. - -This function is called when an event is broadcasted or when an event that the -api subscribed to (through call or subcall mechanism) is pushed. -That behavior allows a service to react to an event and do what it is to do if -this is relevant for it. -(ie: car back camera detects imminent collision and broadcast it, then -appropriate service enable parking brake.). - -### Event handlers - -The apis functions allow to declare event handling callbacks. These callbacks are -called on reception of an event matching a pattern and a receive in more that -the event name and its companion JSON data, a user defiend closure and the api -that is used to create it. diff --git a/docs/4_APIs_and_Services/4.3_Application_Framework_Binder/5_Binder_Application_writing_guide/Binder_Application_writing_guide.md b/docs/4_APIs_and_Services/4.3_Application_Framework_Binder/5_Binder_Application_writing_guide/Binder_Application_writing_guide.md deleted file mode 100644 index e995b91..0000000 --- a/docs/4_APIs_and_Services/4.3_Application_Framework_Binder/5_Binder_Application_writing_guide/Binder_Application_writing_guide.md +++ /dev/null @@ -1,328 +0,0 @@ ---- -edit_link: '' -title: Binder Application writing guide -origin_url: >- - https://git.automotivelinux.org/src/app-framework-binder/plain/docs/afb-application-writing.md?h=master ---- - - - -# How to write an application on top of AGL FRAMEWORK - -## Programming Languages for Applications - -### Writing an HTML5 application - -Developers of HTML5 applications (client side) can easily create -applications for AGL framework using their preferred -HTML5 framework. - -Developers may also take advantage of powerful server side bindings to improve -application behavior. -Server side bindings return an application/json mine-type -and can be accessed though either HTTP or Websockets. - -In a near future, JSON-RPC protocol should be added to complete the current -x-afb-json1 protocol. - -Two examples of HTML5 applications are given: - -- [afb-client](https://gerrit.automotivelinux.org/gerrit/gitweb?p=src/app-framework-demo.git;a=tree;f=afb-client) a simple "hello world" application template - -- [afm-client](https://gerrit.automotivelinux.org/gerrit/gitweb?p=src/app-framework-demo.git;a=tree;f=afm-client) a simple "Home screen" application template - -### Writing a Qt application - -Writing Qt applications is also supported. -Qt offers standard API to send request through HTTP or WebSockets. - -It is also possible to write QML applications. -A sample QML application [token-websock] is available: - -- [token-websock](https://gerrit.automotivelinux.org/gerrit/gitweb?p=src/app-framework-binder.git;a=blob;f=test/token-websock.qml) - -A simple "hello world" application in QML - -### Writing a "C" application - -C applications can use afb-daemon binder through a websocket connection. - -The library **libafbwsc** is provided for C clients that need -to connect with an afb-daemon binder. - -The program **afb-client-demo** is the C example that uses the -**libafbwsc** library. -Source code is available here -[src/afb-client-demo.c](https://gerrit.automotivelinux.org/gerrit/gitweb?p=src/app-framework-binder.git;a=blob;f=src/afb-client-demo.c). - -Current implementation relies on libsystemd and file descriptors. -This model may be reviewed in the future to support secure sockets -and get rid of libsystemd dependency. - -### Handling sessions within applications - -Applications should understand sessions and token management when interacting -with afb-daemon binder. - -Applications communicate with their private binder (afb-daemon) using -a network connection or any other potential connection channel. -While the current version does not yet implement Unix socket, -this feature might be added in the near future. -Developers need to be warn that HTTP protocol is a none -connected protocol and that using HTTP socket connection to authenticate -clients is not supported. - -For this reason, the binder should authenticate the application -by using a shared secret. -The secret is named "token" and the identification of client is named "session.” - -The examples **token-websock.qml** and **afb-client** are demonstrating -how authentication and sessions are managed. - -### Handling sessions - -Bindings and other binder features need to keep track of client -instances. -This is especially important for bindings running as services -as they may typically have to keep each client's data separated. - -For HTML5 applications, the web runtime handles the cookie of the session -that the binder afb-daemon automatically sets. - -Session identifier can be set using the parameter **uuid** or **x-afb-uuid** in -URI requests. -Within current version of the framework session UUID is supported -by both HTTP requests and websocket negotiation. - -### Exchanging tokens - -At application start, AGL framework communicates a shared secret to both binder -and client application. -This initial secret is called the "**initial token**". - -For each of its client application, the binder manages a current active -token for session management. -This authentication token can be use to restrict the access to some binding's methods. - -The token must be included in URI request on HTTP or during websockets -connection using parameter **token** or **x-afb-token**. - -To ensure security, tokens must be refreshed periodically. - -### Example of session management - -In following examples, we suppose that **afb-daemon** is launched with something -equivalent to: - -```bash -afb-daemon --port=1234 --token=123456 [...] -``` - -making the expectation that **AuthLogin** binding is requested as default. - -#### Using curl - -First, connects with the initial token, 123456: - -```bash -$ curl http://localhost:1234/api/auth/connect?token=123456 -{ - "jtype": "afb-reply", - "request": { - "status": "success", - "token": "0aef6841-2ddd-436d-b961-ae78da3b5c5f", - "uuid": "850c4594-1be1-4e9b-9fcc-38cc3e6ff015" - }, - "response": {"token": "A New Token and Session Context Was Created"} -} -``` - -It returns an answer containing session UUID, 850c4594-1be1-4e9b-9fcc-38cc3e6ff015, -and a refreshed token, 850c4594-1be1-4e9b-9fcc-38cc3e6ff015. - -Check if session and token is valid: - -```bash -$ curl http://localhost:1234/api/auth/check?token=0aef6841-2ddd-436d-b961-ae78da3b5c5f\&uuid=850c4594-1be1-4e9b-9fcc-38cc3e6ff015 -{ - "jtype": "afb-reply", - "request": {"status":"success"}, - "response": {"isvalid":true} -} -``` - -Refresh the token: - -```bash -$ curl http://localhost:1234/api/auth/refresh?token=0aef6841-2ddd-436d-b961-ae78da3b5c5f\&uuid=850c4594-1be1-4e9b-9fcc-38cc3e6ff015 -{ - "jtype": "afb-reply", - "request": { - "status":"success", - "token":"b8ec3ec3-6ffe-448c-9a6c-efda69ad7bd9" - }, - "response": {"token":"Token was refreshed"} -} -``` - -Close the session: - -```bash -$ curl http://localhost:1234/api/auth/logout?token=b8ec3ec3-6ffe-448c-9a6c-efda69ad7bd9\&uuid=850c4594-1be1-4e9b-9fcc-38cc3e6ff015 -{ - "jtype": "afb-reply", - "request": {"status": "success"}, - "response": {"info":"Token and all resources are released"} -} -``` - -Checking on closed session for uuid should be refused: - -```bash -$ curl http://localhost:1234/api/auth/check?token=b8ec3ec3-6ffe-448c-9a6c-efda69ad7bd9\&uuid=850c4594-1be1-4e9b-9fcc-38cc3e6ff015 -{ - "jtype": "afb-reply", - "request": { - "status": "failed", - "info": "invalid token's identity" - } -} -``` - -#### Using afb-client-demo - -- The program is packaged within AGL in the rpm **libafbwsc-dev** - -Here is an example of exchange using **afb-client-demo**: - -```bash -$ afb-client-demo ws://localhost:1234/api?token=123456 -auth connect -ON-REPLY 1:auth/connect: {"jtype":"afb-reply","request":{"status":"success", - "token":"63f71a29-8b52-4f9b-829f-b3028ba46b68","uuid":"5fcc3f3d-4b84-4fc7-ba66-2d8bd34ae7d1"}, - "response":{"token":"A New Token and Session Context Was Created"}} -auth check -ON-REPLY 2:auth/check: {"jtype":"afb-reply","request":{"status":"success"},"response":{"isvalid":true}} -auth refresh -ON-REPLY 4:auth/refresh: {"jtype":"afb-reply","request":{"status":"success", - "token":"8b8ba8f4-1b0c-48fa-962d-4a00a8c9157e"},"response":{"token":"Token was refreshed"}} -auth check -ON-REPLY 5:auth/check: {"jtype":"afb-reply","request":{"status":"success"},"response":{"isvalid":true}} -auth refresh -ON-REPLY 6:auth/refresh: {"jtype":"afb-reply","request":{"status":"success", - "token":"e83b36f8-d945-463d-b983-5d8ed73ba529"},"response":{"token":"Token was refreshed"}} -``` - -After closing connection, reconnect as here after: - -```bash -$ afb-client-demo ws://localhost:1234/api?token=e83b36f8-d945-463d-b983-5d8ed73ba529\&uuid=5fcc3f3d-4b84-4fc7-ba66-2d8bd34ae7d1 auth check -ON-REPLY 1:auth/check: {"jtype":"afb-reply","request":{"status":"success"},"response":{"isvalid":true}} -``` - -Same connection check using **curl**: - -```bash -$ curl http://localhost:1234/api/auth/check?token=e83b36f8-d945-463d-b983-5d8ed73ba529\&uuid=5fcc3f3d-4b84-4fc7-ba66-2d8bd34ae7d1 -{"jtype":"afb-reply","request":{"status":"success"},"response":{"isvalid":true}} -``` - -### Format of replies - -Replies use javascript object returned as serialized JSON. - -This object contains at least 2 mandatory fields of name **jtype** and -**request** and one optional field of name **response**. - -#### Template of replies - -This is a template of replies: - -```json -{ - "jtype": "afb-reply", - "request": { - "status": "success", - "info": "informationnal text", - "token": "e83b36f8-d945-463d-b983-5d8ed73ba52", - "uuid": "5fcc3f3d-4b84-4fc7-ba66-2d8bd34ae7d1", - "reqid": "application-generated-id-23456" - }, - "response": ....any response object.... -} -``` - -#### Field jtype of replies - -The field **jtype** must have a value of type string equal to **"afb-reply"**. - -#### Field request of replies - -The field **request** must have a value of type object. -This request object has at least one field named **status** -and four optional fields named **info**, **token**, **uuid**, **reqid**. - -##### Subfield request.status - -**status** must have a value of type string. This string is equal to **"success"** -only in case of success. - -##### Subfield request.info - -**info** is of type string and represent optional information added to the reply. - -##### Subfield request.token - -**token** is of type string. It is sent either at session creation -or when the token is refreshed. - -##### Subfield request.uuid - -**uuid** is of type string. It is sent at session creation. - -##### Subfield request.reqid - -**reqid** is of type string. It is sent in response to HTTP requests -that added a parameter of name **reqid** or **x-afb-reqid** at request time. -Value returns in the reply has the exact same value as the one received in the -request. - -#### Field response of replies - -This field response optionally contains an object returned when request -succeeded. - -### Format of events - -Events are javascript object serialized as JSON. - -This object contains at least 2 mandatory fields of name **jtype** and **event** -and one optional field of name **data**. - -#### Template of event - -Here is a template of event: - -```json -{ - "jtype": "afb-event", - "event": "sample_api_name/sample_event_name", - "data": ...any event data... -} -``` - -#### Field jtype of event - -The field **jtype** must have a value of type string equal to **"afb-event"**. - -#### Field event of event - -The field **event** carries the event's name. - -The name of the event is made of two parts separated by a slash: -the name of the name of the API that generated the event -and the name of event within the API. - -#### Field data of event - -This field data if present holds the data carried by the event. diff --git a/docs/4_APIs_and_Services/4.3_Application_Framework_Binder/6_Annexes/1_Migration_to_bindings_v3.md b/docs/4_APIs_and_Services/4.3_Application_Framework_Binder/6_Annexes/1_Migration_to_bindings_v3.md deleted file mode 100644 index edbfe0e..0000000 --- a/docs/4_APIs_and_Services/4.3_Application_Framework_Binder/6_Annexes/1_Migration_to_bindings_v3.md +++ /dev/null @@ -1,209 +0,0 @@ ---- -edit_link: '' -title: Migration to bindings v3 -origin_url: >- - https://git.automotivelinux.org/src/app-framework-binder/plain/docs/afb-migration-to-binding-v3.md?h=master ---- - - - -Migration to binding V3 -======================= - -The ***binding*** interface evolved from version 1 to version 2 -for the following reasons: - -- integration of the security requirements within the bindings -- simplification of the API (after developer feedbacks) -- removal of obscure features and cleanup - -The ***binder*** can run ***bindings*** v1, v2 and/or v3 in any combination. -Thus moving from v1 or v2 to v3 is not enforced at this time. But ... - -In the face to face meeting in Karlsruhe it was decided to remove support -of bindings v1 and to deprecate the use of bindings v2. - -So at the end, **IT IS HIGHLY NEEDED TO SWITCH TO VERSION 3** - -This guide covers the migration of bindings from version 2 to version 3. - -The migration from version 1 is not treated here because bindings version 1 -are very old and probably do not exist anymore. If needed you can refer -to the old [guide to migrate bindings from v1 to v2](legacy/afb-migration-v1-to-v2.html). - - -Differences between version 2 and version 3 -------------------------------------------- - -### in v3 all is api - -The version 3 introduces the concept of "API" that gather what was called before -the daemon and the service. This is the new concept that predates the 2 others. - -The concept of API is intended to allow the definition of multiple APIs -by a same "binding" (a dynamically loaded library). - -Because there is potentially several "API", the functions that were without -context in bindings version 2 need now to tell what API is consumer. - -To be compatible with version 2, bindings v3 still have a default hidden -context: the default API named **afbBindingV3root**. - -To summarize, the functions of class **daemon** and **service** use the default -hidden API. - -It is encouraged to avoid use of functions of class **daemon** and **service**. -You should replace these implicit calls to explicit **api** calls that -reference **afbBindingV3root**. - -Same thing for the logging macros: **AFB_ERROR**, **AFB_WARNING**, -**AFB_NOTICE**, **AFB_INFO**, **AFB_DEBUG** that becomes respectively -**AFB_API_ERROR**, **AFB_API_WARNING**, **AFB_API_NOTICE**, **AFB_API_INFO**, -**AFB_API_DEBUG**. - -Example of 2 equivalent writes: - -```C - AFB_NOTICE("send stress event"); - afb_daemon_broadcast_event(stressed_event, NULL); -``` - -or - -```C - AFB_API_NOTICE(afbBindingV3root, "send stress event"); - afb_api_broadcast_event(afbBindingV3root, stressed_event, NULL); -``` - -### the reply mechanism predates success and fail - -### subcall has more power - -Task list for the migration ---------------------------- - -This task list is: - -1. Use the automatic migration procedure described below -2. Adapt the functions **preinit**, **init** and **onevent** -3. Consider use of the new reply -4. Consider use of the new (sub)call -5. Consider use of event handlers - -The remaining chapters explain these task with more details. - -Automatic migration! --------------------- - -A tiny **sed** script is intended to perform a first pass on the code that -you want to upgrade. It can be done using **curl** and applied using **sed** -as below. - -```bash -BASE=https://git.automotivelinux.org/src/app-framework-binder/plain -SED=migration-to-binding-v3.sed -curl -o $SED $BASE/docs/$SED -sed -i -f $SED file1 file2 file3... -``` - -You can also follow -[this link](https://git.automotivelinux.org/src/app-framework-binder/plain/docs/migration-to-binding-v3.sed) -and save the file. - -This automatic action does most of the boring job but not all the job. -The remaining of this guide explains the missing part. - -Adapt the functions preinit, init and onevent ----------------------------------------------- - -The signature of the functions **preinit**, **init** and **onevent** changed -to include the target api. - -The functions of the v2: - -```C -int (*preinit)(); -int (*init)(); -void (*onevent)(const char *event, struct json_object *object); -``` - -Gain a new first argument of type **afb_api_t** as below: - -```C -int (*preinit)(afb_api_t api); -int (*init)(afb_api_t api); -void (*onevent)(afb_api_t api, const char *event, struct json_object *object); -``` - -For the migration, it is enough to just add the new argument without -using it. - -Consider use of the new reply ------------------------------ - -The v3 allows error reply with JSON object. To achieve it, an unified -reply function's family is introduced: - -```C -void afb_req_reply(afb_req_t req, json_object *obj, const char *error, const char *info); -void afb_req_reply_v(afb_req_t req, json_object *obj, const char *error, const char *info, va_list args); -void afb_req_reply_f(afb_req_t req, json_object *obj, const char *error, const char *info, ...); -``` - -The functions **success** and **fail** are still supported. -These functions are now implemented as the following macros: - - -```C -#define afb_req_success(r,o,i) afb_req_reply(r,o,NULL,i) -#define afb_req_success_f(r,o,...) afb_req_reply_f(r,o,NULL,__VA_ARGS__) -#define afb_req_success_v(r,o,f,v) afb_req_reply_v(r,o,NULL,f,v) -#define afb_req_fail(r,e,i) afb_req_reply(r,NULL,e,i) -#define afb_req_fail_f(r,e,...) afb_req_reply_f(r,NULL,e,__VA_ARGS__) -#define afb_req_fail_v(r,e,f,v) afb_req_reply_v(r,NULL,e,f,v) -``` - -This is a decision of the developer to switch to the new family -**afb_req_reply** or to keep the good old functions **afb_req_fail** -adn **afb_req_success**. - -Consider use of the new (sub)call ---------------------------------- - -The new call and subcall (the functions **afb_api_call**, **afb_api_call_sync**, -**afb_req_subcall** and **afb_req_subcall_sync**) functions are redesigned -to better fit the new reply behaviour. In most case the developer will benefit -of the new behavior that directly gives result and error without enforcing -to parse the JSON object result. - -The subcall functions are also fully redesigned to allow precise handling -of the context and event subscriptions. The new design allows you to specify: - - - whether the subcall is made in the session of the caller or in the session - of the service - - whether the credentials to use are those of the caller or those of the - service - - whether the caller or the service or both or none will receive the - eventually events during the subcall. - -See [calls](reference-v3/func-api.html#calls-and-job-functions) and -[subcalls](reference-v3/func-req.html#subcall-functions). - -The table below list the changes to apply: - -| Name in Version 2 | New name of Version 3 -|:----------------------:|:----------------------------------------------------: -| afb_req_subcall | afb_req_subcall_legacy -| afb_req_subcall_sync | afb_req_subcall_sync_legacy -| afb_service_call | afb_service_call_legacy -| afb_service_call_sync | afb_service_call_sync_legacy -| afb_req_subcall_req | afb_req_subcall_req (same but obsolete) - - -Consider use of event handlers ------------------------------- - -Binding V3 brings new ways of handling event in services. You can register -functions that will handle specific events and that accept closure arguments. - -See [**afb_api_event_handler_add** and **afb_api_event_handler_del**](reference-v3/func-api.html#event-functions) diff --git a/docs/4_APIs_and_Services/4.3_Application_Framework_Binder/6_Annexes/2_WebSocket_protocol_x-afb-ws-json1.md b/docs/4_APIs_and_Services/4.3_Application_Framework_Binder/6_Annexes/2_WebSocket_protocol_x-afb-ws-json1.md deleted file mode 100644 index 431b41f..0000000 --- a/docs/4_APIs_and_Services/4.3_Application_Framework_Binder/6_Annexes/2_WebSocket_protocol_x-afb-ws-json1.md +++ /dev/null @@ -1,315 +0,0 @@ ---- -edit_link: '' -title: WebSocket protocol x-afb-ws-json1 -origin_url: >- - https://git.automotivelinux.org/src/app-framework-binder/plain/docs/protocol-x-afb-ws-json1.md?h=master ---- - - - -# The websocket protocol x-afb-ws-json1 - -The WebSocket protocol *x-afb-ws-json1* is used to communicate between -an application and a binder. It allows access to all registered apis -of the binder. - -This protocol is inspired from the protocol **OCPP - SRPC** as described for -example here: -[OCPP transport specification - SRPC over WebSocket](http://www.gir.fr/ocppjs/ocpp_srpc_spec.shtml). - -The registration to the IANA is still to be done, see: -[WebSocket Protocol Registries](https://www.iana.org/assignments/websocket/websocket.xml) - -This document gives a short description of the protocol *x-afb-ws-json1*. -A more formal description has to be done. - -## Architecture - -The protocol is intended to be symmetric. It allows: - -- to CALL a remote procedure that returns a result -- to push and receive EVENT - -## Messages - -Valid messages are made of *text* frames that are all valid JSON. - -Valid messages are: - -Calls: - -```txt -[ 2, ID, PROCN, ARGS ] -[ 2, ID, PROCN, ARGS, TOKEN ] -``` - -Replies (3: OK, 4: ERROR): - -```txt -[ 3, ID, RESP ] -[ 4, ID, RESP ] -``` - -Events: - -```txt -[ 5, EVTN, OBJ ] -``` - -Where: - -| Field | Type | Description -|-------|--------|------------------ -| ID | string | A string that identifies the call. A reply to that call use the ID of the CALL. -| PROCN | string | The procedure name to call of the form "api/verb" -| ARGS | any | Any argument to pass to the call (see afb_req_json that returns it) -| RESP | any | The response to the call -| TOKEN | string | The authorisation token -| EVTN | string | Name of the event in the form "api/event" -| OBJ | any | The companion object of the event - -Below, an example of exchange: - -```txt -C->S: [2,"156","hello/ping",null] -S->C: [3,"156",{"response":"Some String","jtype":"afb-reply","request":{"status":"success","info":"Ping Binder Daemon tag=pingSample count=1 query=\"null\"","uuid":"ec30120c-6997-4529-9d63-c0de0cce56c0"}}] -``` - -## History - -### 14 November 2019 - -Removal of token returning. The replies - -```txt -[ 3, ID, RESP, TOKEN ] -[ 4, ID, RESP, TOKEN ] -``` - -are removed from the specification. - -## Future - -Here are the planned extensions: - -- add binary messages with cbor data -- add calls with unstructured replies - -This could be implemented by extending the current protocol or by -allowing the binder to accept either protocol including the new ones. - -## Javascript implementation - -The file **AFB.js** is a javascript implementation of the protocol. - -Here is that code: - -```javascript -/* - * Copyright (C) 2017-2019 "IoT.bzh" - * Author: José Bollo - * - * Licensed under the Apache License, Version 2.0 (the "License"); - * you may not use this file except in compliance with the License. - * You may obtain a copy of the License at - * - * http://www.apache.org/licenses/LICENSE-2.0 - * - * Unless required by applicable law or agreed to in writing, software - * distributed under the License is distributed on an "AS IS" BASIS, - * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. - * See the License for the specific language governing permissions and - * limitations under the License. - */ -AFB = function(base, initialtoken){ - -if (typeof base != "object") - base = { base: base, token: initialtoken }; - -var initial = { - base: base.base || "api", - token: base.token || initialtoken || "HELLO", - host: base.host || window.location.host, - url: base.url || undefined -}; - -var urlws = initial.url || "ws://"+initial.host+"/"+initial.base; - -/*********************************************/ -/**** ****/ -/**** AFB_context ****/ -/**** ****/ -/*********************************************/ -var AFB_context; -{ - var UUID = undefined; - var TOKEN = initial.token; - - var context = function(token, uuid) { - this.token = token; - this.uuid = uuid; - } - - context.prototype = { - get token() {return TOKEN;}, - set token(tok) {if(tok) TOKEN=tok;}, - get uuid() {return UUID;}, - set uuid(id) {if(id) UUID=id;} - }; - - AFB_context = new context(); -} -/*********************************************/ -/**** ****/ -/**** AFB_websocket ****/ -/**** ****/ -/*********************************************/ -var AFB_websocket; -{ - var CALL = 2; - var RETOK = 3; - var RETERR = 4; - var EVENT = 5; - - var PROTO1 = "x-afb-ws-json1"; - - AFB_websocket = function(on_open, on_abort) { - var u = urlws; - if (AFB_context.token) { - u = u + '?x-afb-token=' + AFB_context.token; - if (AFB_context.uuid) - u = u + '&x-afb-uuid=' + AFB_context.uuid; - } - this.ws = new WebSocket(u, [ PROTO1 ]); - this.url = u; - this.pendings = {}; - this.awaitens = {}; - this.counter = 0; - this.ws.onopen = onopen.bind(this); - this.ws.onerror = onerror.bind(this); - this.ws.onclose = onclose.bind(this); - this.ws.onmessage = onmessage.bind(this); - this.onopen = on_open; - this.onabort = on_abort; - } - - function onerror(event) { - var f = this.onabort; - if (f) { - delete this.onopen; - delete this.onabort; - f && f(this); - } - this.onerror && this.onerror(this); - } - - function onopen(event) { - var f = this.onopen; - delete this.onopen; - delete this.onabort; - f && f(this); - } - - function onclose(event) { - for (var id in this.pendings) { - try { this.pendings[id][1](); } catch (x) {/*TODO?*/} - } - this.pendings = {}; - this.onclose && this.onclose(); - } - - function fire(awaitens, name, data) { - var a = awaitens[name]; - if (a) - a.forEach(function(handler){handler(data);}); - var i = name.indexOf("/"); - if (i >= 0) { - a = awaitens[name.substring(0,i)]; - if (a) - a.forEach(function(handler){handler(data);}); - } - a = awaitens["*"]; - if (a) - a.forEach(function(handler){handler(data);}); - } - - function reply(pendings, id, ans, offset) { - if (id in pendings) { - var p = pendings[id]; - delete pendings[id]; - try { p[offset](ans); } catch (x) {/*TODO?*/} - } - } - - function onmessage(event) { - var obj = JSON.parse(event.data); - var code = obj[0]; - var id = obj[1]; - var ans = obj[2]; - AFB_context.token = obj[3]; - switch (code) { - case RETOK: - reply(this.pendings, id, ans, 0); - break; - case RETERR: - reply(this.pendings, id, ans, 1); - break; - case EVENT: - default: - fire(this.awaitens, id, ans); - break; - } - } - - function close() { - this.ws.close(); - this.ws.onopen = - this.ws.onerror = - this.ws.onclose = - this.ws.onmessage = - this.onopen = - this.onabort = function(){}; - } - - function call(method, request, callid) { - return new Promise((function(resolve, reject){ - var id, arr; - if (callid) { - id = String(callid); - if (id in this.pendings) - throw new Error("pending callid("+id+") exists"); - } else { - do { - id = String(this.counter = 4095 & (this.counter + 1)); - } while (id in this.pendings); - } - this.pendings[id] = [ resolve, reject ]; - arr = [CALL, id, method, request ]; - if (AFB_context.token) arr.push(AFB_context.token); - this.ws.send(JSON.stringify(arr)); - }).bind(this)); - } - - function onevent(name, handler) { - var id = name; - var list = this.awaitens[id] || (this.awaitens[id] = []); - list.push(handler); - } - - AFB_websocket.prototype = { - close: close, - call: call, - onevent: onevent - }; -} -/*********************************************/ -/**** ****/ -/**** ****/ -/**** ****/ -/*********************************************/ -return { - context: AFB_context, - ws: AFB_websocket -}; -}; -``` diff --git a/docs/4_APIs_and_Services/4.3_Application_Framework_Binder/6_Annexes/3_Installing_the_binder_on_a_desktop.md b/docs/4_APIs_and_Services/4.3_Application_Framework_Binder/6_Annexes/3_Installing_the_binder_on_a_desktop.md deleted file mode 100644 index 7c680ed..0000000 --- a/docs/4_APIs_and_Services/4.3_Application_Framework_Binder/6_Annexes/3_Installing_the_binder_on_a_desktop.md +++ /dev/null @@ -1,51 +0,0 @@ ---- -edit_link: '' -title: Installing the binder on a desktop -origin_url: >- - https://git.automotivelinux.org/src/app-framework-binder/plain/docs/afb-desktop-package.md?h=master ---- - - - -# Desktop packages for binder development - -Packages of the ***binder*** (afb-daemon)exist -for common desktop linux distributions. - -- Fedora -- Ubuntu -- Debian -- Suse - -Installing the development package of the ***binder*** -allows to write ***bindings*** that runs on the desktop -computer of the developer. - -It is very convenient to quickly write and debug a binding. - -## Retrieving compiling option with pkg-config - -The ***binder*** afb-daemon provides a configuration -file for **pkg-config**. -Typing the command - -```bash -pkg-config --cflags afb-daemon -``` - -Print flags use for compilation: - -```bash -$ pkg-config --cflags afb-daemon --I/opt/local/include -I/usr/include/json-c -``` - -For linking, you should use - -```bash -$ pkg-config --libs afb-daemon --ljson-c -``` - -It automatically includes the dependency to json-c. -This is activated through **Requires** keyword in pkg-config. diff --git a/docs/4_APIs_and_Services/4.3_Application_Framework_Binder/6_Annexes/4_Options_of_afb-daemon.md b/docs/4_APIs_and_Services/4.3_Application_Framework_Binder/6_Annexes/4_Options_of_afb-daemon.md deleted file mode 100644 index c109b62..0000000 --- a/docs/4_APIs_and_Services/4.3_Application_Framework_Binder/6_Annexes/4_Options_of_afb-daemon.md +++ /dev/null @@ -1,363 +0,0 @@ ---- -edit_link: '' -title: Options of afb-daemon -origin_url: >- - https://git.automotivelinux.org/src/app-framework-binder/plain/docs/afb-daemon-options.md?h=master ---- - - - -# Launching options of afb-daemon - -The launch options for binder **afb-daemon** are: - -``` - -v, --verbose Verbose Mode, repeat to increase verbosity - -c, --color Colorize the ouput - -q, --quiet Quiet Mode, repeat to decrease verbosity - -l, --log=xxxx Tune log level - --foreground Get all in foreground mode - --background Get all in background mode - -D, --daemon Get all in background mode - -n, --name=xxxx Set the visible name - -p, --port=xxxx HTTP listening TCP port [default 1234] - --roothttp=xxxx HTTP Root Directory [default no root http (files not served but apis still available)] - --rootbase=xxxx Angular Base Root URL [default /opa] - --rootapi=xxxx HTML Root API URL [default /api] - --alias=xxxx Multiple url map outside of rootdir [eg: --alias=/icons:/usr/share/icons] - --apitimeout=xxxx Binding API timeout in seconds [default 20] - --cntxtimeout=xxxx Client Session Context Timeout [default 32000000] - --cache-eol=xxxx Client cache end of live [default 100000] - -w, --workdir=xxxx Set the working directory [default: $PWD or current working directory] - -u, --uploaddir=xxxx Directory for uploading files [default: workdir] relative to workdir - --rootdir=xxxx Root Directory of the application [default: workdir] relative to workdir - --ldpaths=xxxx Load bindings from dir1:dir2:... [default: path of afb-dbus-binding.so] - -b, --binding=xxxx Load the binding of path - --weak-ldpaths=xxxx Same as --ldpaths but ignore errors - --no-ldpaths Discard default ldpaths loading - -t, --token=xxxx Initial Secret [default=random, use --token= to allow any token] - -r, --random-token Enforce a random token - -V, --version Display version and copyright - -h, --help Display this help - --ws-client=xxxx Bind to an afb service through websocket - --ws-server=xxxx Provide an afb service through websockets - -A, --auto-api=xxxx Automatic load of api of the given directory - --session-max=xxxx Max count of session simultaneously [default 200] - --tracereq=xxxx Log the requests: no, common, extra, all - --traceevt=xxxx Log the events: no, common, extra, all - --traceses=xxxx Log the sessions: no, all - --traceapi=xxxx Log the apis: no, common, api, event, all - --traceglob=xxxx Log the globals: none, all - --traceditf=xxxx Log the daemons: no, common, all - --tracesvc=xxxx Log the services: no, all - --call=xxxx call at start, format of val: API/VERB:json-args - --no-httpd Forbid HTTP service - -e, --exec Execute the remaining arguments - -M, --monitoring Enable HTTP monitoring at /monitoring/ - -C, --config=xxxx Load options from the given config file - -Z, --dump-config Dump the config to stdout and exit - -s, --set=xxxx Set parameters ([API]/[KEY]:JSON or {"API":{"KEY":JSON}} - -o, --output=xxxx Redirect stdout and stderr to output file (when --daemon) - --trap-faults=xxxx Trap faults: on, off, yes, no, true, false, 1, 0 (default: true) -``` - -## help - -Prints help with available options - -## version - -Display version and copyright - -## verbose - -Increases the verbosity, can be repeated - -## color - -Add basic colorization to the ouput. - -## quiet - -Decreases the verbosity, can be repeated - -## log=xxxx - -Tune the log level mask. The levels are: - - - error - - warning - - notice - - info - - debug - -The level can be set using + or -. - -| Examples | descritpion -|-----------------|------------------- -| error,warning | selects only the levels error and warning -| +debug | adds level debug to the current verbosity -| -warning | remove the level warning from the current verbosity -| +warning-debug,info | Adds error and remove errors and warnings - -## port=xxxx - -HTTP listening TCP port [default 1234] - -## workdir=xxxx - -Directory where the daemon must run [default: $PWD if defined -or the current working directory] - -## uploaddir=xxxx - -Directory where uploaded files are temporarily stored [default: workdir] - -## rootdir=xxxx - -Root directory of the application to serve [default: workdir] - -## roothttp=xxxx - -Directory of HTTP served files. If not set, files are not served -but apis are still accessible. - -## rootbase=xxxx - -Angular Base Root URL [default /opa] - -This is used for any application of kind OPA (one page application). -When set, any missing document whose url has the form /opa/zzz -is translated to /opa/#!zzz - -## rootapi=xxxx - -HTML Root API URL [default /api] - -The bindings are available within that url. - -## alias=xxxx - -Maps a path located anywhere in the file system to the -a subdirectory. The syntax for mapping a PATH to the -subdirectory NAME is: --alias=/NAME:PATH. - -Example: --alias=/icons:/usr/share/icons maps the -content of /usr/share/icons within the subpath /icons. - -This option can be repeated. - -## apitimeout=xxxx - -binding API timeout in seconds [default 20] - -Defines how many seconds maximum a method is allowed to run. -0 means no limit. - -## cntxtimeout=xxxx - -Client Session Timeout in seconds [default 32000000 that is 1 year] - -## cache-eol=xxxx - -Client cache end of live [default 100000 that is 27,7 hours] - -## session-max=xxxx - -Maximum count of simultaneous sessions [default 200] - -## ldpaths=xxxx - -Load bindings from given paths separated by colons -as for dir1:dir2:binding1.so:... [default = $libdir/afb] - -You can mix path to directories and to bindings. -The sub-directories of the given directories are searched -recursively. - -The bindings are the files terminated by '.so' (the extension -so denotes shared object) that contain the public entry symbol. - -## weak-ldpaths=xxxx - -Same as --ldpaths but instead of stopping on error, ignore errors and continue. - -## binding=xxxx - -Load the binding of given path. - -## token=xxxx - -Initial Secret token to authenticate. - -If not set, no client can authenticate. - -If set to the empty string, then any initial token is accepted. - -## random-token - -Generate a random starting token. See option --exec. - -## ws-client=xxxx - -Transparent binding to a binder afb-daemon service through a WebSocket. - -The value of xxxx is either a unix naming socket, of the form "unix:path/api", -or an internet socket, of the form "host:port/api". - -## ws-server=xxxx - -Provides a binder afb-daemon service through WebSocket. - -The value of xxxx is either a unix naming socket, of the form "unix:path/api", -or an internet socket, of the form "host:port/api". - -## foreground - -Get all in foreground mode (default) - -## daemon - -Get all in background mode - -## no-httpd - -Forbids HTTP serve - -## exec - -Must be the last option for afb-daemon. The remaining -arguments define a command that afb-daemon will launch. -The sequences @p, @t and @@ of the arguments are replaced -with the port, the token and @. - -## tracereq=xxxx - -Trace the processing of requests in the log file. - -Valid values are 'no' (default), 'common', 'extra' or 'all'. - -## traceapi=xxxx - -Trace the accesses to functions of class api. - -Valid values are 'no' (default), 'common', 'api', 'event' or 'all'. - -## traceevt=xxxx - -Trace the accesses to functions of class event. - -Valid values are 'no' (default), 'common', 'extra' or 'all'. - -## call=xxx - -Call a binding at start (can be be repeated). -The values are given in the form API/VERB:json-args. - -Example: --call 'monitor/set:{"verbosity":{"api":"debug"}}' - -## monitoring - -Enable HTTP monitoring at /monitoring/ - -## name=xxxx - -Set the visible name - -## auto-api=xxxx - -Automatic activation of api of the given directory when the api is missing. - -## config=xxxx - -Load options from the given config file - -This can be used instead of arguments on the command line. - -Example: - - afb-daemon \ - --no-ldpaths \ - --binding /home/15646/bindings/binding45.so \ - --binding /home/15646/bindings/binding3.so \ - --tracereq common \ - --port 5555 \ - --token SPYER \ - --set api45/key:54027a5e3c6cb2ca5ddb97679ce32f185b067b0a557d16a8333758910bc25a72 \ - --exec /home/15646/bin/test654 @p @t - -is equivalent to: - - afb-daemon --config /home/15646/config1 - -when the file **/home/15646/config1** is: - - { - "no-ldpaths": true, - "binding": [ - "\/home\/15646\/bindings\/binding45.so", - "\/home\/15646\/bindings\/binding3.so" - ], - "tracereq": "common", - "port": 5555, - "token": "SPYER", - "set" : { - "api45": { - "key": "54027a5e3c6cb2ca5ddb97679ce32f185b067b0a557d16a8333758910bc25a72" - } - }, - "exec": [ - "\/home\/15646\/bin\/test654", - "@p", - "@t" - ] - } - -The options are the keys of the config object. - -See option --dump-config - -## dump-config - -Output a JSON representation of the configuration resulting from -environment and options. - -## output=xxxx - -Redirect stdout and stderr to output file - -## set=xxxx - -Set values that can be retrieved by bindings. - -The set value can have different formats. - -The most generic format is **{"API1":{"KEY1":VALUE,"KEY2":VALUE2,...},"API2":...}** - -This example set 2 keys for the api *chook*: - - afb-daemon -Z --set '{"chook":{"account":"urn:chook:b2ca5ddb97679","delay":500}}' - { - "set": { - "chook": { - "account": "urn:chook:b2ca5ddb97679", - "delay": 500 - } - } - } - -An other format is: **[API]/[KEY]:VALUE**. -When API is omitted, it take the value "*". -When KEY is ommitted, it take the value of "*". - -The settings for the API \* are globals and apply to all bindings. - -The settings for the KEY \* are mixing the value for the API. - -The following examples are all setting the same values: - - afb-daemon --set '{"chook":{"account":"urn:chook:b2ca5ddb97679","delay":500}}' - afb-daemon --set 'chook/*:{"account":"urn:chook:b2ca5ddb97679","delay":500}' - afb-daemon --set 'chook/:{"account":"urn:chook:b2ca5ddb97679","delay":500}' - afb-daemon --set 'chook/account:"urn:chook:b2ca5ddb97679"' --set chook/delay:500 - diff --git a/docs/4_APIs_and_Services/4.3_Application_Framework_Binder/6_Annexes/5_Debuggin_binder_and_bindings.md b/docs/4_APIs_and_Services/4.3_Application_Framework_Binder/6_Annexes/5_Debuggin_binder_and_bindings.md deleted file mode 100644 index 12de531..0000000 --- a/docs/4_APIs_and_Services/4.3_Application_Framework_Binder/6_Annexes/5_Debuggin_binder_and_bindings.md +++ /dev/null @@ -1,45 +0,0 @@ ---- -edit_link: '' -title: Debugging binder and bindings -origin_url: >- - https://git.automotivelinux.org/src/app-framework-binder/plain/docs/afb-daemon-debugging.md?h=master ---- - - - -# Debugging binder and bindings - -When compiled with the symbol AGL_DEVEL defined, the ***binder*** -understands the 2 configuration variables: - - - AFB_DEBUG_BREAK: to emit interrupts - - AFB_DEBUG_WAIT: to wait interrupts - -To use these variables, assign it the list of break or wait points -to reach. - -Example: - -```bash -$ AFB_DEBUG_BREAK=main-entry AFB_DEBUG_WAIT=start-load,start-exec afb-daemon .... -``` - -This tells to ***afb-daemon*** to break at the point **main-entry** and to -wait at the points **start-load** and **start-exec**. - -The items of the list can be separated using comma, space, tab or new-line. - -The break/wait points are, in the order of their occurrence: - -- main-entry: before decode arguments -- main-args: before daemon setup -- main-start: before starting jobs -- start-entry: before initialisation of sessions and hooks -- start-load: before load and pre-init of bindings -- start-start: before init of bindings -- start-http: before start of http server -- start-call: before execution of requests of the command line (option --call) -- start-exec: before execution of child preocees - -Note also that a call to 'personality' is inserted just after -the point start-start. diff --git a/docs/4_APIs_and_Services/4.3_Application_Framework_Binder/6_Annexes/6_LEGACY_Migration_from_v1_to_v2.md b/docs/4_APIs_and_Services/4.3_Application_Framework_Binder/6_Annexes/6_LEGACY_Migration_from_v1_to_v2.md deleted file mode 100644 index 54286e9..0000000 --- a/docs/4_APIs_and_Services/4.3_Application_Framework_Binder/6_Annexes/6_LEGACY_Migration_from_v1_to_v2.md +++ /dev/null @@ -1,664 +0,0 @@ ---- -edit_link: '' -title: LEGACY Migration from v1 to v2 -origin_url: >- - https://git.automotivelinux.org/src/app-framework-binder/plain/docs/legacy/afb-migration-v1-to-v2.md?h=master ---- - - - -[LEGACY] Migration from binding V1 to binding V2 -======================================= - -> LEGACY!!! IT IS NOT EXPECTED THAT YOU STILL NEED THIS GUIDE. -> -> THIS GUIDE WILL BE REMOVED IN A NEAR FUTURE - - -The ***binding*** interface evolved from version 1 to version 2 -for the following reasons: - -- integration of the security requirements within the bindings -- simplification of the API (after developer feedbacks) -- removal of obscure features, cleanup - -The ***binder*** can run ***bindings*** v1 and/or v2 in any combination. -Thus moving from v1 to v2 is not enforced, there is no real need. - -More, it is possible to write a dual ***binding***: - -- a ***binding*** that implements the version 1 and the version 2. - -However, IT IS HIGHLY RECOMMENDED TO SWITCH TO ONLY VERSION 2: - -- any new development SHOULD start using ***binding*** V2 -- existing ***bindings*** SHOULD migrate to the version 2 - -This guide covers the migration of bindings from version 1 to version 2. - -It also explains some of the rationale taken when migrating from version 1 to version 2. - -In the future, if ***binding*** api evolves to fresh versions (3, 4, ...) -it might be necessarily to write bindings implementing more than -just one version. -For example: - -- a ***binding*** being v2 AND v3 will resolve the issue of running on older and newer version of AGL. - -This should always be possible even if more complicated. - -Important things to known when migrating ----------------------------------------- - -One of the most important change when migrating from v1 to v2 is -that many functions use an hidden *common* variable. -This affects the functions of the following classes: - -- functions of class **daemon**: - - functions starting with **afb_daemon_...** - - functions for logging: **ERROR**, **WARNING**, **NOTICE**, **INFO**, **DEBUG** -- functions of class **service**: - - functions starting with **afb_service_...** -- callback functions: - - the register function (that is removed) - - the service init function - - the onevent function - -For these functions, the first parameter is now implicit. - -Let takes an example. -For ***binding*** v1 you had to write: - -```C - afb_daemon_broadcast_event(afbitf->daemon, reason, description); -``` - -For ***binding*** v2, you simply write: - -```C - afb_daemon_broadcast_event(reason, description); -``` - -This simplification is possible because the header files included for the bindings -now provide a common variable for storing the **daemon** and **service** data. - -As a programmer, you shouldn't care much about that hidden variable. -It simplifies the job, that's all and that is the reason of the change. - -An other important difference is between the version 1 and the version 2 is -on how the ***binding***'s **API** is documented. -The version 2 emphasis the **OpenAPI v3** description of the **API**. -For this reason, to avoid duplication of descriptions, only one description is expected: - -- The **OpenAPI** one. - -Task list for the migration ---------------------------- - -This task list is: - -1. Enforce use of binding v2 by setting **AFB_BINDING_VERSION** -1. Rewrite the main structure and the list of exported verbs -1. Adapt the init and callback functions -1. Removes the first parameter of functions of classes **daemon** and **service** -1. Consider where to emit logs for requests -1. Take care of store/unstore changes -1. Consider use of synchronous (sub)call requests -1. Optionally, removes explicit struct - -The remaining chapters explain these task with more details. - -Enforce use of binding v2 by setting AFB_BINDING_VERSION --------------------------------------------------------- - -By defining **AFB_BINDING_VERSION** to **2** you switch to version 2. -This is done as below. - -```C -#define AFB_BINDING_VERSION 2 -#include -``` - -After that you will get many errors when compiling. - -Rewrite the main structures and the list of exported verbs ---------------------------------------------------------- - -The structures describing the ***binding** changed from version 1 to version 2. - -The structure for describing verbs changed to include security -requirements. - -In version 1 it was: - -```C -struct afb_verb_desc_v1 -{ - const char *name; /* name of the verb */ - enum afb_session_flags_v1 session; /* authorization and session requirements of the verb */ - void (*callback)(struct afb_req req); /* callback function implementing the verb */ - const char *info; /* textual description of the verb */ -}; -``` - -In version 2 it becomes: - -```C -struct afb_verb_v2 -{ - const char *verb; /* name of the verb */ - void (*callback)(struct afb_req req); /* callback function implementing the verb */ - const struct afb_auth *auth; /* required authorization */ - uint32_t session; /* authorization and session requirements of the verb */ -}; - -``` - -The migration of instances of that structure requires the following actions: - -- rename field **name** to **verb** -- remove field **info** -- adapt field **session** if needed -- set field **auth** to NULL - -Example: - -```C - { .name= "new", .session= AFB_SESSION_NONE, .callback= new, .info= "Starts a new game" } -``` - -Becomes - -```C - { .verb = "new", .session = AFB_SESSION_NONE, .callback = new, .auth = NULL } -``` - -The field **auth** can be set to a value describing the requested -authorization. - -The main describing structure also changed. - -In version 1 it was: - -```C -struct afb_binding_desc_v1 -{ - const char *info; /* textual information about the binding */ - const char *prefix; /* required prefix name for the binding */ - const struct afb_verb_desc_v1 *verbs; /* array of descriptions of verbs terminated by a NULL name */ -}; -``` - -In version 2 it becomes: - -```C -struct afb_binding_v2 -{ - const char *api; /* api name for the binding */ - const char *specification; /* textual specification of the binding */ - const struct afb_verb_v2 *verbs; /* array of descriptions of verbs terminated by a NULL name */ - int (*preinit)(); /* callback at load of the binding */ - int (*init)(); /* callback for starting the service */ - void (*onevent)(const char *event, struct json_object *object); /* callback for handling events */ - unsigned noconcurrency: 1; /* avoids concurrent requests to verbs */ -}; -``` - -The migration of instances of that structure requires the following actions: - -- declare, explore, name the structure as ```const struct afb_binding_v2 afbBindingV2``` -- rename the field **prefix** to **api** -- remove the field **info** -- setup the fields **preinit**, **init**, **onevent** according to the next section -- set the field **noconcurrency** to the right value: - - to 1 if you want to avoid concurrent calls to verbs. - - to 0 if you allow concurrent calls to verbs. - -Example: - -```C -static const struct afb_binding plugin_desc = { - .type = AFB_BINDING_VERSION_1, - .v1 = { - .info = "Minimal Hello World Sample", - .prefix = "hello", - .verbs = verbs - } -``` - -Becomes: - -```C -const struct afb_binding_v2 afbBindingV2 = { - .api = "hello", - .specification = NULL, - .verbs = verbs, - .preinit = preinit, - .init = init -}; -``` - -The **binder** now relies only on the exported names -to deduce the type of the binding. -This make the main structure more simple. - -Adapt the init and callback functions -------------------------------------- - -The ***bindings*** version 1 defined 3 exported functions: - -- **afbBindingV1Register** -- **afbBindingV1ServiceInit** -- **afbBindingV1ServiceEvent** - -These function should not be exported any more and there definition changed. - -The function **afbBindingV1Register** is no more used to describe the binding. -When a binding has to take actions when it is loaded, it must set the field -**preinit** of the structure **afbBindingV2**. -This field, this preinit, might be used to check features at load. -When it returns a negative number, the ***binder*** stops before initializing any ***binding***. - -The function **afbBindingV1ServiceInit** is replaced by the field **init** -of the structure **afbBindingV2**. -The init function should return 0 in case of success or a negative error code -in case of problem. -It is called during initialization of services. - -The function **afbBindingV1ServiceEvent**is replaced by the field **onevent** -of the structure **afbBindingV2**. - -The two functions **afbBindingV1Register** and **afbBindingV1ServiceInit**, -were taking as parameter the ***binder*** interface and the service interface respectively. -These interfaces are now managed hiddenly for the **binding** by the **binder**. -So the variable that ***bindings*** version used to store the ***binder*** interface -and the service interface are no more needed and can be removed. - -Example: - -```C -const struct afb_binding_interface *interface; -struct afb_service service; - -static const struct afb_binding plugin_desc = { - .type = AFB_BINDING_VERSION_1, - .v1 = { - .info = "Minimal Hello World Sample", - .prefix = "hello", - .verbs = verbs - } -} - -const struct afb_binding *afbBindingV1Register (const struct afb_binding_interface *itf) -{ - interface = itf; - NOTICE(interface, "binding register"); - return &plugin_desc; -} - -int afbBindingV1ServiceInit(struct afb_service svc) -{ - service = svc; - NOTICE(interface, "binding init"); - return 0; -} - -void afbBindingV1ServiceEvent(const char *event, struct json_object *object) -{ - NOTICE(interface, "onevent %s", event); -} -``` - -Becomes: - -```C -static int preinit() -{ - AFB_NOTICE("binding preinit (was register)"); - return 0; -} - -static int init() -{ - AFB_NOTICE("binding init"); - return 0; -} - -static void onevent(const char *event, struct json_object *object) -{ - AFB_NOTICE("onevent %s", event); -} - -const struct afb_binding_v2 afbBindingV2 = { - .api = "hello", - .specification = NULL, - .verbs = verbs, - .preinit = preinit, - .init = init, - .onevent = onevent -}; -``` - -The two functions **afbBindingV1Register** and **afbBindingV1ServiceInit**, -were taking as parameter the ***binder*** interface and the service interface respectively. -These interfaces are now managed hiddenly for the **binding** by the **binder**. -So the variable that ***bindings*** version used to store the ***binder*** interface -and the service interface are no more needed and can be removed. - -On the above example the following lines were removed: - -```C -const struct afb_binding_interface *interface; -struct afb_service service; - - interface = itf; - - service = svc; -``` - -Removes the first parameter of functions of classes **daemon** and **service** ------------------------------------------------------------------------------- - -As explained before, many functions loose there first -arguments, this are the functions of the following classes: - -- functions of class **daemon**: - - functions starting with **afb_daemon_...** - - functions for logging: **ERROR**, **WARNING**, **NOTICE**, **INFO**, **DEBUG** -- functions of class **service**: - - functions starting with **afb_service_...** -- callback functions: - - the register function (that is removed) - - the service init function - - the onevent function - -For these functions, the first parameter is now implicit. - -Example: - -```C - afb_daemon_broadcast_event(afbitf->daemon, reason, description); -``` - -Becomes: - -```C - afb_daemon_broadcast_event(reason, description); -``` - -Also, to avoid possible conflicts, we introduced prefixed logging functions: -the macros - -- **ERROR** -- **WARNING** -- **NOTICE** -- **INFO** -- **DEBUG** - -have now a prefixed version: - -- **AFB\_ERROR** -- **AFB\_WARNING** -- **AFB\_NOTICE** -- **AFB\_INFO** -- **AFB\_DEBUG** - -It is now recommended to use the prefixed version. - -Example: - -```C - NOTICE(interface, "hello plugin comes to live"); -``` - -Become: - -```C - NOTICE("hello plugin comes to live"); -``` - -or, better: - -```C - AFB_NOTICE("hello plugin comes to live"); -``` - -To remove definition of the un-prefixed versions of logging macros: - -- **ERROR** -- **WARNING** -- **NOTICE** -- **INFO** -- **DEBUG** - -and just define - -- **AFB_BINDING_PRAGMA_NO_VERBOSE_UNPREFIX** - -before to include **afb/afb-binding.h**. - -```C -#define AFB_BINDING_PRAGMA_NO_VERBOSE_UNPREFIX -#define AFB_BINDING_VERSION 2 -#include -``` - -Consider where to emit logs for requests ----------------------------------------- - -The ***bindings*** v2 now allows to emit log messages associated to ***requests***. -This feature is valuable when debugging because it allows to return -side information associated to a ***request***. - -The defined macros for logging to requests are: - -- **AFB_REQ_ERROR** -- **AFB_REQ_WARNING** -- **AFB_REQ_NOTICE** -- **AFB_REQ_INFO** -- **AFB_REQ_DEBUG** - -We encourage the use of these new logging facilities everywhere it makes sense. - -Example: - -```C - INFO(afbitf, "method 'new' called for boardid %d", board->id); -``` - -Might become: - -```C - AFB_REQ_INFO(req, "method 'new' called for boardid %d", board->id); -``` - -Take care of store/unstore change ---------------------------------- - -For efficiency, the version 2 redefined how storing/un-storing of -requests works. -Storing request is needed for asynchronous handling of requests. - -For ***bindings*** version, the signature of the functions were: - -```C -struct afb_req *afb_req_store(struct afb_req req); -struct afb_req afb_req_unstore(struct afb_req *req); -``` - -For version 2 it becomes - -```C -struct afb_stored_req *afb_req_store(struct afb_req req); -struct afb_req afb_req_unstore(struct afb_stored_req *sreq); -``` - -Where the structure ```struct afb_stored_req``` is opaque. - -It should require few code change. - -Also check the following chapter that explain that asynchronous (sub)calls -can be replaced by synchronous one, avoiding the need to store/unstore -requests. - -Consider use of synchronous (sub)call requests ----------------------------------------------- - -***Bindings*** can emit requests for themselves (calls) or for -their clients (subcalls). -With ***bindings*** version 2 comes also synchronous requests for both cases. - -So when migrating to bindings version 2, a developer can consider -to replace the asynchronous requests (with asynchronous call back) -by synchronous ones. - -See functions ***afb_service_call_sync*** and ***afb_req_subcall_sync***. - -Optionally, removes explicit struct ------------------------------------ - -The new definitions now includes **typedefs** for common -structures, as shown on below sample: - -```C -typedef struct afb_daemon afb_daemon; -typedef struct afb_event afb_event; -typedef struct afb_arg afb_arg; -typedef struct afb_req afb_req; -typedef struct afb_service afb_service; -``` - -So you can remove the keyword **struct** if it bores you. - -Example: - -```C -static void verb(struct afb_req req) -{ - ... -} -``` - -Might become: - -```C -static void verb(afb_req req) -{ - ... -} -``` - -Example of migration --------------------- - -The first ***binding*** that migrated from v1 to v2 was the sample **HelloWorld**. -Here is shown the differences between the version 1 and the version 2. - -```diff -diff --git a/bindings/samples/HelloWorld.c b/bindings/samples/HelloWorld.c -index c6fa779..505aee3 100644 ---- a/bindings/samples/HelloWorld.c -+++ b/bindings/samples/HelloWorld.c -@@ -21,9 +21,9 @@ - - #include - -+#define AFB_BINDING_VERSION 2 - #include - --const struct afb_binding_interface *interface; - static pthread_mutex_t mutex = PTHREAD_MUTEX_INITIALIZER; - - struct event -@@ -79,7 +80,7 @@ static int event_add(const char *tag, const char *name) - strcpy(e->tag, tag); - - /* make the event */ -- e->event = afb_daemon_make_event(interface->daemon, name); -+ e->event = afb_daemon_make_event(name); - if (!e->event.closure) { free(e); return -1; } - - /* link */ -@@ -140,7 +141,7 @@ static void pingBug (struct afb_req request) - static void pingEvent(struct afb_req request) - { - json_object *query = afb_req_json(request); -- afb_daemon_broadcast_event(interface->daemon, "event", json_object_get(query)); -+ afb_daemon_broadcast_event("event", json_object_get(query)); - ping(request, json_object_get(query), "event"); - } - -@@ -288,38 +289,43 @@ static void exitnow (struct afb_req request) - exit(0); - } - -+static int preinit() -+{ -+ AFB_NOTICE("hello binding comes to live"); -+ return 0; -+} -+ -+static int init() -+{ -+ AFB_NOTICE("hello binding starting"); -+ return 0; -+} -+ - // NOTE: this sample does not use session to keep test a basic as possible - // in real application most APIs should be protected with AFB_SESSION_CHECK --static const struct afb_verb_desc_v1 verbs[]= { -- {"ping" , AFB_SESSION_NONE, pingSample , "Ping Application Framework"}, -- {"pingfail" , AFB_SESSION_NONE, pingFail , "Fails"}, -- {"pingnull" , AFB_SESSION_NONE, pingNull , "Return NULL"}, -- {"pingbug" , AFB_SESSION_NONE, pingBug , "Do a Memory Violation"}, -- {"pingJson" , AFB_SESSION_NONE, pingJson , "Return a JSON object"}, -- {"pingevent", AFB_SESSION_NONE, pingEvent , "Send an event"}, -- {"subcall", AFB_SESSION_NONE, subcall , "Call api/verb(args)"}, -- {"subcallsync", AFB_SESSION_NONE, subcallsync , "Call api/verb(args)"}, -- {"eventadd", AFB_SESSION_NONE, eventadd , "adds the event of 'name' for the 'tag'"}, -- {"eventdel", AFB_SESSION_NONE, eventdel , "deletes the event of 'tag'"}, -- {"eventsub", AFB_SESSION_NONE, eventsub , "subscribes to the event of 'tag'"}, -- {"eventunsub",AFB_SESSION_NONE, eventunsub , "unsubscribes to the event of 'tag'"}, -- {"eventpush", AFB_SESSION_NONE, eventpush , "pushs the event of 'tag' with the 'data'"}, -- {"exit", AFB_SESSION_NONE, exitnow , "exits from afb-daemon"}, -- {NULL} -+static const struct afb_verb_v2 verbs[]= { -+ { "ping" , pingSample , NULL, AFB_SESSION_NONE }, -+ { "pingfail" , pingFail , NULL, AFB_SESSION_NONE }, -+ { "pingnull" , pingNull , NULL, AFB_SESSION_NONE }, -+ { "pingbug" , pingBug , NULL, AFB_SESSION_NONE }, -+ { "pingJson" , pingJson , NULL, AFB_SESSION_NONE }, -+ { "pingevent", pingEvent , NULL, AFB_SESSION_NONE }, -+ { "subcall", subcall , NULL, AFB_SESSION_NONE }, -+ { "subcallsync", subcallsync, NULL, AFB_SESSION_NONE }, -+ { "eventadd", eventadd , NULL, AFB_SESSION_NONE }, -+ { "eventdel", eventdel , NULL, AFB_SESSION_NONE }, -+ { "eventsub", eventsub , NULL, AFB_SESSION_NONE }, -+ { "eventunsub", eventunsub , NULL, AFB_SESSION_NONE }, -+ { "eventpush", eventpush , NULL, AFB_SESSION_NONE }, -+ { "exit", exitnow , NULL, AFB_SESSION_NONE }, -+ { NULL} - }; - --static const struct afb_binding plugin_desc = { -- .type = AFB_BINDING_VERSION_1, -- .v1 = { -- .info = "Minimal Hello World Sample", -- .prefix = "hello", -- .verbs = verbs -- } -+const struct afb_binding_v2 afbBindingV2 = { -+ .api = "hello", -+ .specification = NULL, -+ .verbs = verbs, -+ .preinit = preinit, -+ .init = init - }; - --const struct afb_binding *afbBindingV1Register (const struct afb_binding_interface *itf) --{ -- interface = itf; -- NOTICE(interface, "hello plugin comes to live"); -- return &plugin_desc; --} -``` \ No newline at end of file diff --git a/docs/4_APIs_and_Services/4.3_Application_Framework_Binder/6_Annexes/7_LEGACY Binding V2 references.md b/docs/4_APIs_and_Services/4.3_Application_Framework_Binder/6_Annexes/7_LEGACY Binding V2 references.md deleted file mode 100644 index 70007f5..0000000 --- a/docs/4_APIs_and_Services/4.3_Application_Framework_Binder/6_Annexes/7_LEGACY Binding V2 references.md +++ /dev/null @@ -1,765 +0,0 @@ ---- -edit_link: '' -title: LEGACY Binding V2 references -origin_url: >- - https://git.automotivelinux.org/src/app-framework-binder/plain/docs/legacy/afb-binding-v2-references.md?h=master ---- - - - -[LEGACY] Binding Reference -========================== - -# Structure for declaring binding ---------------------------------- - -### struct afb_binding_v2 - -The main structure, of type **afb_binding_v2**, for describing the binding -must be exported under the name **afbBindingV2**. - -This structure is defined as below. - -```C -/* - * Description of the bindings of type version 2 - */ -struct afb_binding_v2 -{ - const char *api; /* api name for the binding */ - const char *specification; /* textual openAPIv3 specification of the binding */ - const char *info; /* some info about the api, can be NULL */ - const struct afb_verb_v2 *verbs; /* array of descriptions of verbs terminated by a NULL name */ - int (*preinit)(); /* callback at load of the binding */ - int (*init)(); /* callback for starting the service */ - void (*onevent)(const char *event, struct json_object *object); /* callback for handling events */ - unsigned noconcurrency: 1; /* avoids concurrent requests to verbs */ -}; -``` - -### struct afb_verb_v2 - -Each verb is described with a structure of type **afb_verb_v2** -defined below: - -```C -/* - * Description of one verb of the API provided by the binding - * This enumeration is valid for bindings of type version 2 - */ -struct afb_verb_v2 -{ - const char *verb; /* name of the verb */ - void (*callback)(struct afb_req req); /* callback function implementing the verb */ - const struct afb_auth *auth; /* required authorization */ - const char *info; /* some info about the verb, can be NULL */ - uint32_t session; /* authorization and session requirements of the verb */ -}; -``` - -The **session** flags is one of the constant defined below: - -- AFB_SESSION_NONE : no flag, synonym to 0 -- AFB_SESSION_LOA_0 : Requires the LOA to be 0 or more, synonym to 0 or AFB_SESSION_NONE -- AFB_SESSION_LOA_1 : Requires the LOA to be 1 or more -- AFB_SESSION_LOA_2 : Requires the LOA to be 2 or more -- AFB_SESSION_LOA_3 : Requires the LOA to be 3 or more -- AFB_SESSION_CHECK : Requires the token to be set and valid -- AFB_SESSION_REFRESH : Implies a token refresh -- AFB_SESSION_CLOSE : Implies cloing the session - -The LOA (Level Of Assurance) is set, by binding, using the function **afb_req_session_set_LOA**. - -### struct afb_auth and enum afb_auth_type - -The structure **afb_auth** is used within verb description to -set security requirements. -The interpretation of the structure depends on the value of the field **type**. - -```C -struct afb_auth -{ - const enum afb_auth_type type; - union { - const char *text; - const unsigned loa; - const struct afb_auth *first; - }; - const struct afb_auth *next; -}; -``` - -The possible values for **type** is defined here: - -```C -/* - * Enum for Session/Token/Assurance middleware. - */ -enum afb_auth_type -{ - afb_auth_No = 0, /** never authorized, no data */ - afb_auth_Token, /** authorized if token valid, no data */ - afb_auth_LOA, /** authorized if LOA greater than data 'loa' */ - afb_auth_Permission, /** authorized if permission 'text' is granted */ - afb_auth_Or, /** authorized if 'first' or 'next' is authorized */ - afb_auth_And, /** authorized if 'first' and 'next' are authorized */ - afb_auth_Not, /** authorized if 'first' is not authorized */ - afb_auth_Yes /** always authorized, no data */ -}; -``` - -Example: - -```C -static const struct afb_auth _afb_auths_v2_monitor[] = { - { .type = afb_auth_Permission, .text = "urn:AGL:permission:monitor:public:set" }, - { .type = afb_auth_Permission, .text = "urn:AGL:permission:monitor:public:get" }, - { .type = afb_auth_Or, .first = &_afb_auths_v2_monitor[1], .next = &_afb_auths_v2_monitor[0] } -}; -``` - -## Functions of class afb_daemon - -The 3 following functions are linked to libsystemd. -They allow use of **sd_event** features and access -to **sd_bus** features. - -```C -/* - * Retrieves the common systemd's event loop of AFB - */ -struct sd_event *afb_daemon_get_event_loop(); - -/* - * Retrieves the common systemd's user/session d-bus of AFB - */ -struct sd_bus *afb_daemon_get_user_bus(); - -/* - * Retrieves the common systemd's system d-bus of AFB - */ -struct sd_bus *afb_daemon_get_system_bus(); -``` - -The 2 following functions are linked to event management. -Broadcasting an event send it to any possible listener. - -```C -/* - * Broadcasts widely the event of 'name' with the data 'object'. - * 'object' can be NULL. - * - * For convenience, the function calls 'json_object_put' for 'object'. - * Thus, in the case where 'object' should remain available after - * the function returns, the function 'json_object_get' shall be used. - * - * Calling this function is only forbidden during preinit. - * - * Returns the count of clients that received the event. - */ -int afb_daemon_broadcast_event(const char *name, struct json_object *object); - -/* - * Creates an event of 'name' and returns it. - * - * Calling this function is only forbidden during preinit. - * - * See afb_event_is_valid to check if there is an error. - */ -struct afb_event afb_daemon_make_event(const char *name); -``` - -The following function is used by logging macros and should normally -not be used. -Instead, you should use the macros: - -- **AFB\_ERROR** -- **AFB\_WARNING** -- **AFB\_NOTICE** -- **AFB\_INFO** -- **AFB\_DEBUG** - -```C -/* - * Send a message described by 'fmt' and following parameters - * to the journal for the verbosity 'level'. - * - * 'file', 'line' and 'func' are indicators of position of the code in source files - * (see macros __FILE__, __LINE__ and __func__). - * - * 'level' is defined by syslog standard: - * EMERGENCY 0 System is unusable - * ALERT 1 Action must be taken immediately - * CRITICAL 2 Critical conditions - * ERROR 3 Error conditions - * WARNING 4 Warning conditions - * NOTICE 5 Normal but significant condition - * INFO 6 Informational - * DEBUG 7 Debug-level messages - */ -void afb_daemon_verbose(int level, const char *file, int line, const char * func, const char *fmt, ...); -``` - -The 2 following functions MUST be used to access data of the bindings. - -```C -/* - * Get the root directory file descriptor. This file descriptor can - * be used with functions 'openat', 'fstatat', ... - */ -int afb_daemon_rootdir_get_fd(); - -/* - * Opens 'filename' within the root directory with 'flags' (see function openat) - * using the 'locale' definition (example: "jp,en-US") that can be NULL. - * Returns the file descriptor or -1 in case of error. - */ -int afb_daemon_rootdir_open_locale(const char *filename, int flags, const char *locale); -``` - -The following function is used to queue jobs. - -```C -/* - * Queue the job defined by 'callback' and 'argument' for being executed asynchronously - * in this thread (later) or in an other thread. - * If 'group' is not NUL, the jobs queued with a same value (as the pointer value 'group') - * are executed in sequence in the order of there submission. - * If 'timeout' is not 0, it represent the maximum execution time for the job in seconds. - * At first, the job is called with 0 as signum and the given argument. - * The job is executed with the monitoring of its time and some signals like SIGSEGV and - * SIGFPE. When a such signal is catched, the job is terminated and re-executed but with - * signum being the signal number (SIGALRM when timeout expired). - * - * Returns 0 in case of success or -1 in case of error. - */ -int afb_daemon_queue_job(void (*callback)(int signum, void *arg), void *argument, void *group, int timeout) -``` - -The following function must be used when a binding depends on other -bindings at its initialization. - -```C -/* - * Tells that it requires the API of "name" to exist - * and if 'initialized' is not null to be initialized. - * Calling this function is only allowed within init. - * Returns 0 in case of success or -1 in case of error. - */ -int afb_daemon_require_api(const char *name, int initialized) -``` - -This function allows to give a different name to the binding. -It can be called during pre-init. - -```C -/* - * Set the name of the API to 'name'. - * Calling this function is only allowed within preinit. - * Returns 0 in case of success or -1 in case of error. - */ -int afb_daemon_rename_api(const char *name); -``` - -## Functions of class afb_service - -The following functions allow services to call verbs of other -bindings for themselves. - -```C -/** - * Calls the 'verb' of the 'api' with the arguments 'args' and 'verb' in the name of the binding. - * The result of the call is delivered to the 'callback' function with the 'callback_closure'. - * - * For convenience, the function calls 'json_object_put' for 'args'. - * Thus, in the case where 'args' should remain available after - * the function returns, the function 'json_object_get' shall be used. - * - * The 'callback' receives 3 arguments: - * 1. 'closure' the user defined closure pointer 'callback_closure', - * 2. 'status' a status being 0 on success or negative when an error occurred, - * 2. 'result' the resulting data as a JSON object. - * - * @param api The api name of the method to call - * @param verb The verb name of the method to call - * @param args The arguments to pass to the method - * @param callback The to call on completion - * @param callback_closure The closure to pass to the callback - * - * @see also 'afb_req_subcall' - */ -void afb_service_call( - const char *api, - const char *verb, - struct json_object *args, - void (*callback)(void*closure, int status, struct json_object *result), - void *callback_closure); - -/** - * Calls the 'verb' of the 'api' with the arguments 'args' and 'verb' in the name of the binding. - * 'result' will receive the response. - * - * For convenience, the function calls 'json_object_put' for 'args'. - * Thus, in the case where 'args' should remain available after - * the function returns, the function 'json_object_get' shall be used. - * - * @param api The api name of the method to call - * @param verb The verb name of the method to call - * @param args The arguments to pass to the method - * @param result Where to store the result - should call json_object_put on it - - * - * @returns 0 in case of success or a negative value in case of error. - * - * @see also 'afb_req_subcall' - */ -int afb_service_call_sync( - const char *api, - const char *verb, - struct json_object *args, - struct json_object **result); -``` - -## Functions of class afb_event - -This function checks whether the event is valid. -It must be used when creating events. - -```C -/* - * Checks wether the 'event' is valid or not. - * - * Returns 0 if not valid or 1 if valid. - */ -int afb_event_is_valid(struct afb_event event); -``` - -The two following functions are used to broadcast or push -event with its data. - -```C -/* - * Broadcasts widely the 'event' with the data 'object'. - * 'object' can be NULL. - * - * For convenience, the function calls 'json_object_put' for 'object'. - * Thus, in the case where 'object' should remain available after - * the function returns, the function 'json_object_get' shall be used. - * - * Returns the count of clients that received the event. - */ -int afb_event_broadcast(struct afb_event event, struct json_object *object); - -/* - * Pushes the 'event' with the data 'object' to its observers. - * 'object' can be NULL. - * - * For convenience, the function calls 'json_object_put' for 'object'. - * Thus, in the case where 'object' should remain available after - * the function returns, the function 'json_object_get' shall be used. - * - * Returns the count of clients that received the event. - */ -int afb_event_push(struct afb_event event, struct json_object *object); -``` - -The following function destroys the event. - -```C -/* - * Drops the data associated to the 'event' - * After calling this function, the event - * MUST NOT BE USED ANYMORE. - */ -void afb_event_drop(struct afb_event event); -``` - -This function allows to retrieve the exact name of the event. - -```C -/* - * Gets the name associated to the 'event'. - */ -const char *afb_event_name(struct afb_event event); -``` - -## Functions of class afb_req - -This function checks the validity of the **req**. - -```C -/* - * Checks wether the request 'req' is valid or not. - * - * Returns 0 if not valid or 1 if valid. - */ -int afb_req_is_valid(struct afb_req req); -``` - -The following functions retrieves parameters of the request. - -```C -/* - * Gets from the request 'req' the argument of 'name'. - * Returns a PLAIN structure of type 'struct afb_arg'. - * When the argument of 'name' is not found, all fields of result are set to NULL. - * When the argument of 'name' is found, the fields are filled, - * in particular, the field 'result.name' is set to 'name'. - * - * There is a special name value: the empty string. - * The argument of name "" is defined only if the request was made using - * an HTTP POST of Content-Type "application/json". In that case, the - * argument of name "" receives the value of the body of the HTTP request. - */ -struct afb_arg afb_req_get(struct afb_req req, const char *name); - -/* - * Gets from the request 'req' the string value of the argument of 'name'. - * Returns NULL if when there is no argument of 'name'. - * Returns the value of the argument of 'name' otherwise. - * - * Shortcut for: afb_req_get(req, name).value - */ -const char *afb_req_value(struct afb_req req, const char *name); - -/* - * Gets from the request 'req' the path for file attached to the argument of 'name'. - * Returns NULL if when there is no argument of 'name' or when there is no file. - * Returns the path of the argument of 'name' otherwise. - * - * Shortcut for: afb_req_get(req, name).path - */ -const char *afb_req_path(struct afb_req req, const char *name); - -/* - * Gets from the request 'req' the json object hashing the arguments. - * The returned object must not be released using 'json_object_put'. - */ -struct json_object *afb_req_json(struct afb_req req); -``` - -The following functions emit the reply to the request. - -```C -/* - * Sends a reply of kind success to the request 'req'. - * The status of the reply is automatically set to "success". - * Its send the object 'obj' (can be NULL) with an - * informational comment 'info (can also be NULL). - * - * For convenience, the function calls 'json_object_put' for 'obj'. - * Thus, in the case where 'obj' should remain available after - * the function returns, the function 'json_object_get' shall be used. - */ -void afb_req_success(struct afb_req req, struct json_object *obj, const char *info); - -/* - * Same as 'afb_req_success' but the 'info' is a formatting - * string followed by arguments. - * - * For convenience, the function calls 'json_object_put' for 'obj'. - * Thus, in the case where 'obj' should remain available after - * the function returns, the function 'json_object_get' shall be used. - */ -void afb_req_success_f(struct afb_req req, struct json_object *obj, const char *info, ...); - -/* - * Same as 'afb_req_success_f' but the arguments to the format 'info' - * are given as a variable argument list instance. - * - * For convenience, the function calls 'json_object_put' for 'obj'. - * Thus, in the case where 'obj' should remain available after - * the function returns, the function 'json_object_get' shall be used. - */ -void afb_req_success_v(struct afb_req req, struct json_object *obj, const char *info, va_list args); - -/* - * Sends a reply of kind failure to the request 'req'. - * The status of the reply is set to 'status' and an - * informational comment 'info' (can also be NULL) can be added. - * - * Note that calling afb_req_fail("success", info) is equivalent - * to call afb_req_success(NULL, info). Thus even if possible it - * is strongly recommended to NEVER use "success" for status. - */ -void afb_req_fail(struct afb_req req, const char *status, const char *info); - -/* - * Same as 'afb_req_fail' but the 'info' is a formatting - * string followed by arguments. - */ -void afb_req_fail_f(struct afb_req req, const char *status, const char *info, ...); - -/* - * Same as 'afb_req_fail_f' but the arguments to the format 'info' - * are given as a variable argument list instance. - */ -void afb_req_fail_v(struct afb_req req, const char *status, const char *info, va_list args); -``` - -The following functions handle the session data. - -```C -/* - * Gets the pointer stored by the binding for the session of 'req'. - * When the binding has not yet recorded a pointer, NULL is returned. - */ -void *afb_req_context_get(struct afb_req req); - -/* - * Stores for the binding the pointer 'context' to the session of 'req'. - * The function 'free_context' will be called when the session is closed - * or if binding stores an other pointer. - */ -void afb_req_context_set(struct afb_req req, void *context, void (*free_context)(void*)); - -/* - * Gets the pointer stored by the binding for the session of 'req'. - * If the stored pointer is NULL, indicating that no pointer was - * already stored, afb_req_context creates a new context by calling - * the function 'create_context' and stores it with the freeing function - * 'free_context'. - */ -void *afb_req_context(struct afb_req req, void *(*create_context)(), void (*free_context)(void*)); - -/* - * Frees the pointer stored by the binding for the session of 'req' - * and sets it to NULL. - * - * Shortcut for: afb_req_context_set(req, NULL, NULL) - */ -void afb_req_context_clear(struct afb_req req); - -/* - * Closes the session associated with 'req' - * and delete all associated contexts. - */ -void afb_req_session_close(struct afb_req req); - -/* - * Sets the level of assurance of the session of 'req' - * to 'level'. The effect of this function is subject of - * security policies. - * Returns 1 on success or 0 if failed. - */ -int afb_req_session_set_LOA(struct afb_req req, unsigned level); -``` - -The 4 following functions must be used for asynchronous handling requests. - -```C -/* - * Adds one to the count of references of 'req'. - * This function MUST be called by asynchronous implementations - * of verbs if no reply was sent before returning. - */ -void afb_req_addref(struct afb_req req); - -/* - * Substracts one to the count of references of 'req'. - * This function MUST be called by asynchronous implementations - * of verbs after sending the asynchronous reply. - */ -void afb_req_unref(struct afb_req req); - -/* - * Stores 'req' on heap for asynchronous use. - * Returns a handler to the stored 'req' or NULL on memory depletion. - * The count of reference to 'req' is incremented on success - * (see afb_req_addref). - */ -struct afb_stored_req *afb_req_store(struct afb_req req); - -/* - * Retrieves the afb_req stored at 'sreq'. - * Returns the stored request. - * The count of reference is UNCHANGED, thus, the - * function 'afb_req_unref' should be called on the result - * after that the asynchronous reply if sent. - */ -struct afb_req afb_req_unstore(struct afb_stored_req *sreq); -``` - -The two following functions are used to associate client with events -(subscription). - -```C -/* - * Establishes for the client link identified by 'req' a subscription - * to the 'event'. - * Returns 0 in case of successful subscription or -1 in case of error. - */ -int afb_req_subscribe(struct afb_req req, struct afb_event event); - -/* - * Revokes the subscription established to the 'event' for the client - * link identified by 'req'. - * Returns 0 in case of successful subscription or -1 in case of error. - */ -int afb_req_unsubscribe(struct afb_req req, struct afb_event event); -``` - -The following functions must be used to make request in the name of the -client (with its permissions). - -```C -/* - * Makes a call to the method of name 'api' / 'verb' with the object 'args'. - * This call is made in the context of the request 'req'. - * On completion, the function 'callback' is invoked with the - * 'closure' given at call and two other parameters: 'iserror' and 'result'. - * 'status' is 0 on success or negative when on an error reply. - * 'result' is the json object of the reply, you must not call json_object_put - * on the result. - * - * For convenience, the function calls 'json_object_put' for 'args'. - * Thus, in the case where 'args' should remain available after - * the function returns, the function 'json_object_get' shall be used. - * - * See also: - * - 'afb_req_subcall_req' that is convenient to keep request alive automatically. - * - 'afb_req_subcall_sync' the synchronous version - */ -void afb_req_subcall( - struct afb_req req, - const char *api, - const char *verb, - struct json_object *args, - void (*callback)(void *closure, int status, struct json_object *result), - void *closure); - -/* - * Makes a call to the method of name 'api' / 'verb' with the object 'args'. - * This call is made in the context of the request 'req'. - * On completion, the function 'callback' is invoked with the - * original request 'req', the 'closure' given at call and two - * other parameters: 'iserror' and 'result'. - * 'status' is 0 on success or negative when on an error reply. - * 'result' is the json object of the reply, you must not call json_object_put - * on the result. - * - * For convenience, the function calls 'json_object_put' for 'args'. - * Thus, in the case where 'args' should remain available after - * the function returns, the function 'json_object_get' shall be used. - * - * See also: - * - 'afb_req_subcall' that doesn't keep request alive automatically. - * - 'afb_req_subcall_sync' the synchronous version - */ -static inline void afb_req_subcall_req(struct afb_req req, const char *api, const char *verb, struct json_object *args, void (*callback)(void *closure, int iserror, struct json_object *result, struct afb_req req), void *closure) -{ - req.itf->subcall_req(req.closure, api, verb, args, callback, closure); -} - -/* - * Makes a call to the method of name 'api' / 'verb' with the object 'args'. - * This call is made in the context of the request 'req'. - * This call is synchronous, it waits until completion of the request. - * It returns 0 on success or a negative value on error answer. - * The object pointed by 'result' is filled and must be released by the caller - * after its use by calling 'json_object_put'. - * - * For convenience, the function calls 'json_object_put' for 'args'. - * Thus, in the case where 'args' should remain available after - * the function returns, the function 'json_object_get' shall be used. - * - * See also: - * - 'afb_req_subcall_req' that is convenient to keep request alive automatically. - * - 'afb_req_subcall' that doesn't keep request alive automatically. - */ -int afb_req_subcall_sync( - struct afb_req req, - const char *api, - const char *verb, - struct json_object *args, - struct json_object **result); -``` - -The following function is used by logging macros and should normally -not be used. -Instead, you should use the macros: - -- **AFB_REQ_ERROR** -- **AFB_REQ_WARNING** -- **AFB_REQ_NOTICE** -- **AFB_REQ_INFO** -- **AFB_REQ_DEBUG** - -```C -/* - * Send associated to 'req' a message described by 'fmt' and following parameters - * to the journal for the verbosity 'level'. - * - * 'file', 'line' and 'func' are indicators of position of the code in source files - * (see macros __FILE__, __LINE__ and __func__). - * - * 'level' is defined by syslog standard: - * EMERGENCY 0 System is unusable - * ALERT 1 Action must be taken immediately - * CRITICAL 2 Critical conditions - * ERROR 3 Error conditions - * WARNING 4 Warning conditions - * NOTICE 5 Normal but significant condition - * INFO 6 Informational - * DEBUG 7 Debug-level messages - */ -void afb_req_verbose(struct afb_req req, int level, const char *file, int line, const char * func, const char *fmt, ...); -``` - -The functions below allow a binding involved in the platform security -to explicitly check a permission of a client or to get the calling -application identity. - -```C -/* - * Check whether the 'permission' is granted or not to the client - * identified by 'req'. - * - * Returns 1 if the permission is granted or 0 otherwise. - */ -int afb_req_has_permission(struct afb_req req, const char *permission); - -/* - * Get the application identifier of the client application for the - * request 'req'. - * - * Returns the application identifier or NULL when the application - * can not be identified. - * - * The returned value if not NULL must be freed by the caller - */ -char *afb_req_get_application_id(struct afb_req req); - -/* - * Get the user identifier (UID) of the client application for the - * request 'req'. - * - * Returns -1 when the application can not be identified. - */ -int afb_req_get_uid(struct afb_req req); -``` - -## Logging macros - -The following macros must be used for logging: - -```C -AFB_ERROR(fmt,...) -AFB_WARNING(fmt,...) -AFB_NOTICE(fmt,...) -AFB_INFO(fmt,...) -AFB_DEBUG(fmt,...) -``` - -The following macros can be used for logging in the context -of a request **req** of type **afb_req**: - -```C -AFB_REQ_ERROR(req,fmt,...) -AFB_REQ_WARNING(req,fmt,...) -AFB_REQ_NOTICE(req,fmt,...) -AFB_REQ_INFO(req,fmt,...) -AFB_REQ_DEBUG(req,fmt,...) -``` - -By default, the logging macros add file, line and function -indication. diff --git a/docs/4_APIs_and_Services/4.3_Application_Framework_Binder/7_Document_revisions/Document_revisions.md b/docs/4_APIs_and_Services/4.3_Application_Framework_Binder/7_Document_revisions/Document_revisions.md deleted file mode 100644 index 5b6064a..0000000 --- a/docs/4_APIs_and_Services/4.3_Application_Framework_Binder/7_Document_revisions/Document_revisions.md +++ /dev/null @@ -1,23 +0,0 @@ ---- -edit_link: '' -title: Document revisions -origin_url: >- - https://git.automotivelinux.org/src/app-framework-binder/plain/docs/REVISIONS.md?h=master ---- - - - -Document revisions -================== - -| Date | Version | Designation  | Author | -|--------------|:----------:|----------------------------------------------|-------------------------------------------------------| -| 23 May 2016 | 0.9 | Initial release | J. Bollo [ IoT.bzh ]
M. Bachmann [ IoT.bzh ] | -| 30 May 2016 | 1.0 | Master document edition, final review | S. Desneux [ IoT.bzh ]
F. Ar Foll [ IoT.bzh ] | -| 21 Sept 2016 | 2.0 | Updated with new sections (events,widgets) | J. Bollo [ IoT.bzh ]
S. Desneux [ IoT.bzh ] | -| 12 Dec 2016 | 2.1 | Updated for CC Release | S. Desneux [ IoT.bzh ] | -| 14 Dec 2016 | 3.0 | Minor fixes, alignment with CC version | S. Desneux [ IoT.bzh ] | -| 20 Mar 2017 | 3.1 | Systemd integration | J. Bollo [ IoT.bzh ]
S. Desneux [ IoT.bzh ] | -| 21 Jun 2017 | 4.0 | Update for AGL DD | J. Bollo [ IoT.bzh ]
S. Desneux [ IoT.bzh ] | -| 21 Sep 2017 | 4.99-EERC1 | Update for AGL EE-RC1 | J. Bollo [ IoT.bzh ]
S. Desneux [ IoT.bzh ] | -| 14 Jun 2018 | 5.99-FFRC1 | Update for AGL FF-RC1 | J. Bollo [ IoT.bzh ] | diff --git a/docs/4_APIs_and_Services/4.3_Application_Framework_Binder/pictures/basis.svg b/docs/4_APIs_and_Services/4.3_Application_Framework_Binder/pictures/basis.svg deleted file mode 100644 index 0d42d76..0000000 --- a/docs/4_APIs_and_Services/4.3_Application_Framework_Binder/pictures/basis.svg +++ /dev/null @@ -1,356 +0,0 @@ - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - APPLICATION - - - - - - - - BINDERafb-daemon - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - BINDING - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - BINDING - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - BINDING - - - - - - - - - - - - - - - - - - SECURITYCONTEXT - - - - - - http - - - - - - ws - - - - - - - - \ No newline at end of file diff --git a/docs/4_APIs_and_Services/4.3_Application_Framework_Binder/pictures/interconnection.svg b/docs/4_APIs_and_Services/4.3_Application_Framework_Binder/pictures/interconnection.svg deleted file mode 100644 index 4a10217..0000000 --- a/docs/4_APIs_and_Services/4.3_Application_Framework_Binder/pictures/interconnection.svg +++ /dev/null @@ -1,854 +0,0 @@ - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - APPLICATION - - - - - - - - BINDERafb-daemon - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - BINDING - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - BINDING - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - BINDING - - - - - - - - - - - - SECURITYCONTEXT - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - APPLICATION - - - - - - - - BINDERafb-daemon - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - BINDING - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - BINDING - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - BINDING - - - - - - - - - - - - SECURITYCONTEXT - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - APPLICATION - - - - - - - - BINDERafb-daemon - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - BINDING - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - BINDING - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - BINDING - - - - - - - - - - - - SECURITYCONTEXT - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - APPLICATION - - - - - - - - BINDERafb-daemon - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - BINDING - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - BINDING - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - BINDING - - - - - - - - - - - - SECURITYCONTEXT - - - - - - - - - interconnectiondbus, ws,bus1, tls,... - - - - - - - - A - - - - - - - - C - - - - - - - - B - - - - - - - - D - - - - - - - - \ No newline at end of file diff --git a/docs/4_APIs_and_Services/4.3_Application_Framework_Binder/pictures/signaling-basis.svg b/docs/4_APIs_and_Services/4.3_Application_Framework_Binder/pictures/signaling-basis.svg deleted file mode 100644 index b13fcf1..0000000 --- a/docs/4_APIs_and_Services/4.3_Application_Framework_Binder/pictures/signaling-basis.svg +++ /dev/null @@ -1,145 +0,0 @@ - - - - - - - request-data - - - - - - client 1 - - - - - - - - client 2 - - - - - - - - : framework - - - - - - - - signaling agent - - - - - - - - - - - request-data - - - - - - afb_daemon_make_event - - - - - - - - - afb_req_subscribe - - - - - reply of request-data - - - - - - afb_req_subscribe - - - - - reply of request-data - - - - - - device - - - - - - - - - setup - - - - - << wake up >> - - - - - afb_event_push - - - - - << event >> - - - - - << event >> - - - - - reply of afb_event_push - - - - - - - - - - - - - - - - - - - - - - - - - - diff --git a/docs/4_APIs_and_Services/4.4_AGL_Test_Framework/0_Installation/Installation.md b/docs/4_APIs_and_Services/4.4_AGL_Test_Framework/0_Installation/Installation.md deleted file mode 100644 index 512e08f..0000000 --- a/docs/4_APIs_and_Services/4.4_AGL_Test_Framework/0_Installation/Installation.md +++ /dev/null @@ -1,33 +0,0 @@ ---- -edit_link: '' -title: Installation -origin_url: >- - https://git.automotivelinux.org/apps/app-afb-test/plain/docs/0_Installation.md?h=master ---- - - - -# Installation - -[Verify Your Build Host](../../../devguides/reference/1-verify-build-host.html). - -Use the following command-line to get the `afb-test` binding and all its -dependencies. - -* Fedora (>= 27): - -```bash -dnf install agl-app-afb-test-devel -``` - -* OpenSuse (>= 15.0): - -```bash -zypper install agl-app-afb-test-devel -``` - -* Ubuntu (>= Xenial), Debian stable: - -```bash -apt-get install agl-app-afb-test-dev -``` diff --git a/docs/4_APIs_and_Services/4.4_AGL_Test_Framework/1_Write_the_tests/Write_the_tests.md b/docs/4_APIs_and_Services/4.4_AGL_Test_Framework/1_Write_the_tests/Write_the_tests.md deleted file mode 100644 index b5d6ed7..0000000 --- a/docs/4_APIs_and_Services/4.4_AGL_Test_Framework/1_Write_the_tests/Write_the_tests.md +++ /dev/null @@ -1,261 +0,0 @@ ---- -edit_link: '' -title: Write the tests -origin_url: >- - https://git.automotivelinux.org/apps/app-afb-test/plain/docs/1_Write_the_tests.md?h=master ---- - - - -# Write the tests - -## Create the test tree - -At the root of your project, create a test-dedicated directory that holds -all your test materials. A classic test tree looks like the following: - -```tree - test - ├── CMakeLists.txt - └── afb-test - ├── CMakeLists.txt - ├── etc - │ ├── CMakeLists.txt - │ └── aft-agl-middlename.json - ├── fixtures - │ ├── CMakeLists.txt - │ ├── helper.sh - │ ├── data - │ └── plugin.lua - └── tests - ├── CMakeLists.txt - ├── test01.lua - ├── test02.lua - └── test03.lua - ... -``` - -Here is a description of each subdirectory purpose: - -- *etc*`: Holds the test binding configuration in a JSON file. -- *fixtures*: contains all external needed files to run your tests. - This subdirectory is primarily used to inject data or a plugin - with the mock-up APIs code in a LUA or C plugin. -- *tests*: Contains only the tests written in LUA for your binding. - -## Create your configuration file - -The configuration file describes your test API and how it launches the tests. -A test binding does not provide verbs. -This configuration describes the API verb(s) and mocked-up APIs. -Following are the `key` descriptions for the configuration file: - -### `metadata` section - -- `uid`: A simple label useful for debugging. -- `version` (optional): The test's version. -- `info` (optional): Provides information about the test. -- `api`: The name your test binding takes. - Formerly, the name was the test API name prefixed with `aft` - (i.e. `aft-`). -- `require`: The tested API's name. This key ensure that the tested API is - correctly launched and initialized so the test binding can test it. - -### `testVerb` section - -- `uid`: The verb name. -- `info` (optional): Provides information about the verb. -- `action`: A special string indicating the function to trigger when the verb is - called. The verb is always the same about the test binding. -- `args` Contains the following: - - `trace`: The name of the tested API you are testing. `trace` is - needed to allow the test binding trace the tested API and retrieve through - the binder's monitoring feature `calls` and `events`. - - `files`: A string or an array of strings of the LUA files with your tests. - Only provide the file name. Do not provide the path. - -### `mapis` (mocked up API), section - -- `uid`: The mocked up API's name -- `info` (optional): Provides information on the mock-up API. -- `libs`: The LUA script or C plugin file name. - -#### `verbs` section - -Describes the implemented mocked up API verbs. Each verb maps to a function -name that is executed when the verb is called. - -- `uid`: The verb's name. -- `info` (optional): Provides information on the verb. -- `action`: A URI string that points to a C plugin or LUA script's function that - is executes when the verb is called. The format of the action URI is: - ``://``#`` - -#### `events` section. - -Allows you to trigger a function when a described event is received. -The trigger can be for any event on which you need to apply modifications. -You do not have to enumerate each possible event that the mocked up API can -generate. You could avoid this section if you do not want to execute a function -when an event is received. - -- `uid`: The event's name (e.g. `/`) -- `info` (optional): Provides information about the event. -- `action`: A URI string that points to a C plugin or LUA script's function that - is executed when an event is received. The format of the action URI is: - ``://``#``. - The action `lua://AFT#_evt_catcher_` is the default `afb-test` events listener. - -### Configuration examples - -Here is a simple example: - -```json -{ - "id": "http://iot.bzh/download/public/schema/json/ctl-schema.json#", - "$schema": "http://iot.bzh/download/public/schema/json/ctl-schema.json#", - "metadata": { - "uid": "Hello_Test", - "version": "1.0", - "api": "aft-example", - "info": "Binding made to test other bindings", - "require": [ - "hello" - ] - }, - "testVerb": { - "uid": "testing-hello", - "info": "Launch the tests against hello api", - "action": "lua://AFT#_launch_test", - "args": { - "trace": "hello", - "files": ["aftTest.lua","helloworld.lua"] - } - } -} -``` - -Following is another example that uses a mocked up `low-can` API: - -```json -{ - "id": "http://iot.bzh/download/public/schema/json/ctl-schema.json#", - "$schema": "http://iot.bzh/download/public/schema/json/ctl-schema.json#", - "metadata": { - "uid": "Other_Tests", - "version": "1.0", - "api": "aft-example", - "info": "Binding made to test other bindings", - "require": [ - "tested-api" - ] - }, - "testVerb": { - "uid": "Complete", - "info": "Launch all the tests", - "action": "lua://AFT#_launch_test", - "args": { - "trace": "low-can", - "files": [ "aftTest.lua", "mapis-tests.lua" ] - } - }, - "mapis": [{ - "uid": "low-can", - "info": "Faked low-can API", - "libs": "mapi_low-can.lua", - "verbs": [ - { - "uid": "subscribe", - "info": "Subscribe to CAN signals events", - "action": "lua://low-can#_subscribe" - }, - {...}, - { - "uid": "write", - "info": "Write a CAN messages to the CAN bus.", - "action": "lua://low-can#_write" - } - ], - "events": [{ - "uid": "low-can/diagnostic_messages", - "action": "lua://AFT#_evt_catcher_" - },{ - "uid": "low-can/messages_engine_speed", - "action": "lua://AFT#_evt_catcher_" - },{ - "uid": "low-can/messages_vehicle_speed", - "action": "lua://AFT#_evt_catcher_" - }] - }] -} -``` - -## The LUA test files - -The test framework uses the LUA language to describe the tests. - -You must be aware of two things when you write tests using -this framework: *test* and *assertions* functions. - -- *Assertions* functions test an atomic operation result. - (ie: `1+1 = 2`). -- *Test* functions represent a test. These functions represent a set of one - or more *assertions* that must all succeed in order to valid the test. - -The framework comes with several *test* and *assertion* functions that -allow verb calls and received events to be tested. Use these provided -*test* functions as a start. If you -need more functions, use the ones that call a callback. If the test is more complex or -more comprehensive then *describe* your test function using *assert* functions. -Following is an example. - -See the test framework functions [References](Reference/0_BindingTestFunctions.html) for a -comprehensive list of available *tests* and *assertions* functions. - -### Tests example - -```lua - function _callback(responseJ) - _AFT.assertStrContains(responseJ.response, "Some String") - end - - function _callbackError(responseJ) - _AFT.assertStrContains(responseJ.request.info, "Ping Binder Daemon fails") - end - - function _callbackEvent(eventName, eventData) - _AFT.assertEquals(eventData, {data = { key = 'weird others data', another_key = 123.456 }}) - end - - _AFT.addEventToMonitor("hello/anEvent") - _AFT.addEventToMonitor("hello/anotherEvent", _callbackEvent) - - _AFT.testVerbStatusSuccess('testPingSuccess','hello', 'ping', {}) - _AFT.testVerbResponseEquals('testPingSuccess','hello', 'ping', {}, "Some String") - _AFT.testVerbResponseEquals('testPingSuccess','hello', 'ping', {}, "Unexpected String") - _AFT.testVerbCb('testPingSuccess','hello', 'ping', {}, _callback) - _AFT.testVerbStatusError('testPingError', 'hello', 'pingfail', {}) - _AFT.testVerbResponseEqualsError('testPingError', 'hello', 'pingfail', {}, "Ping Binder Daemon fails") - _AFT.testVerbResponseEqualsError('testPingError', 'hello', 'pingfail', {}, "Ping Binder Daemon succeed") - _AFT.testVerbCbError('testPingError', 'hello', 'pingfail', {}, _callbackError) - - _AFT.testVerbStatusSuccess('testEventAdd', 'hello', 'eventadd', {tag = 'event', name = 'anEvent'}) - _AFT.testVerbStatusSuccess('testEventSub', 'hello', 'eventsub', {tag = 'event'}) - _AFT.testVerbStatusSuccess('testEventPush', 'hello', 'eventpush', {tag = 'event', data = { key = 'some data', another_key = 123}}) - - _AFT.testVerbStatusSuccess('testEventAdd', 'hello', 'eventadd', {tag = 'evt', name = 'anotherEvent'}) - _AFT.testVerbStatusSuccess('testEventSub', 'hello', 'eventsub', {tag = 'evt'}) - _AFT.testVerbStatusSuccess('testEventPush', 'hello', 'eventpush', {tag = 'evt', data = { key = 'weird others data', another_key = 123.456}}) - - _AFT.testVerbStatusSuccess('testGenerateWarning', 'hello', 'verbose', {level = 4, message = 'My Warning message!'}) - - _AFT.testEvtGrpReceived("TestEventGroupReceived",{"hello/anEvent","hello/anotherEvent"},300000) - _AFT.testEvtGrpNotReceived("TestEventGroupNotReceived",{"hello/anEvent","hello/anotherEvent"},300000) - - _AFT.testEvtReceived("testEvent", "hello/anEvent",300000) - _AFT.testEvtReceived("testEventCb", "hello/anotherEvent",300000) - - _AFT.describe("myTestLabel", function() - _AFT.assertEquals(false, false) - end) -``` diff --git a/docs/4_APIs_and_Services/4.4_AGL_Test_Framework/2_The_test_widget/The_test_widget.md b/docs/4_APIs_and_Services/4.4_AGL_Test_Framework/2_The_test_widget/The_test_widget.md deleted file mode 100644 index 2933f74..0000000 --- a/docs/4_APIs_and_Services/4.4_AGL_Test_Framework/2_The_test_widget/The_test_widget.md +++ /dev/null @@ -1,74 +0,0 @@ ---- -edit_link: '' -title: The test widget -origin_url: >- - https://git.automotivelinux.org/apps/app-afb-test/plain/docs/2_The_test_widget.md?h=master ---- - - - -# How to build the test widget using app-templates/cmake-apps-module - -## Defining CMake targets - -Now that the test tree has been created, in each directory you have to create -a `CMakeLists.txt` file to hold the CMake's target definition. For each target -you need to specify a **LABELS** depending on the purpose of the files for each -directory. There are more explanations about using the *cmake-apps-module* (the -former *app-templates* submodule) in the [documentation website](../../../devguides/reference/cmakeafbtemplates/dev_guide/advanced-usage.html). - -Here is a cheat sheet to map the **LABELS** target for each classic test tree -directory: - -* `etc` uses the label **TEST-CONFIG** -* `fixtures` uses the label **TEST-DATA** -* `tests` uses the label **TEST-DATA** - -i.e for the `etc` folder: - -```cmake -PROJECT_TARGET_ADD(afb-test-config) - - file(GLOB CONF_FILES "*.json") - - add_input_files("${CONF_FILES}") - - SET_TARGET_PROPERTIES(${TARGET_NAME} PROPERTIES - LABELS "TEST-CONFIG" - OUTPUT_NAME ${TARGET_NAME} - ) -``` - -> **CAUTION**: make sure that you have CMakeLists files that include your -> subdirectories target (cf: previous chapter `Write the tests`). - -## Build the test widget - -By default, the test widget is not built, you have to specify that you want to -build it or use a special target. - -### Building at the same time than classic widget - -Specify the option `BUILD_TEST_WGT=TRUE` when you configure your build. - -ie: - -```bash -cd build -cmake -DBUILD_TEST_WGT=TRUE .. -make -make widget -``` - -### Building separately only the test widget - -Just use the target `test_widget` after a classic build. - -ie: - -```bash -cd build -cmake .. -make -make test_widget -``` diff --git a/docs/4_APIs_and_Services/4.4_AGL_Test_Framework/3_Launch_the_tests/Launch_the_tests.md b/docs/4_APIs_and_Services/4.4_AGL_Test_Framework/3_Launch_the_tests/Launch_the_tests.md deleted file mode 100644 index 43993f4..0000000 --- a/docs/4_APIs_and_Services/4.4_AGL_Test_Framework/3_Launch_the_tests/Launch_the_tests.md +++ /dev/null @@ -1,336 +0,0 @@ ---- -edit_link: '' -title: Launch the tests -origin_url: >- - https://git.automotivelinux.org/apps/app-afb-test/plain/docs/3_Launch_the_tests.md?h=master ---- - - - -# How to launch the tests ? - -## Natively during the development - -It could be convenient to be able to test the software that you are currently -developing. Then you can ensure that your modifications haven't introduced -regressions, bugs, etc. This depends upon your tests of course. - -As previously saw, you need the `test widget` to be able to launch the tests and -you need also to have the `afb-test` binding installed and the `application -framework binder` to be able to execute your tests. - -Assuming you already installed those components on your development host, then -proceed as the following from the project root directory: - -```bash -cd build -cmake -DBUILD_TEST_WGT=TRUE .. -make -make widget -``` - -To prepare all files needed for the test launch then use the `afm-test` script: - -```bash -# Usage of afm-test command line utility -afm-test --help -Usage: /opt/AGL/bin/afm-test [-m|--mode ] [-t|--timeout ] [-l|--lavaoutput] -binding-wgt-rootdir: path to the test wgt file -test-wgt-rootdir: path to the test folder file --m|--mode: SOLO (1 binder) or SERVICE (2 binders) (Default: SOLO) --t|--timeout: timeout in second. (Default 3 seconds) --l|--lavaoutput: Flags indicating the binding to add Lava special test markers. -Error: Test launch failed. Code: 1 -# Launching the test from your build project directory -afm-test package package-test -``` - -### Example with the afb-test selftest suite - -Prepare the launch building the `test widget`: - -```bash -$ cd build -# Cleaning the previous build files -$ rm -rf * -# Configuration step -$ cmake -DBUILD_TEST_WGT=TRUE .. --- The C compiler identification is GNU 8.2.1 --- The CXX compiler identification is GNU 8.2.1 --- Check for working C compiler: /usr/lib64/ccache/cc --- Check for working C compiler: /usr/lib64/ccache/cc -- works --- Detecting C compiler ABI info --- Detecting C compiler ABI info - done --- Detecting C compile features --- Detecting C compile features - done --- Check for working CXX compiler: /usr/lib64/ccache/c++ --- Check for working CXX compiler: /usr/lib64/ccache/c++ -- works --- Detecting CXX compiler ABI info --- Detecting CXX compiler ABI info - done --- Detecting CXX compile features --- Detecting CXX compile features - done -Distribution detected (separated by ';' choose one of them) fedora -Include: /home/claneys/.config/app-templates/cmake.d/00-common-var.cmake -Include: /home/claneys/Workspace/Sources/IOTbzh/gerrit.automotivelinux.org/apps/app-afb-test/conf.d/cmake/00-default-osconfig.cmake -Include: /usr/share/cmake/Modules/CMakeAfbTemplates/cmake/cmake.d/01-build_options.cmake --- Found PkgConfig: /usr/bin/pkg-config (found version "1.4.2") --- Checking for module 'json-c' --- Found json-c, version 0.13.1 --- Checking for module 'libsystemd>=222' --- Found libsystemd, version 238 --- Checking for module 'afb-daemon>=4.0' --- Found afb-daemon, version 6.90.0 --- Checking for module 'lua>=5.3' --- Found lua, version 5.3.4 -Include: /usr/share/cmake/Modules/CMakeAfbTemplates/cmake/cmake.d/02-variables.cmake --- Check gcc_minimal_version (found gcc version 8.2.1) (found g++ version 8.2.1) -Include: /usr/share/cmake/Modules/CMakeAfbTemplates/cmake/cmake.d/03-macros.cmake -Include: /usr/share/cmake/Modules/CMakeAfbTemplates/cmake/cmake.d/04-extra_targets.cmake --- Overwrite the CMAKE default install prefix with /opt/AGL --- Found CURL: /usr/lib64/libcurl.so (found version "7.59.0") --- Qt's WebSocket AFB Client: Disabled! --- CURL wrapping helpers: Enabled! --- Notice: LUA Controler Support Selected --- Notice: Using default test widget configuration's file. --- If you want to use a customized test-config.xml template then specify TEST_WIDGET_CONFIG_TEMPLATE in your config.cmake file. --- Configuring done --- Generating done --- Build files have been written to: /home/claneys/Workspace/Sources/IOTbzh/gerrit.automotivelinux.org/apps/app-afb-test/build -# Build the binding -$ make -Scanning dependencies of target test-files -[ 3%] Generating test-files -[ 3%] Built target test-files -Scanning dependencies of target project_populate_test-files -[ 6%] Generating package-test/var/test-files -[ 6%] Built target project_populate_test-files -Scanning dependencies of target afb-test-config -[ 9%] Generating afb-test-config -Warning: JSON_CHECKER not found. Not verification made on files ! -[ 9%] Built target afb-test-config -Scanning dependencies of target project_populate_afb-test-config -[ 12%] Generating package-test/etc/afb-test-config -[ 12%] Built target project_populate_afb-test-config -Scanning dependencies of target aftest-config -[ 16%] Generating aftest-config -Warning: JSON_CHECKER not found. Not verification made on files ! -[ 16%] Built target aftest-config -Scanning dependencies of target project_populate_aftest-config -[ 19%] Generating package/etc/aftest-config -[ 19%] Built target project_populate_aftest-config -Scanning dependencies of target fixture-files -[ 22%] Generating fixture-files -[ 22%] Built target fixture-files -Scanning dependencies of target project_populate_fixture-files -[ 25%] Generating package-test/var/fixture-files -[ 25%] Built target project_populate_fixture-files -Scanning dependencies of target afTest-lua -[ 29%] Generating afTest-lua -[ 29%] Built target afTest-lua -Scanning dependencies of target project_populate_afTest-lua -[ 32%] Generating package/var/afTest-lua -[ 32%] Built target project_populate_afTest-lua -Scanning dependencies of target afb-helpers -[ 35%] Building C object afb-helpers/CMakeFiles/afb-helpers.dir/wrap-json.c.o -[ 38%] Building C object afb-helpers/CMakeFiles/afb-helpers.dir/filescan-utils.c.o -[ 41%] Building C object afb-helpers/CMakeFiles/afb-helpers.dir/escape.c.o -[ 45%] Building C object afb-helpers/CMakeFiles/afb-helpers.dir/curl-wrap.c.o -[ 48%] Linking C static library libafb-helpers.a -[ 48%] Built target afb-helpers -Scanning dependencies of target ctl-utilities -[ 51%] Building C object app-controller-submodule/ctl-lib/CMakeFiles/ctl-utilities.dir/ctl-action.c.o -[ 54%] Building C object app-controller-submodule/ctl-lib/CMakeFiles/ctl-utilities.dir/ctl-config.c.o -[ 58%] Building C object app-controller-submodule/ctl-lib/CMakeFiles/ctl-utilities.dir/ctl-onload.c.o -[ 61%] Building C object app-controller-submodule/ctl-lib/CMakeFiles/ctl-utilities.dir/ctl-plugin.c.o -[ 64%] Building C object app-controller-submodule/ctl-lib/CMakeFiles/ctl-utilities.dir/ctl-control.c.o -[ 67%] Building C object app-controller-submodule/ctl-lib/CMakeFiles/ctl-utilities.dir/ctl-event.c.o -[ 70%] Building C object app-controller-submodule/ctl-lib/CMakeFiles/ctl-utilities.dir/ctl-lua.c.o -[ 74%] Building C object app-controller-submodule/ctl-lib/CMakeFiles/ctl-utilities.dir/ctl-timer.c.o -[ 77%] Building C object app-controller-submodule/ctl-lib/CMakeFiles/ctl-utilities.dir/ctl-lua-utils.c.o -[ 80%] Linking C static library libctl-utilities.a -[ 80%] Built target ctl-utilities -Scanning dependencies of target aft -[ 83%] Building C object src/CMakeFiles/aft.dir/aft.c.o -[ 87%] Building C object src/CMakeFiles/aft.dir/mapis.c.o -[ 90%] Linking C shared module aft.so -[ 90%] Built target aft -Scanning dependencies of target project_populate_aft -[ 93%] Generating package/lib/aft.so -[ 93%] Built target project_populate_aft -Scanning dependencies of target populate -[ 96%] Generating package/bin, package/etc, package/lib, package/htdocs, package/var, package-test/bin, package-test/etc, package-test/lib, package-test/htdocs, package-test/var -[ 96%] Built target populate -Scanning dependencies of target afTest_build_done -++ Typical binding launch: afb-daemon --name afTest --port=1234 --workdir=package-test --ldpaths=/opt/AGL/lib64/afb:../package/lib --token= -[ 96%] Built target afTest_build_done -Scanning dependencies of target autobuild -[100%] Built target autobuild -# Build both widgets classic and test -$ make widget -[ 2%] Built target test-files -Scanning dependencies of target packaging_wgt -[ 5%] Generating package/config.xml -[ 8%] Generating package-test/config.xml, package-test/bin/launcher -[ 8%] Built target packaging_wgt -[ 11%] Generating package-test/var/test-files -[ 11%] Built target project_populate_test-files -Warning: JSON_CHECKER not found. Not verification made on files ! -[ 14%] Built target afb-test-config -[ 17%] Generating package-test/etc/afb-test-config -[ 17%] Built target project_populate_afb-test-config -Warning: JSON_CHECKER not found. Not verification made on files ! -[ 20%] Built target aftest-config -[ 23%] Generating package/etc/aftest-config -[ 23%] Built target project_populate_aftest-config -[ 26%] Built target fixture-files -[ 29%] Generating package-test/var/fixture-files -[ 29%] Built target project_populate_fixture-files -[ 32%] Built target afTest-lua -[ 35%] Generating package/var/afTest-lua -[ 35%] Built target project_populate_afTest-lua -[ 50%] Built target afb-helpers -[ 79%] Built target ctl-utilities -[ 88%] Built target aft -[ 91%] Built target project_populate_aft -[ 94%] Built target populate -Scanning dependencies of target widget -[ 97%] Generating aftest.wgt -NOTICE: -- PACKING widget aftest.wgt from directory /home/claneys/Workspace/Sources/IOTbzh/gerrit.automotivelinux.org/apps/app-afb-test/build/package -[100%] Generating aftest-test.wgt -NOTICE: -- PACKING widget aftest-test.wgt from directory /home/claneys/Workspace/Sources/IOTbzh/gerrit.automotivelinux.org/apps/app-afb-test/build/package-test -++ Install widget file using in the target : afm-util install afTest.wgt -[100%] Built target widget -``` - -Launch the test using the mode SERVICE for the `afb-test` because of a recursion -problem which loads 2 times the same binding and causes conflict. So it is -needed to uses 2 binders then each ones loads its binding properly: - -```bash -$ afm-test package package-test/ -m SERVICE -1..4 -# Started on Tue Oct 30 10:32:46 2018 -# Starting class: TestListverb -ok 1 TestListverb.testFunction -# Starting class: TestGetVerb -ok 2 TestGetVerb.testFunction -# Starting class: Test_turning_on -ok 3 Test_turning_on.testFunction -# Starting class: testLockWait -ok 4 testLockWait.testFunction -# Ran 4 tests in 0.001 seconds, 4 successes, 0 failures -~~~~~~~~~~ BEGIN ALL TESTS ~~~~~~~~~~ -1..59 -# Started on Tue Oct 30 10:32:48 2018 -# Starting class: testAssertEquals -~~~~~ Begin Test ~~~~~ -~~~~~ Begin Test Assert Equals ~~~~~ -~~~~~ End Test Assert Equals ~~~~~ -~~~~~ End Test ~~~~~ -ok 1 testAssertEquals.testFunction -# Starting class: testAssertNotEquals -~~~~~ Begin Test ~~~~~ -~~~~~ End Test ~~~~~ -ok 2 testAssertNotEquals.testFunction -# Starting class: testAssertItemsEquals -~~~~~ Begin Test ~~~~~ -[...] -~~~~~ End Test ~~~~~ -ok 57 testAssertVerbStatusError.testFunction -# Starting class: testAssertVerbResponseEqualsError -~~~~~ Begin Test ~~~~~ -~~~~~ End Test ~~~~~ -ok 58 testAssertVerbResponseEqualsError.testFunction -# Starting class: testAssertVerbCbError -~~~~~ Begin Test ~~~~~ -~~~~~ End Test ~~~~~ -ok 59 testAssertVerbCbError.testFunction -# Ran 59 tests in 0.003 seconds, 59 successes, 0 failures -~~~~~~~~~~ END ALL TESTS ~~~~~~~~~~ -Tests correctly launched. -``` - -## Launch test on a target board - -If you are trying to launch your test on a target you'll have to use -a test widget which contains test files, fixture and configuration. -Then use **afm-test**: - -```bash -# afm-test -h -Usage: /usr/bin/afm-test [-l|--lava] [-v|--verb ] --l|--lavaoutput: flag that enable Lava test marker to the output. (Default: disabled) --v|--verb: select a specific verb to launch from the test API. (Default: all) -path: path to the test wgt file -``` - -By default, the test widgets should be located in /usr/AGL/apps/testwgt. This -will install the widget, launch the tests then display the result on standard -output. After that it will kill test binding and remove it. - -### Example on a target - -Here is an example: - -```bash -qemux86-64:~# afm-test /usr/AGL/apps/testwgt/aftest-test.wgt -afm-test /tmp/aftest-test.wgt -PASS: aftest-test@6.90 started with pid=1649 -1..59 -~~~~~ Begin Test ~~~~~ -~~~~~ Begin Test Assert Equals ~~~~~ -~~~~~ End Test Assert Equals ~~~~~ -~~~~~ End Test ~~~~~ -PASS: 1 testAssertEquals.testFunction -~~~~~ Begin Test ~~~~~ -~~~~~ End Test ~~~~~ -PASS: 2 testAssertNotEquals.testFunction -~~~~~ Begin Test ~~~~~ -~~~~~ End Test ~~~~~ -PASS: 3 testAssertItemsEquals.testFunction -~~~~~ Begin Test ~~~~~ -~~~~~ End Test ~~~~~ -[...] -PASS: 58 testAssertVerbResponseEqualsError.testFunction -~~~~~ Begin Test ~~~~~ -~~~~~ End Test ~~~~~ -PASS: 59 testAssertVerbCbError.testFunction -# Ran 59 tests in 0.003 seconds, 59 successes, 0 failures -~~~~~~~~~~ END ALL TESTS ~~~~~~~~~~ -1..63 -~~~~~ Begin Test ~~~~~ -~~~~~ Begin Test Assert Equals ~~~~~ -~~~~~ End Test Assert Equals ~~~~~ -~~~~~ End Test ~~~~~ -PASS: 1 testAssertEquals.testFunction -~~~~~ Begin Test ~~~~~ -~~~~~ End Test ~~~~~ -PASS: 2 testAssertNotEquals.testFunction -~~~~~ Begin Test ~~~~~ -~~~~~ End Test ~~~~~ -PASS: 3 testAssertItemsEquals.testFunction -~~~~~ Begin Test ~~~~~ -~~~~~ End Test ~~~~~ -[...] -~~~~~ Begin Test ~~~~~ -~~~~~ End Test ~~~~~ -PASS: 61 TestGetVerb.testFunction -~~~~~ Begin Test ~~~~~ -~~~~~ End Test ~~~~~ -PASS: 62 Test_turning_on.testFunction -~~~~~ Begin Test ~~~~~ -~~~~~ End Test ~~~~~ -PASS: 63 testLockWait.testFunction -# Ran 63 tests in 0.003 seconds, 63 successes, 0 failures -~~~~~~~~~~ END ALL TESTS ~~~~~~~~~~ -PASS: aftest-test@6.90 killed and removed -``` - -The command being : ```afm-test /usr/AGL/apps/testwgt/aftest-test.wgt``` - -You can see here that everything ran as on your pc terminal. -**Begin Test** and **End Test** are the -beforeEach and afterEach functions and -**END ALL TESTS** is the after all functions. - - **PASS :** shows the function that is or was running. diff --git a/docs/4_APIs_and_Services/4.4_AGL_Test_Framework/4_Tests_Examples/Tests_Examples.md b/docs/4_APIs_and_Services/4.4_AGL_Test_Framework/4_Tests_Examples/Tests_Examples.md deleted file mode 100644 index a69496b..0000000 --- a/docs/4_APIs_and_Services/4.4_AGL_Test_Framework/4_Tests_Examples/Tests_Examples.md +++ /dev/null @@ -1,119 +0,0 @@ ---- -edit_link: '' -title: Tests examples -origin_url: >- - https://git.automotivelinux.org/apps/app-afb-test/plain/docs/4_Tests_Examples.md?h=master ---- - - - -# Test example - -To launch the binding use the command-line provided at the end of the build, -and the afb-daemon-demo just like in the example below. This will launch the -test of an Helloworld binding example. Tests's codes are available in the LUA -files `conf.d/controller/lua.d/helloworld.lua` and -`conf.d/controller/lua.d/aftTest.lua`. - -The example will run some basics tests on API verb calls and events received. - -## helloworld.lua - -```lua - function _callback(responseJ) - _AFT.assertStrContains(responseJ.response, "Some String") - end - - function _callbackError(responseJ) - _AFT.assertStrContains(responseJ.request.info, "Ping Binder Daemon fails") - end - - function _callbackEvent(eventName, eventData) - _AFT.assertEquals(eventData, {data = { key = 'weird others data', another_key = 123.456 }}) - end - - _AFT.addEventToMonitor("hello/anEvent") - _AFT.addEventToMonitor("hello/anotherEvent", _callbackEvent) - - _AFT.testVerbStatusSuccess('testPingSuccess','hello', 'ping', {}) - _AFT.testVerbResponseEquals('testPingSuccess','hello', 'ping', {}, "Some String") - _AFT.testVerbResponseEquals('testPingSuccess','hello', 'ping', {}, "Unexpected String") - _AFT.testVerbCb('testPingSuccess','hello', 'ping', {}, _callback) - _AFT.testVerbStatusError('testPingError', 'hello', 'pingfail', {}) - _AFT.testVerbResponseEqualsError('testPingError', 'hello', 'pingfail', {}, "Ping Binder Daemon fails") - _AFT.testVerbResponseEqualsError('testPingError', 'hello', 'pingfail', {}, "Ping Binder Daemon succeed") - _AFT.testVerbCbError('testPingError', 'hello', 'pingfail', {}, _callbackError) - - _AFT.testVerbStatusSuccess('testEventAdd', 'hello', 'eventadd', {tag = 'event', name = 'anEvent'}) - _AFT.testVerbStatusSuccess('testEventSub', 'hello', 'eventsub', {tag = 'event'}) - _AFT.testVerbStatusSuccess('testEventPush', 'hello', 'eventpush', {tag = 'event', data = { key = 'some data', another_key = 123}}) - - _AFT.testVerbStatusSuccess('testEventAdd', 'hello', 'eventadd', {tag = 'evt', name = 'anotherEvent'}) - _AFT.testVerbStatusSuccess('testEventSub', 'hello', 'eventsub', {tag = 'evt'}) - _AFT.testVerbStatusSuccess('testEventPush', 'hello', 'eventpush', {tag = 'evt', data = { key = 'weird others data', another_key = 123.456}}) - - _AFT.testVerbStatusSkipped('testEventSub', 'hello', 'eventsub', {tag = 'evt'}) - - _AFT.testVerbStatusSuccess('testGenerateWarning', 'hello', 'verbose', {level = 4, message = 'My Warning message!'}) - - _AFT.testEvtGrpReceived("TestEventGroupReceived",{"hello/anEvent","hello/anotherEvent"},300000) - _AFT.testEvtGrpNotReceived("TestEventGroupNotReceived",{"hello/anEvent","hello/anotherEvent"},300000) - - _AFT.testEvtReceived("testEvent", "hello/anEvent",300000) - _AFT.testEvtReceived("testEventCb", "hello/anotherEvent",300000) - - _AFT.describe("myTestLabel", function() - _AFT.assertEquals(false, false) - end) -``` - -## aftTest.lua - -```lua -_AFT.setBeforeEach(function() print("~~~~~ Begin Test ~~~~~") end) -_AFT.setAfterEach(function() print("~~~~~ End Test ~~~~~") end) - -_AFT.setBeforeAll(function() print("~~~~~~~~~~ BEGIN ALL TESTS ~~~~~~~~~~") return 0 end) -_AFT.setAfterAll(function() print("~~~~~~~~~~ END ALL TESTS ~~~~~~~~~~") return 0 end) - - -local corout = coroutine.create( print ) - -_AFT.describe("testAssertEquals", function() _AFT.assertEquals(false, false) end, - function() print("~~~~~ Begin Test Assert Equals ~~~~~") end, - function() print("~~~~~ End Test Assert Equals ~~~~~") end) - -_AFT.describe("testAssertNotEquals", function() _AFT.assertNotEquals(true,false) end) -_AFT.describe("testAssertItemsEquals", function() _AFT.assertItemsEquals({1,2,3},{3,1,2}) end) -_AFT.describe("testAssertAlmostEquals", function() _AFT.assertAlmostEquals(1.25 ,1.5,0.5) end) -_AFT.describe("testAssertNotAlmostEquals", function() _AFT.assertNotAlmostEquals(1.25,1.5,0.125) end) -_AFT.describe("testAssertEvalToTrue", function() _AFT.assertEvalToTrue(true) end) -_AFT.describe("testAssertEvalToFalse", function() _AFT.assertEvalToFalse(false) end) - -_AFT.describe("testAssertStrContains", function() _AFT.assertStrContains("Hello I'm a string","string") end) -_AFT.describe("testAssertStrContains", function() _AFT.assertStrContains("Hello I'm a second string","second",5) end) - -_AFT.describe("testAssertStrIContains", function() _AFT.assertStrIContains("Hello I'm another string","I'm") end) - -_AFT.describe("testAssertNotStrContains", function() _AFT.assertNotStrContains("Hello it's me again, the other string","banana") end) -_AFT.describe("testAssertNotStrContains", function() _AFT.assertNotStrContains("Hello it's me again, the other string","banana",8) end) -... -... -... -_AFT.describe("testAssertNotIsUserdata", function() _AFT.assertNotIsUserdata(2) end) - - -function _callback(responseJ) _AFT.assertStrContains(responseJ.response, "Some String") end -function _callbackError(responseJ) _AFT.assertStrContains(responseJ.request.info, "Ping Binder Daemon fails") end - -_AFT.describe("testAssertVerbStatusSuccess",function() _AFT.assertVerbStatusSuccess('hello', 'ping', {}) end) -_AFT.describe("testAssertVerbStatusSkipped",function() _AFT.assertVerbStatusSkipped('hello', 'ping', {}) end) -_AFT.describe("testAssertVerbResponseEquals",function() _AFT.assertVerbResponseEquals('hello', 'ping', {},"Some String") end) -_AFT.describe("testAssertVerbCb",function() _AFT.assertVerbCb('hello', 'ping', {},_callback) end) -_AFT.describe("testAssertVerbStatusError",function() _AFT.assertVerbStatusError('hello', 'pingfail', {}) end) -_AFT.describe("testAssertVerbResponseEqualsError",function() _AFT.assertVerbResponseEqualsError('hello', 'pingfail', {},"Ping Binder Daemon fails") end) -_AFT.describe("testAssertVerbCbError",function() _AFT.assertVerbCbError('hello', 'pingfail', {},_callbackError) end) -``` - -> **NOTE**: I suggest you to take this lua file example to make your own test -> then read the following chapter if needed to write more complex tests. diff --git a/docs/4_APIs_and_Services/4.4_AGL_Test_Framework/5_Reference/1_BindingTestFunctions/BindingTestFunctions.md b/docs/4_APIs_and_Services/4.4_AGL_Test_Framework/5_Reference/1_BindingTestFunctions/BindingTestFunctions.md deleted file mode 100644 index 0ca593e..0000000 --- a/docs/4_APIs_and_Services/4.4_AGL_Test_Framework/5_Reference/1_BindingTestFunctions/BindingTestFunctions.md +++ /dev/null @@ -1,121 +0,0 @@ ---- -edit_link: '' -title: Binding Test Functions -origin_url: >- - https://git.automotivelinux.org/apps/app-afb-test/plain/docs/Reference/0_BindingTestFunctions.md?h=master ---- - - - -# Binding Test functions - -* **_AFT.testVerbStatusSuccess(testName, api, verb, args, setUp, tearDown)** - - Simply test that the call of a verb successfully returns. - - *setUp* and *tearDown* are functions that can be added to your context, - it works just like **_AFT.beforeEach()** and **_AFT.afterEach()**, - *setUp* will be ran before your *testFunction* and **_AFT.beforeEach()** - (if set) functions, *tearDown* will be ran after your *testFunction* and - **_AFT.afterEach()** (if set) functions. - -* **_AFT.testVerbStatusError(testName, api, verb, args, setUp, tearDown)** - - The inverse than above. - - *setUp* and *tearDown* are functions that can be added to your context, - it works just like **_AFT.beforeEach()** and **_AFT.afterEach()**, - *setUp* will be ran before your *testFunction* and **_AFT.beforeEach()** - (if set) functions, *tearDown* will be ran after your *testFunction* and - **_AFT.afterEach()** (if set) functions. - -* **_AFT.testVerbStatusSkipped(testName, api, verb, args, setUp, tearDown, msg)** - - Skip a test. - - *msg* is a message to indicate the reason why the test is skip, - it must contain your test name if you want to parse the output. - *setUp* and *tearDown* are functions that can be added to your context, - it works just like **_AFT.beforeEach()** and **_AFT.afterEach()**, - *setUp* will be ran before your *testFunction* and **_AFT.beforeEach()** - (if set) functions, *tearDown* will be ran after your *testFunction* and - **_AFT.afterEach()** (if set) functions. - -* **_AFT.testVerbResponseEquals(testName, api, verb, args, expectedResponse, setUp, tearDown)** - - Test that the call of a verb successfully returns and that verb's response - is equals to the *expectedResponse*. - - *setUp* and *tearDown* are functions that can be added to your context, - it works just like **_AFT.beforeEach()** and **_AFT.afterEach()**, *setUp* - will be ran before your *testFunction* and **_AFT.beforeEach()** (if set) - functions, *tearDown* will be ran after your *testFunction* and - **_AFT.afterEach()** (if set) functions. - -* **_AFT.testVerbResponseEqualsError(testName, api, verb, args, expectedResponse, setUp, tearDown)** - - The inverse than above. - - *setUp* and *tearDown* are functions that can be added to your context, it works - just like **_AFT.beforeEach()** and **_AFT.afterEach()**, *setUp* will be ran - before your *testFunction* and **_AFT.beforeEach()** (if set) functions, - *tearDown* will be ran after your *testFunction* and **_AFT.afterEach()** (if - set) functions. - -* **_AFT.testVerbCb(testName, api, verb, args, expectedResponse, callback, setUp, tearDown)** - - Test the call of a verb with a custom callback. From this callback you - will need to make some assertions on what you need (verb JSON return object - content mainly). - - If you don't need to test the response simply specify an empty LUA table. - - *setUp* and *tearDown* are functions that can be added to your context, it works - just like **_AFT.beforeEach()** and **_AFT.afterEach()**, *setUp* will be ran - before your *testFunction* and **_AFT.beforeEach()** (if set) functions, - *tearDown* will be ran after your *testFunction* and **_AFT.afterEach()** (if - set) functions. - -* **_AFT.testVerbCbError(testName, api, verb, args, expectedResponse, callback, setUp, tearDown)** - - Should return success on failure. - - *setUp* and *tearDown* are functions that can be added to your context, it works - just like **_AFT.beforeEach()** and **_AFT.afterEach()**, *setUp* will be ran - before your *testFunction* and **_AFT.beforeEach()** (if set) functions, - *tearDown* will be ran after your *testFunction* and **_AFT.afterEach()** (if - set) functions. - -* **_AFT.testEvtReceived(testName, eventName, timeout, setUp, tearDown)** - - Prior to be able to check that an event has been received, you have to - register the event with the test framework using **_AFT.addEventToMonitor** - function. - - Check if an event has been correctly received in time (timeout in µs). An event - name use the application framework naming scheme: **api/event_name**. - -* **_AFT.testEvtNotReceived(testName, eventName, timeout, setUp, tearDown)** - - Prior to be able to check that an event has not been received, you have to - register the event with the test framework using **_AFT.addEventToMonitor** - function. - - Check if an event has not been correctly received in time (timeout in µs). An - event name use the application framework naming scheme: **api/event_name**. - -* **_AFT.testGrpEvtReceived(testName, eventGrp, timeout, setUp, tearDown)** - - Prior to be able to check that a group of event (a table of event) has been - received, you have to register the event with the test framework using - **_AFT.addEventToMonitor** function. - - The table has to have this format: -```lua - eventGrp = {["api/event_name_1"]=1,["api/event_name_2"]=2,["api/event_name_3"]=5} -``` - As you can see, in the table, event names are table keys and the value stored are - the number of time that the events have to be received. - - Check if events has been correctly received in time (timeout in µs). An - event name use the application framework naming scheme: **api/event_name**. diff --git a/docs/4_APIs_and_Services/4.4_AGL_Test_Framework/5_Reference/2_BindingAssertFunctions/2_BindingAssertFunctions.md b/docs/4_APIs_and_Services/4.4_AGL_Test_Framework/5_Reference/2_BindingAssertFunctions/2_BindingAssertFunctions.md deleted file mode 100644 index b696555..0000000 --- a/docs/4_APIs_and_Services/4.4_AGL_Test_Framework/5_Reference/2_BindingAssertFunctions/2_BindingAssertFunctions.md +++ /dev/null @@ -1,79 +0,0 @@ ---- -edit_link: '' -title: Binding Assert Functions -origin_url: >- - https://git.automotivelinux.org/apps/app-afb-test/plain/docs/Reference/1_BindingAssertFunctions.md?h=master ---- - - - -# Binding Assert functions - -* **_AFT.assertVerbStatusSuccess(api, verb, args)** - - Simply test that the call of a verb successfully returns. - -* **_AFT.assertVerbStatusError(api, verb, args)** - - The inverse than above. - -* **_AFT.assertVerbStatusSkipped(api, verb, args, msg)** - - Skip a test. - - *msg* must contain your test name if you want to parse the output. - -* **_AFT.assertVerbResponseEquals(api, verb, args, expectedResponse)** - - Test that the call of a verb successfully returns and that verb's response - is equals to the *expectedResponse*. - -* **_AFT.assertVerbResponseEqualsError(api, verb, args, expectedResponse)** - - The inverse than above. - -* **_AFT.assertVerbCb(api, verb, args, expectedResponse, callback)** - - Test the call of a verb with a custom callback. From this callback you - will need to make some assertions on what you need (verb JSON return object - content mainly). - - If you don't need to test the response simply specify an empty LUA table. - -* **_AFT.assertVerbCbError(api, verb, args, expectedResponse, callback)** - - Should return success on failure. - -* **_AFT.assertEvtReceived(eventName, timeout)** - - Prior to be able to check that an event has been received, you have to - register the event with the test framework using **_AFT.addEventToMonitor** - function. - - Check if an event has been correctly received in time (timeout in µs). - An event name use the application framework naming scheme: **api/event_name**. - -* **_AFT.assertEvtNotReceived(eventName, timeout)** - - Prior to be able to check that an event has been received, you have to - register the event with the test framework using **_AFT.addEventToMonitor** - function. - - Check if an event has been correctly received in time (timeout in µs). - An event name use the application framework naming scheme: **api/event_name**. - -* **_AFT.assertGrpEvtReceived(eventGrp, timeout)** - - Prior to be able to check that a group of event (a table of event) has been - received, you have to register the event with the test framework using - **_AFT.addEventToMonitor** function. - - The table has to have this format: - ```lua - eventGrp = {["api/event_name_1"]=1,["api/event_name_2"]=2,["api/event_name_3"]=5} - ``` - As you can see, in the table, event names are table keys and the value stored are - the number of time that the events have to be received. - - Check if events has been correctly received in time (timeout in µs). - An event name use the application framework naming scheme: **api/event_name**. diff --git a/docs/4_APIs_and_Services/4.4_AGL_Test_Framework/5_Reference/3_TestFrameworkFunctions/3_TestFrameworkFunctions.md b/docs/4_APIs_and_Services/4.4_AGL_Test_Framework/5_Reference/3_TestFrameworkFunctions/3_TestFrameworkFunctions.md deleted file mode 100644 index f2181aa..0000000 --- a/docs/4_APIs_and_Services/4.4_AGL_Test_Framework/5_Reference/3_TestFrameworkFunctions/3_TestFrameworkFunctions.md +++ /dev/null @@ -1,70 +0,0 @@ ---- -edit_link: '' -title: Test Framework Functions -origin_url: >- - https://git.automotivelinux.org/apps/app-afb-test/plain/docs/Reference/2_TestFrameworkFunctions.md?h=master ---- - - - -# Test Framework functions - -* **_AFT.addEventToMonitor(eventName, callback)** - - Add a binding event in the test framework to be able to assert its reception - . You'll need to add as much as events you expect to receive. You could also - specify a callback to test deeper that the event is as you want to. The - callback will happens after the assertion that it has been received so you - can work on data that the event eventually carry. - -* **_AFT.setJunitFile(filePath)** - - Set the *JUnit* file path. When *JUnit* is set as the output type for the - test framework. - -* **_AFT.setBeforeEach(function)** - - Set the **_AFT.beforeEach()** function which is used to run the *function* - before each tests. - -* **_AFT.setAfterEach(function)** - - Set the **_AFT.afterEach()** function which is used to run the *function* - after each tests. - -* **_AFT.setBeforeAll(function)** - - Set the **_AFT.beforeAll()** function which is used to run the *function* - before all tests. If the given function is successful it has to return 0 - else it will return an error. - -* **_AFT.setAfterAll(function)** - - Set the **_AFT.afterAll()** function which is used to run the *function* - after all tests. If the given function is successful it has to return 0 - else it will return an error. - -* **_AFT.describe(testName, testFunction, setUp, tearDown)** - - Give a context to a custom test. *testFunction* will be given the name - provided by *testName* and will be tested. - - *setUp* and *tearDown* are functions that can be added to your context, - it works just like **_AFT.beforeEach()** and **_AFT.afterEach()**, - *setUp* will be ran before your *testFunction* and **_AFT.beforeEach()** - (if set) functions, *tearDown* will be ran after your *testFunction* and - **_AFT.afterEach()** (if set) functions. - -* **_AFT.setBefore(testName, beforeTestFunction)** - - Set a function to be ran at the beginning of the given *testName* function. - -```lua - _AFT.testVerbStatusSuccess('testPingSuccess','hello', 'ping', {}) - _AFT.setBefore("testPingSuccess",function() print("~~~~~ Begin testPingSuccess ~~~~~") end) - _AFT.setAfter("testPingSuccess",function() print("~~~~~ End testPingSuccess ~~~~~") end) -``` - -* **_AFT.setBefore(testName, beforeTestFunction)** - - Set a function to be ran at the end of the given *testName* function. diff --git a/docs/4_APIs_and_Services/4.4_AGL_Test_Framework/5_Reference/4_LuaUnit_Assertion_Functions/0_General_Assertions.md b/docs/4_APIs_and_Services/4.4_AGL_Test_Framework/5_Reference/4_LuaUnit_Assertion_Functions/0_General_Assertions.md deleted file mode 100644 index a66939b..0000000 --- a/docs/4_APIs_and_Services/4.4_AGL_Test_Framework/5_Reference/4_LuaUnit_Assertion_Functions/0_General_Assertions.md +++ /dev/null @@ -1,41 +0,0 @@ ---- -edit_link: '' -title: General Assertions -origin_url: >- - https://git.automotivelinux.org/apps/app-afb-test/plain/docs/Reference/LuaUnitAssertionFunctions/0_GeneralAssertions.md?h=master ---- - - - -# General Assertions - -* **_AFT.assertEquals(actual, expected)** - - Assert that two values are equal. - - For tables, the comparison is a deep comparison : - - * number of elements must be the same - * tables must contain the same keys - * each key must contain the same values. The values are also compared recursively with deep comparison. - - LuaUnit provides other table-related assertions, see [Table assertions](http://luaunit.readthedocs.io/en/luaunit_v3_2_1/#assert-table) - -* **_AFT.assertNotEquals(actual, expected)** - - Assert that two values are different. The assertion fails if the two values are identical. - - It also uses table deep comparison. - -* **_AFT.assertAlmostEquals(actual, expected, margin)** - - Assert that two floating point numbers are almost equal. - - When comparing floating point numbers, strict equality does not work. - Computer arithmetic is so that an operation that mathematically yields - 1.00000000 might yield 0.999999999999 in lua . That’s why you need an - almost equals comparison, where you specify the error margin. - -* **_AFT.assertNotAlmostEquals(actual, expected, margin)** - - Assert that two floating point numbers are not almost equal. \ No newline at end of file diff --git a/docs/4_APIs_and_Services/4.4_AGL_Test_Framework/5_Reference/4_LuaUnit_Assertion_Functions/1_Value_Assertions.md b/docs/4_APIs_and_Services/4.4_AGL_Test_Framework/5_Reference/4_LuaUnit_Assertion_Functions/1_Value_Assertions.md deleted file mode 100644 index f12ac29..0000000 --- a/docs/4_APIs_and_Services/4.4_AGL_Test_Framework/5_Reference/4_LuaUnit_Assertion_Functions/1_Value_Assertions.md +++ /dev/null @@ -1,67 +0,0 @@ ---- -edit_link: '' -title: Value Assertions -origin_url: >- - https://git.automotivelinux.org/apps/app-afb-test/plain/docs/Reference/LuaUnitAssertionFunctions/1_ValueAssertions.md?h=master ---- - - - -# Value assertions - -* **_AFT.assertEvalToTrue(value)** - - Assert that a given value evals to true. Lua coercion rules are applied so - that values like 0,"",1.17 succeed in this assertion. If provided, extra_msg - is a string which will be printed along with the failure message. - -* **_AFT.assertEvalToFalse(Value)** - - Assert that a given value eval to *false*. Lua coercion rules are applied so - that *nil* and *false* succeed in this assertion. If provided, extra_msg is a - string which will be printed along with the failure message. - -* **_AFT.assertIsTrue(value)** - - Assert that a given value compares to true. Lua coercion rules are applied so - that values like 0, "", 1.17 all compare to true. - -* **_AFT.assertIsFalse(value)** - - Assert that a given value compares to false. Lua coercion rules are applied so - that only nil and false all compare to false. - -* **_AFT.assertIsNil(value)** - - Assert that a given value is nil . - -* **_AFT.assertNotIsNil(value)** - - Assert that a given value is not *nil* . Lua coercion rules are applied - so that values like ``0``, ``""``, ``false`` all validate the assertion. - If provided, *extra_msg* is a string which will be printed along with the - failure message. - -* **_AFT.assertIs(actual, expected)** - - Assert that two variables are identical. For string, numbers, boolean and - for nil, this gives the same result as assertEquals() . For the other types, - identity means that the two variables refer to the same object. - - Example : - -```lua - s1='toto' - s2='to'..'to' - t1={1,2} - t2={1,2} - luaunit.assertIs(s1,s1) -- ok - luaunit.assertIs(s1,s2) -- ok - luaunit.assertIs(t1,t1) -- ok - luaunit.assertIs(t1,t2) -- fail -``` - -* **_AFT.assertNotIs(actual, expected)** - - Assert that two variables are not identical, in the sense that they do not - refer to the same value. See assertIs() for more details. diff --git a/docs/4_APIs_and_Services/4.4_AGL_Test_Framework/5_Reference/4_LuaUnit_Assertion_Functions/2_Scientific_Assertions.md b/docs/4_APIs_and_Services/4.4_AGL_Test_Framework/5_Reference/4_LuaUnit_Assertion_Functions/2_Scientific_Assertions.md deleted file mode 100644 index 4c2208a..0000000 --- a/docs/4_APIs_and_Services/4.4_AGL_Test_Framework/5_Reference/4_LuaUnit_Assertion_Functions/2_Scientific_Assertions.md +++ /dev/null @@ -1,57 +0,0 @@ ---- -edit_link: '' -title: Scientific Assertions -origin_url: >- - https://git.automotivelinux.org/apps/app-afb-test/plain/docs/Reference/LuaUnitAssertionFunctions/2_ScientificAssertions.md?h=master ---- - - - -# Scientific assertions - ->**Note** ->If you need to deal with value minus zero, be very careful because Lua versions -are inconsistent on how they treat the >syntax -0 : it creates either a plus -zero or a minus zero. Multiplying or dividing 0 by -1 also yields inconsistent > -results. The reliable way to create the -0 value is : minusZero = -1 / (1/0). - -* **_AFT.assertIsNaN(value)** - Assert that a given number is a *NaN* (Not a Number), according to the - definition of IEEE-754_ . If provided, *extra_msg* is a string which will - be printed along with the failure message. - -* **_AFT.assertIsPlusInf(value)** - - Assert that a given number is *plus infinity*, according to the definition of - IEEE-754_. If provided, *extra_msg* is a string which will be printed along - with the failure message. - -* **_AFT.assertIsMinusInf(value)** - - Assert that a given number is *minus infinity*, according to the definition of - IEEE-754_. If provided, *extra_msg* is a string which will be printed along - with the failure message. - -* **_AFT.assertIsInf(value)** - - Assert that a given number is *infinity* (either positive or negative), - according to the definition of IEEE-754_. If provided, *extra_msg* is a string - which will be printed along with the failure message. - -* **_AFT.assertIsPlusZero(value)** - - Assert that a given number is *+0*, according to the definition of IEEE-754_. - The verification is done by dividing by the provided number and verifying - that it yields *infinity* . If provided, *extra_msg* is a string which will - be printed along with the failure message. - - Be careful when dealing with *+0* and *-0*, see note above - -* **_AFT.assertIsMinusZero(value)** - - Assert that a given number is *-0*, according to the definition of IEEE-754_. - The verification is done by dividing by the provided number and verifying that - it yields *minus infinity* . If provided, *extra_msg* is a string which will - be printed along with the failure message. - - Be careful when dealing with *+0* and *-0* \ No newline at end of file diff --git a/docs/4_APIs_and_Services/4.4_AGL_Test_Framework/5_Reference/4_LuaUnit_Assertion_Functions/3_String_Assertions.md b/docs/4_APIs_and_Services/4.4_AGL_Test_Framework/5_Reference/4_LuaUnit_Assertion_Functions/3_String_Assertions.md deleted file mode 100644 index e465a54..0000000 --- a/docs/4_APIs_and_Services/4.4_AGL_Test_Framework/5_Reference/4_LuaUnit_Assertion_Functions/3_String_Assertions.md +++ /dev/null @@ -1,47 +0,0 @@ ---- -edit_link: '' -title: String Assertions -origin_url: >- - https://git.automotivelinux.org/apps/app-afb-test/plain/docs/Reference/LuaUnitAssertionFunctions/3_StringAssertions.md?h=master ---- - - - -# String assertions - -Assertions related to string and patterns. - -* **_AFT.assertStrContains(str, sub[, useRe])** - - Assert that a string contains the given substring or pattern. - - By default, substring is searched in the string. If useRe is provided and is - true, sub is treated as a pattern which is searched inside the string str. - -* **_AFT.assertStrIContains(str, sub)** - - Assert that a string contains the given substring, irrespective of the case. - - Not that unlike assertStrcontains(), you can not search for a pattern. - -* **_AFT.assertNotStrContains(str, sub, useRe)** - - Assert that a string does not contain a given substring or pattern. - - By default, substring is searched in the string. If useRe is provided and is - true, sub is treated as a pattern which is searched inside the string str. - -* **_AFT.assertNotStrIContains(str, sub)** - - Assert that a string does not contain the given substring, irrespective of - the case. - - Not that unlike assertNotStrcontains(), you can not search for a pattern. - -* **_AFT.assertStrMatches(str, pattern[, start[, final]])** - - Assert that a string matches the full pattern pattern. - - If start and final are not provided or are nil, the pattern must match the - full string, from start to end. The functions allows to specify the expected - start and end position of the pattern in the string. \ No newline at end of file diff --git a/docs/4_APIs_and_Services/4.4_AGL_Test_Framework/5_Reference/4_LuaUnit_Assertion_Functions/4_Error_Assertions.md b/docs/4_APIs_and_Services/4.4_AGL_Test_Framework/5_Reference/4_LuaUnit_Assertion_Functions/4_Error_Assertions.md deleted file mode 100644 index cb181ad..0000000 --- a/docs/4_APIs_and_Services/4.4_AGL_Test_Framework/5_Reference/4_LuaUnit_Assertion_Functions/4_Error_Assertions.md +++ /dev/null @@ -1,39 +0,0 @@ ---- -edit_link: '' -title: Error Assertions -origin_url: >- - https://git.automotivelinux.org/apps/app-afb-test/plain/docs/Reference/LuaUnitAssertionFunctions/4_ErrorAssertions.md?h=master ---- - - - -# Error assertions - -Error related assertions, to verify error generation and error messages. - -* **_AFT.assertError(func, ...)** - - Assert that calling functions func with the arguments yields an error. If the function does not yield an error, the assertion fails. - - Note that the error message itself is not checked, which means that this function does not distinguish between the legitimate error that you expect and another error that might be triggered by mistake. - - The next functions provide a better approach to error testing, by checking explicitly the error message content. - ->**Note** ->When testing LuaUnit, switching from assertError() to assertErrorMsgEquals() revealed quite a few bugs! - -* **_AFT.assertErrorMsgEquals(expectedMsg, func, ...)** - - Assert that calling function func will generate exactly the given error message. If the function does not yield an error, or if the error message is not identical, the assertion fails. - - Be careful when using this function that error messages usually contain the file name and line number information of where the error was generated. This is usually inconvenient. To ignore the filename and line number information, you can either use a pattern with assertErrorMsgMatches() or simply check if the message contains a string with assertErrorMsgContains() . - -* **_AFT.assertErrorMsgContains(partialMsg, func, ...)** - - Assert that calling function func will generate an error message containing partialMsg . If the function does not yield an error, or if the expected message is not contained in the error message, the assertion fails. - -* **_AFT.assertErrorMsgMatches(expectedPattern, func, ...)** - - Assert that calling function func will generate an error message matching expectedPattern . If the function does not yield an error, or if the error message does not match the provided pattern the assertion fails. - - Note that matching is done from the start to the end of the error message. Be sure to escape magic all magic characters with % (like -+.?\*) . \ No newline at end of file diff --git a/docs/4_APIs_and_Services/4.4_AGL_Test_Framework/5_Reference/4_LuaUnit_Assertion_Functions/5_Type_Assertions.md b/docs/4_APIs_and_Services/4.4_AGL_Test_Framework/5_Reference/4_LuaUnit_Assertion_Functions/5_Type_Assertions.md deleted file mode 100644 index 7e49d85..0000000 --- a/docs/4_APIs_and_Services/4.4_AGL_Test_Framework/5_Reference/4_LuaUnit_Assertion_Functions/5_Type_Assertions.md +++ /dev/null @@ -1,47 +0,0 @@ ---- -edit_link: '' -title: Type Assertions -origin_url: >- - https://git.automotivelinux.org/apps/app-afb-test/plain/docs/Reference/LuaUnitAssertionFunctions/5_TypeAssertions.md?h=master ---- - - - -# Type assertions - -The following functions all perform type checking on their argument. If the -received value is not of the right type, the failure message will contain the -expected type, the received type and the received value to help you identify -better the problem. - -* **_AFT.assertIsNumber(value)** - - Assert that the argument is a number (integer or float) - -* **_AFT.assertIsString(value)** - - Assert that the argument is a string. - -* **_AFT.assertIsTable(value)** - - Assert that the argument is a table. - -* **_AFT.assertIsBoolean(value)** - - Assert that the argument is a boolean. - -* **_AFT.assertIsFunction(value)** - - Assert that the argument is a function. - -* **_AFT.assertIsUserdata(value)** - - Assert that the argument is a userdata. - -* **_AFT.assertIsThread(value)** - - Assert that the argument is a coroutine (an object with type thread ). - -* **_AFT.assertNotIsThread(value)** - - Assert that the argument is a not coroutine (an object with type thread ). \ No newline at end of file diff --git a/docs/4_APIs_and_Services/4.4_AGL_Test_Framework/5_Reference/4_LuaUnit_Assertion_Functions/6_Table_Assertions.md b/docs/4_APIs_and_Services/4.4_AGL_Test_Framework/5_Reference/4_LuaUnit_Assertion_Functions/6_Table_Assertions.md deleted file mode 100644 index ab6d1b2..0000000 --- a/docs/4_APIs_and_Services/4.4_AGL_Test_Framework/5_Reference/4_LuaUnit_Assertion_Functions/6_Table_Assertions.md +++ /dev/null @@ -1,28 +0,0 @@ ---- -edit_link: '' -title: Table Assertions -origin_url: >- - https://git.automotivelinux.org/apps/app-afb-test/plain/docs/Reference/LuaUnitAssertionFunctions/6_TableAssertions.md?h=master ---- - - - -# Table assertions - -* **_AFT.assertItemsEquals(actual, expected)** - - Assert that two tables contain the same items, irrespective of their keys. - - This function is practical for example if you want to compare two lists but - where items are not in the same order: - -```lua - luaunit.assertItemsEquals( {1,2,3}, {3,2,1} ) -- assertion succeeds -``` - The comparison is not recursive on the items: if any of the items are tables, - they are compared using table equality (like as in assertEquals() ), where the - key matters. - -```lua - luaunit.assertItemsEquals( {1,{2,3},4}, {4,{3,2,},1} ) -- assertion fails because {2,3} ~= {3,2} -``` diff --git a/docs/4_APIs_and_Services/4.5_Message_Signaling/1_Message_Signaling/architecture.md b/docs/4_APIs_and_Services/4.5_Message_Signaling/1_Message_Signaling/architecture.md deleted file mode 100644 index aaf7e08..0000000 --- a/docs/4_APIs_and_Services/4.5_Message_Signaling/1_Message_Signaling/architecture.md +++ /dev/null @@ -1,476 +0,0 @@ ---- -edit_link: '' -title: Message Signaling -origin_url: >- - https://raw.githubusercontent.com/automotive-grade-linux/docs-sources/master/docs/signaling/architecture.md ---- - - - ---- -title: AGL - Message Signaling Architecture -author: Fulup Ar Foll (IoT.bzh) -date: 2016-06-30 - -categories: architecture, appfw -tags: architecture, signal, message -layout: techdoc - ---- - -**Table of Content** - -1. TOC -{:toc} - -## Context - -Automotive applications need to understand in real time the context in which -vehicles operate. In order to do so, it is critical for automotive application -to rely on a simple, fast and secure method to access data generated by the -multiple sensors/ECU embedded in modern cars. - -This signaling problem is neither new, neither unique to the automotive and -multiple solutions often described as Message Broker or Signaling Gateway have -been around for a while. - -The present document is the now implemented since AGL Daring Dab version, to -handle existing signaling/message in a car. It relies on [[APbinder]] -binder/bindings model to minimize complexity while keeping the system fast -around secure. We propose a model with multiple transport options and a full set -of security feature to protect the service generating the signal as well as -consuming them. - -## Objectives - -Our objectives are solving following 3 key issues: - -1. reduce as much as possible the amount of exchanged data to the meaningful - subset really used by applications -1. offer a high level API that obfuscates low level and proprietary interface to - improve stability in time of the code -1. hide specificities of low level implementation as well as the chosen - deployment distribution model. - -To reach first objective, events emission frequency should be controlled at the -lowest level it possibly can. Aggregation, composition, treatment, filtering of -signals should be supported at software level when not supported by the hardware. - -Second objectives of offering long term stable hight level API while allowing -flexibility in changing low level implementation may look somehow conflicting. -Nevertheless by isolating low level interface from high level and allowing -dynamic composition it is possible to mitigate both objectives. - -## Architecture - -Good practice is often based on modularity with clearly separated components -assembled within a common framework. Such modularity ensures separation of -duties, robustness, resilience and achievable long term maintenance. - -This document uses the term "**Service**" to define a specific instance of this -proposed common framework used to host a group of dedicated separated components -that handle targeted signals/events. Each service exposes to services/applications -the signals/events it is responsible for. - -As an example, a CAN service may want to mix non-public proprietary API with -CANopen compatible devices while hiding this complexity to applications. The -goal is on one hand to isolate proprietary piece of code in such a way that it -is as transparent as possible for the remaining part of the architecture. On a -second hand isolation of code related to a specific device provides a better -separation of responsibilities, keeping all specificity related to a given -component clearly isolated and much easier to test or maintain. Last but not -least if needed this model may also help to provide some proprietary code -directly as binary and not as source code. - -Communicating between the car and regular apps should be done using a 2 levels -AGL services which have two distincts roles: - -- low level should handle communication with CAN bus device (read, decoding, - basic and efficient filtering, caching, ...) -- high level should handle more complex tasks (signals compositions, complex - algorythms like Kalman filter, business logic...) - -![image](images/signal-service-arch.svg "Signal Agent Architecture") - -To do so, the choice has been to use a similar architecture than [[OpenXC]], a -Ford project. Principle is simple, from a JSON file that describes all CAN -signals wanted to be handled, in general a conversion from a **dbc** file, AGL -generator convert it to a C++ source code file. This file which in turn is used -as part of the low level CAN service which can now be compiled. This service -reads, decodes and serves this CAN signals to a high level CAN service that -holds business logic and high level features like described is the above -chapter. - -![image](images/can-generator.svg "AGL CAN generator") - -While in some cases it may be chosen to implement a single service responsible -for everything, other scenarii may chose to split responsibility between -multiple services. Those multiple services may run on a single ECU or on -multiple ECUs. Chosen deployment distribution strategy should not impact the -development of components responsible for signals/events capture. As well as it -should have a loose impact on applications/services consuming those events. - -A distributed capable architecture may provide multiple advantages: - -- it avoids to concentrate complexity in a single big/fat component. -- it leverages naturally multiple ECUs and existing network architecture -- it simplifies security by enabling isolation and sandboxing -- it clearly separates responsibilities and simplifies resolution of conflicts - -Distributed architecture has to be discussed and about now is not fully -implemented. Low level CAN service isn't fully functional nor tested to assume -this feature but its architecture let the possibility open and will be -implemented later. - -![image](images/distributed-arch.png "Distributed Architecture") - -Performance matters. There is a trade-off between modularity and efficiency. -This is specially critical for signals where propagation time from one module to -the other should remain as short as possible and furthermore should consume as -little computing resources as possible. - -A flexible solution should provide enough versatility to either compose modules -in separate processes; either chose a model where everything is hosted within a -single process. Chosen deployment model should have minor or no impact on -development/integration processes. Deployment model should be something easy to -change, it should remain a tactical decision and never become a structuring -decision. - -Nevertheless while grouping modules may improve performance and reduce resource consumption, on the other hand, -it has a clear impact on security. No one should forget that some signals have very different level of security from other ones. -Mixing everything within a single process makes all signal's handling within a single security context. -Such a decision may have a significant impact on the level on confidence one may have in the global system. - -Providing such flexibility constrains the communication model used by modules: - -- The API of integration of the modules (the API of the framework) that enables - the connection of modules must be independent of the implementation of - the communication layer -- The communication layer must be as transparent as possible, its - implementation shouldn't impact how it is used -- The cost of the abstraction for modules grouped in a same process - must be as little as possible -- The cost of separating modules with the maximum of security must remain as - minimal as possible - -Another point impacting performance relates to a smart limitation on the number -of emitted signals. Improving the cost of sending a signal is one thing, -reducing the number of signals is an other one. No one should forget that the -faster you ignore a useless signal the better it is. The best way to achieve -this is by doing the filtering of useless signal as close as possible of the -component generating the signal and when possible directly at the hardware level. - -To enable the right component to filter useless signals, consumer clients must -describe precisely the data they need. A filter on frequency is provided since -Daring Dab version, as well as minimum and maximum limits. These filters can be -specified at subscription time. Also, any data not required by any client should -at the minimum never be transmitted. So only changed data is transmitted and if -another service needs to receive at a regular time, it has to assume that if no -events are received then it is that the value hasn't change. Furthermore when -possible then should even not be computed at all, a CAN signal received on -socket is purely ignored if no one asks for it. - -Describing expected data in a precise but nevertheless simple manner remains a -challenge. It implies to manage: - -- requested frequency of expected data -- accuracy of data to avoid detection of inaccurate changes -- when signaling is required (raising edge, falling edge, - on maintained state, ...), -- filtering of data to avoid glitches and noise, -- composition of signals both numerically and logically (adding, - subtracting, running logical operators like AND/OR/XOR, getting the mean, ...) -- etc... - -It is critical to enable multiple features in signal queries to enable modules -to implement the best computing method. The best computing method may have an -impact on which device to query as well as on which filters should be applied. -Furthermore filtering should happen as soon as possible and obviously when -possible directly at hardware level. - -### Transport Solutions - -D-Bus is the standard choice for Linux, nevertheless it has some serious -performance limitation due to internal verbosity. Nevertheless because it is -available and pre-integrated with almost every Linux component, D-Bus may still -remains an acceptable choice for signal with low rate of emission (i.e. HMI). - -For a faster communication, Jaguar-Land-Rover proposes a memory shared signal -infrastructure. Unfortunately this solution is far from solving all issues and -has some drawbacks. Let check the open issues it has: - -- there is no management of what requested data are. This - translate in computing data even when not needed. -- on top of shared memory, an extra side channel is required for processes - to communicate with the daemon. -- a single shared memory implies a lot of concurrency handling. This might - introduce drawbacks that otherwise would be solved through communication - buffering. - -ZeroMQ, NanoMSG and equivalent libraries focused on fast communication. Some -(e.g. ZeroMQ) come with a commercial licensing model when others (e.g. NanoMSG) -use an open source licensing. Those solutions are well suited for both -communicating inside a unique ECU or across several ECUs. However, most of them -are using Unix domain sockets and TCP sockets and typically do not use shared -memory for inter-process communication. - -Last but not least Android binder, Kdbus and other leverage shared memory, zero -copy and sit directly within Linux kernel. While this may boost information -passing between local processes, it also has some limitations. The first one is -the non support of a multi-ECU or vehicle to cloud distribution. The second one -is that none of them is approved upstream in kernel tree. This last point may -create some extra burden each time a new version of Linux kernel is needed or -when porting toward a new hardware is required. - -### Query and Filtering Language - -Description language for filtering of expected data remains an almost green -field where nothing really fit signal service requirements. Languages like -Simulink or signal processing graphical languages are valuable modelling tools. -Unfortunately they cannot be inserted in the car. Furthermore those languages -have many features that are not useful in proposed signal service context and -cost of integrating such complex languages might not be justified for something -as simple as a signal service. The same remarks apply for automation languages. - -Further investigations leads to some specifications already presents like the -one from Jaguar Land Rover [[VISS]], for **Vehicule Information Service -Specification** and another from Volkwagen AG named [[ViWi]], stand for -**Volkwagen Infotainment Web Interface**. Each ones has their differences and -provides different approach serving the same goal: - -| VISS | ViWi | -|---------------------------------------------------------------|-----------------------------------------------------------------| -| Filtering on node (not possible on several nodes or branches) | Describe a protocol | -| Access restrictions to signals | Ability to specify custom signals | -| Use high level development languages | RESTful HTTP calls | -| One big Server that handle requests | Stateless | -| Filtering | Filtering, sorting | -| Static signals tree not extensible [[VSS]] | Use JSON objects to communicate | -| Use of AMB ? | Identification of resources may be a bit heavy going using UUID | -| Use of Websocket | | - -About **[[VISS]]** specification, the major problem comes from the fact that -signals are specified under the [[VSS]], **Vehicle Signal Specification**. So, -problem is that it is difficult, if not impossible, to make a full inventory -of all signals existing for each car. More important, each evolution in signals -must be reported in the specification and it is without seeing the fact that -car makers have their names and set of signals that would mostly don't -comply with the [[VSS]]. VISS doesn't seems to be an valuable way to handle -car's signals, a big component that responds requests, use of **Automotive -Message Broker** that use DBus is a performance problem. Fujitsu Ten recent -study[[1]] highlights that processor can't handle an heavy load on CAN bus and -that Low level binding adopted for AGL is about 10 times[[2]] less impact on -performance. - -## Describing Signal Subscriptions using JSON - -JSON is a rich structured representation of data. For requested data, it allows -the expression of multiple features and constraints. JSON is both very flexible -and efficient. There are significant advantages in describing requested data at -subscription time using a language like JSON. Another advantage of JSON is that -no parser is required to analyse the request. - -Existing works exists to describe a signals that comes first from Vector with -its proprietary database (`DBC`) which widely used in industry. Make a -description based on this format appears to be a good solution and Open Source -community already has existing tools that let you convert proprietary file -format to an open one. So, a JSON description based on work from [[OpenXC]] is -specified [here](https://github.com/openxc/vi-firmware/blob/master/docs/config/reference.rst) -which in turn is used in Low level CAN service in AGL: - -```json -{ "name": "example", - "extra_sources": [], - "initializers": [], - "loopers": [], - "buses": {}, - "commands": [], - "0x3D9": { - "bus": "hs", - "signals": { - "PT_FuelLevelPct": { - "generic_name": "fuel.level", - "bit_position": 8, - "bit_size": 8, - "factor": 0.392157, - "offset": 0 - }, - "PT_EngineSpeed": { - "generic_name": "engine.speed", - "bit_position": 16, - "bit_size": 16, - "factor": 0.25, - "offset": 0 - }, - "PT_FuelLevelLow": { - "generic_name": "fuel.level.low", - "bit_position": 55, - "bit_size": 1, - "factor": 1, - "offset": 0, - "decoder": "decoder_t::booleanDecoder" - } - } - } -} -``` - -From a description like the above one, low level CAN generator will output -a C++ source file which let low level CAN service that uses it to handle such -signal definition. - -## Naming Signal - -Naming and defining signals is something very complex. For example just -***speed***, as a signal, is difficult to define. -What unit is used (km/h, M/h, m/s, ...)? -From which source (wheels, GPS, AccelMeter)? -How was it captured (period of measure, instantaneous, mean, filtered)? - -In order to simplify application development we should nevertheless agree on -some naming convention for key signals. Those names might be relatively complex -and featured. They may include a unit, a rate, a precision, etc. - -How these names should be registered, documented and managed is out of scope of -this document but extremely important and at some point in time should be -addressed. Nevertheless this issue should not prevent from moving forward -developing a modern architecture. Developers should be warned that naming is a -complex task, and that in the future naming scheme should be redefined, and -potential adjustments would be required. - -About Low level CAN signals naming a doted notation, like the one used by Jaguar -Landrover, is a good compromise as it describe a path to an car element. It -separates and organize names into hierarchy. From the left to right, you -describe your names using the more common ancestor at the left then more you go -to the right the more it will be accurate. Using this notation let you subscribe -or unsubscribe several signals at once using a globbing expression. - -Example using OBD2 standard PID: - -```path -engine.load -engine.coolant.temperature -fuel.pressure -intake.manifold.pressure -engine.speed -vehicle.speed -intake.air.temperature -mass.airflow -throttle.position -running.time -EGR.error -fuel.level -barometric.pressure -commanded.throttle.position -ethanol.fuel.percentage -accelerator.pedal.position -hybrid.battery-pack.remaining.life -engine.oil.temperature -engine.torque -``` - -Here you can chose to subscribe to all engine component using an expression -like : `engine.*` - -## Reusing existing/legacy code - -About now provided services use: - -- **Low Level** [[OpenXC]] project provides logic and some useful libraries to - access a CAN bus. It is the choice for AGL. - -- **High Level** In many cases accessing to low level signal is not enough. - Low level information might need to be composed (i.e. GPS+Gyro+Accel). - Writing this composition logic might be quite complex and reusing existing - libraries like: LibEkNav for Kalman filtering [[9]] or Vrgimbal for 3 axes - control[[10]] may help saving a lot of time. AGL apps should access CAN - signals through High Level service. High level can lean on as many low level - service as needed to compute its **Virtual signals** coming from differents - sources. Viwi protocol seems to be a good solution. - -## Leveraging AGL binder - -Such a model is loosely coupled with AGL binder. Low level CAN service as well -as virtual signal components may potentially run within any hosting environment -that would provide the right API with corresponding required facilities. -Nevertheless leveraging [[APbinder]] has multiple advantages. It already -implements event notification to support a messaging/signaling model for -distributed services. It enables a subscribe model responding to the -requirement and finally it uses JSON natively. - -This messaging/signalling model already enforces the notion of subscription for -receiving data. It implies that unexpected data are not sent and merely not -computed. When expected data is available, it is pushed to all waiting -subscriber only one time. - -The [[APbinder]] provides transparency of communication. -It currently implements the transparency over D-Bus/Kdbus and WebSocket. -Its transparency mechanism of communication is easy to extend to other -technologies: pools of shared memory or any proprietary transport model. - -When bindings/services are loaded by the same binder, it provides transparently -`in-memory` communication. This in-memory communication is really efficient: on -one hand, the exchanged JSON objects are not serialized (because not streamed), -on the other hand, those JSON objects provide a high level of abstraction able -to transfer any data. - -Technically a service is a standard [[APbinder]] binding which is also handled -by the system and launched as a daemon by systemD. -Therefore Signal/Agent inherits of security protection through SMACK, access -control through Cynara, transparency of API to transport layer, life cycle -management, ... Like any other [[APbinder]] process is composed of a set of -bindings. In signal service specific case, those bindings are in fact the -`signal modules`. - -The proposed model allows to implement low level dependencies as independent -signal modules. Those modules when developed are somehow like "Lego Bricks". -They can be spread or grouped within one or multiple services depending on -deployment constraints (performance, multi-ECU, security & isolation -constraints,...). - -On top of that low level signal modules, you should use a high level service. -A first implementation of [[ViWi]] is available [here](https://github.com/iotbzh/high-level-viwi-service) -and can be use to integrate business logic and high level features. - -The model naturally uses JSON to represent data. - -## Multi-ECU and Vehicule to Cloud interactions - -While this might not be a show stopper for current projects, it is obvious that -in the near future Signal/Agent should support a fully distributed -architectures. Some event may come from the cloud (i.e. request to start -monitoring a given feature), some may come from SmartCity and nearby vehicles, -and last but not least some may come from another ECU within the same vehicle or -from a virtualized OS within the same ECU (e.g. cluster & IVI). In order to do -so, Signal modules should enable composition within one or more [[APbinder]] -inside the same ECU. Furthermore they should also support chaining with the -outside world. - -![image](images/cloud-arch.svg "Cloud & Multi-ECU Architecture") - -1. Application requests Virtual Signal exactly like if it was a low level signal -1. Agent Signal has direct relation to low level signal -1. Agent needs to proxy to an other service inside the same ECU to access the signal -1. Signal is not present on current ECU. Request has to be proxied to the outside world - -[AppFw]: http://iot.bzh/download/public/2016/appfw/01_Introduction-to-AppFW-for-AGL-1.0.pdf "Application Framework" -[APcore]: http://iot.bzh/download/public/2016/appfw/03_Documentation-AppFW-Core-1.0.pdf "AppFw Core" -[APmain]: https://gerrit.automotivelinux.org/gerrit/#/q/project:src/app-framework-main "AppFw Main" -[APbinder]: https://gerrit.automotivelinux.org/gerrit/#/q/project:src/app-framework-binder "AppFw Binder" -[APsamples]: https://gerrit.automotivelinux.org/gerrit/gitweb?p=src/app-framework-binder.git;a=tree;f=bindings/samples "AppFw Samples" -[Signal-K]: http://signalk.org/overview.html -[1]: http://schd.ws/hosted_files/aglmmwinter2017/37/20170201_AGL-AMM_F10_kusakabe.pdf -[2]: https://wiki.automotivelinux.org/_media/agl-distro/20170402_ften_can_kusakabe_v2.pdf -[6]: https://github.com/otcshare/automotive-message-broker -[7]: http://ardupilot.org/rover/index.html -[8]: https://github.com/ArduPilot/ardupilot/tree/master/libraries -[9]: https://bitbucket.org/jbrandmeyer/libeknav/wiki/Home -[10]: http://ardupilot.org/rover/docs/common-vrgimbal.html -[11]: http://elinux.org/R-Car/Boards/Porter:PEXT01 -[12]: https://github.com/gpsnavi/gpsnavi -[VISS]: http://rawgit.com/w3c/automotive/gh-pages/vehicle_data/vehicle_information_service.html -[VSS]: https://github.com/GENIVI/vehicle_signal_specification -[ViWi]: https://www.w3.org/Submission/2016/SUBM-viwi-protocol-20161213/ -[OpenXC]: http://openxcplatform.com/ -[low level CAN service]: https://gerrit.automotivelinux.org/gerrit/#/admin/projects/src/low-level-can-generator -[high level ViWi]: https://github.com/iotbzh/high-level-viwi-service diff --git a/docs/4_APIs_and_Services/4.5_Message_Signaling/1_Message_Signaling/images/can-generator.svg b/docs/4_APIs_and_Services/4.5_Message_Signaling/1_Message_Signaling/images/can-generator.svg deleted file mode 100644 index f5a567c..0000000 --- a/docs/4_APIs_and_Services/4.5_Message_Signaling/1_Message_Signaling/images/can-generator.svg +++ /dev/null @@ -1,244 +0,0 @@ - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - CAN Low Level Bindng(Shared Library) - - - - - - - - - - - - - - OPENXC SignalDescription(JSON) - - - - - - - - - - - - - - - - - - - - - Low LevelBindingStatic Code(AGL) - - - - - - - - - - - - - - CANDecoding/EncodingC++ Code(vendor) - - - - - - - - - - - - - - OptionalMessageHandlers(vendor) - - - - - - - - - - - - - - - Call for decode/encode - - - - - - - - - - CANConfigGenerator - - - - - - - - - - C/C++Compiler - - - - - - - - - - - - - - OPENXC SignalDescription(JSON) - - - - - - - - - - - - - - OPENXC SignalDescription(JSON) - - - - - - - - \ No newline at end of file diff --git a/docs/4_APIs_and_Services/4.5_Message_Signaling/1_Message_Signaling/images/cloud-arch.svg b/docs/4_APIs_and_Services/4.5_Message_Signaling/1_Message_Signaling/images/cloud-arch.svg deleted file mode 100644 index 3cecbdc..0000000 --- a/docs/4_APIs_and_Services/4.5_Message_Signaling/1_Message_Signaling/images/cloud-arch.svg +++ /dev/null @@ -1,837 +0,0 @@ - -image/svg+xml -Access Control -Transport . -Custer ECU -Access Control -Transport DBUS, WebSocket, ... -NavigationService -Carte handling -POI management -etc... -CAN GPS -GeopositioningVirtualSignal -Multi ECU Architecture -ABS -Publish/Subscribe -IVI ECU -CAN-BUSVirtual Signal -Publish/Subscribe -Gyro, Acelerometer -CAN-BUS -LIN-BUS -ClusterVirtual Signal -Publish/Subscribe -Engine-CAN-BUS -ABS -1 -2 -3 -4 - \ No newline at end of file diff --git a/docs/4_APIs_and_Services/4.5_Message_Signaling/1_Message_Signaling/images/distributed-arch.png b/docs/4_APIs_and_Services/4.5_Message_Signaling/1_Message_Signaling/images/distributed-arch.png deleted file mode 100644 index 3c4f4a0..0000000 Binary files a/docs/4_APIs_and_Services/4.5_Message_Signaling/1_Message_Signaling/images/distributed-arch.png and /dev/null differ diff --git a/docs/4_APIs_and_Services/4.5_Message_Signaling/1_Message_Signaling/images/signal-service-arch.svg b/docs/4_APIs_and_Services/4.5_Message_Signaling/1_Message_Signaling/images/signal-service-arch.svg deleted file mode 100644 index 3dee802..0000000 --- a/docs/4_APIs_and_Services/4.5_Message_Signaling/1_Message_Signaling/images/signal-service-arch.svg +++ /dev/null @@ -1,296 +0,0 @@ - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - Binder - - - - - - - - CAN Low Level Binding(s)Decoding / EncodingAuthentication / Crypto / FirewallingTransaction (set… ack ...)Stats & MathsCaching (low freq. Signals, get() call)Debug - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - CAN High Level Binding(s)LogicAggregation (« vehicle.doors.any.open »)Advanced Ops - - - - - - - - - - - - - - - - - - - - - - - - - CAN BUS - - - - - - - - - - - - - - - - CAN frames - 011010010 - - - - - - - - - Signals - « vehicle.doors.left.open »(Binder Events) - - - - - - - - UI - - - - - - - - Publish Subscribe - - - - - - - - - - - - - - - \ No newline at end of file diff --git a/docs/4_APIs_and_Services/4.5_Message_Signaling/2_AGL_Service_CAN_Low_Level/1_Architecture.md b/docs/4_APIs_and_Services/4.5_Message_Signaling/2_AGL_Service_CAN_Low_Level/1_Architecture.md deleted file mode 100644 index 4606568..0000000 --- a/docs/4_APIs_and_Services/4.5_Message_Signaling/2_AGL_Service_CAN_Low_Level/1_Architecture.md +++ /dev/null @@ -1,34 +0,0 @@ ---- -edit_link: '' -title: Architecture presentation -origin_url: >- - https://git.automotivelinux.org/apps/agl-service-can-low-level/plain/docs/1-Architecture.md?h=master ---- - - - -# AGL CAN binding architecture proposal - -It's meant to generate, from a JSON file describing CAN messages and diagnostic message \(OBD2 for now\), a cpp file to integrate with the project. - -Once generated binding is built with it and result will be a widget file to install on an AGL target system. - -![From OpenXC firmware to AGL binding](images/OpenXC_to_AGL.png) - -Bringing CAN management into the AGL project is more than allowing decode and print CAN messages, lot of tools can do that (Wireshark, CAN-utils, ...). - -The goal is to provide a common API and abstraction to the CAN bus then you can bring some more high level functionalities to the system. - -CAN binding will be separated in two parts: - -![CAN low and high level bindings mapping](images/CAN_level_mapping.png) - -- High level: Binding from which others applications will connect to. -It will provides valuable access to the CAN bus by aggregate signals or providing new signals from several originals. For example, a signal exposing whether or not a door is open, no matter which one it is. Also, we can imagine an application which supervise if there is no one in the car but moving (1m, 2m ?) to alert the owner of an unexpected behavior. The high level binding will sends a single event representing that behavior to the application which in turn will send a phone message to. - -- Low level: Decode messages that transit and send event through **Application Framework** to the subscribers with human readable message. It provides some basic access to the bus + some basic mathematical, statistical features (last_values, min, max, timestamps, averaging) as well as basic filter to get discerning signal only (This part are not implemented yet in the low level). - - -![Communication between CAN bindings and third applications](images/CAN_bindings_communication.png) - -Last but not least, the low level binding can be shipped as binary only using OpenXC inspired [AGL low level CAN binding Generator](https://gerrit.automotivelinux.org/gerrit/gitweb?p=src/low-level-can-generator.git;a=summary). diff --git a/docs/4_APIs_and_Services/4.5_Message_Signaling/2_AGL_Service_CAN_Low_Level/2_Installation.md b/docs/4_APIs_and_Services/4.5_Message_Signaling/2_AGL_Service_CAN_Low_Level/2_Installation.md deleted file mode 100644 index ad7fedb..0000000 --- a/docs/4_APIs_and_Services/4.5_Message_Signaling/2_AGL_Service_CAN_Low_Level/2_Installation.md +++ /dev/null @@ -1,196 +0,0 @@ ---- -edit_link: '' -title: Installation Guide -origin_url: >- - https://git.automotivelinux.org/apps/agl-service-can-low-level/plain/docs/2-Installation.md?h=master ---- - - - -# Prerequisites - -* An AGL system installed with latest Daring Dab version with latest Application -framework version >= 0.6. - -* Make sure you built the AGL generator else you will not be able to generate custom low-level CAN binding. - -It will produce a _application-generated.cpp_ file to paste in the source, _CAN-binder/low-can-binding/binding/_, directory. - -* Make sure you already set up the AGL SDK using the following [Download or Build Your SDK Installer](../../../getting_started/reference/getting-started/app-workflow-sdk.html). Alternatively, please refer to official guides available on [AGL Developer Site](../../../devguides). - -If you need to have the graphic stack inside your SDK, you have to prepare your environment with the **iotbzh**, or **Daring Dab** flavor using _prepare_meta_ tool. To do so, run the following command in your docker image in the step 4 in place of `... [ prepare build environment ] ...`: - -> **NOTE** These commands assume that proprietary graphic drivers for Renesas Porter board are located in _/home/devel/share/proprietary-renesas-rcar_ directory. - -```bash -prepare_meta -f iotbzh -o /xdt -l /home/devel/mirror -p /home/devel/share/proprietary-renesas-rcar/ -t m3ulcb -e wipeconfig -e rm_work -e cleartemp -/xdt/build/m3ulcb/agl-init-build-env -``` - -* (Optionnal) An [USB CAN adapter](https://shop.8devices.com/index.php?route=product/product&path=67&product_id=54) connected to connector through the [right cable](https://www.mouser.fr/ProductDetail/EasySync/OBD-M-DB9-F-ES?qs=pLQRQR43dtrcAQQLCUAIxA%3D%3D) if you want to connect to a real car through the OBD2 connector. - - - -# Getting started - -## CAN config generator usage - -### Build requirements - -* CMake version 3.3 or later -* G++, Clang++ or any C++11 compliant compiler. - -### Compile - -```bash -source /xdt/sdk/environment-setup-aarch64-agl-linux -export PATH=$PATH:/xdt/sdk/sysroots/x86_64-aglsdk-linux/usr/bin -export WD=$(pwd) -git clone --recursive https://gerrit.automotivelinux.org/gerrit/apps/agl-service-can-low-level -b Renesas_delivery_Q2 -git clone --recursive https://gerrit.automotivelinux.org/gerrit/apps/low-level-can-generator -cd ${WD}/low-level-can-generator -mkdir -p build -cd build -cmake -G "Unix Makefiles" .. -make -``` - -### Naming convention - -We chose a doted naming convention because it's a well know schema. - -It separates and organize names into hierarchy. From the left to right, you describe your names using the more common ancestor at the left then more you go to the right the more it will be accurate. - -Let's take an example, here is an example about standard PID name following this convention: - -``` -engine.load -engine.coolant.temperature -fuel.pressure -intake.manifold.pressure -engine.speed -vehicle.speed -intake.air.temperature -mass.airflow -throttle.position -running.time -EGR.error -fuel.level -barometric.pressure -commanded.throttle.position -ethanol.fuel.percentage -accelerator.pedal.position -hybrid.battery-pack.remaining.life -engine.oil.temperature -engine.torque -``` - -> **NOTE** It's recommended that you follow this naming convention to named your CAN signals. -> -> There is only character `*` that is forbidden in names because it's used as wildcard for subscription and unsubscription. -> -> This described in the below chapter. - -### Available decoder - -You can use some basic decoder provided by default by the binding which are: - -* ***decoder_t::decode_noop*** : Default decoder if not specified, return raw value from signal's bitfield. -* ***decoder_t::decode_boolean*** : Coerces a numerical value to a boolean. -* ***decoder_t::decode_state*** : Find and return the corresponding string state for a CAN signal's raw integer value. - -### Generating JSON from Vector CANoe Database - -> **CAUTION** This chapter has not been tested since it haven't necessary automotive tools for that. - -If you use CANoe to store your `gold standard` CAN signal definitions, you may be able to use the OpenXC `xml_to_json.py` script to make your JSON for you. First, export the Canoe .dbc file as XML - you can do this with Vector CANdb++. Next, create a JSON file according to the format defined above, but only define: - -* CAN messages. -* Name of CAN signals within messages and their generic_name. -* Optionnaly name of diagnostic messages and their name. - -To install the OpenXC utilities and runs `xml_to_json.py` script: - -```bash -sudo pip install openxc -cd /usr/local/lib/python2.7/dist-packages/openxc/generator -``` - -Assuming the data exported from Vector is in `signals.xml` and your minimal mapping file is `mapping.json`, run the script: - -```bash -python -m openxc.utils ./xml_to_json.py signals.xml mapping.json signals.json -``` - -The script scans `mapping.json` to identify the CAN messages and signals that you want to use from the XML file. It pulls the neccessary details of the messages (bit position, bit size, offset, etc) and outputs the resulting subset as JSON into the output file, `signals.json`. - -The resulting file together with `mapping.json` will work as input to the code generation script. - -### Generate your config file - -To generate your config file you just have to run the generator using the `-m` option to specify your JSON file. - -```bash -./can-config-generator -m ../tests/basic.json -o application-generated.cpp -``` - -If you omit the `-o` option, then code is generated on the stdout. -You also can specify a header and a footer file. -These files must be valid C++ fragment as long as they will be inserted as is. -Use the `-h` option to display help. - -> **CAUTION:** Each `diagnostic_message` must define the same `bus` as the binding will use only one bus. - -### Supported OpenXC items - -About now, compliance with OpenXC reference is in progress, can-config-generator and CAN\_signaling will implement them soon. -`initializers`, `loopers`, `commands` and `handlers` nodes are ignored for now. - -This generator will follow OpenXC support status of the low level CAN signaling binding. - -> **NOTE**: The `buses` item will not be supported by this generator because the binding use another way to declare and configure buses. Please refer to the binding's documentation. - -## Compile and install the binding - -### Build requirements - -* Kernel >= 4.8 -* CMake version 3.3 or later -* G++, Clang++ or any C++11 compliant compiler. - -### Compile - -Clone the binding repository, copy the generated file and updated the git submodules. - -Execute the following commands from this repository: - -```bash -cd ${WD}/agl-service-can-low-level -cp ${WD}/low-level-can-generator/build/application-generated.cpp ../low-can-binding/binding -``` - -### Installation - -```bash -cd ${WD}/agl-service-can-low-level -mkdir build -cd build -cmake .. -make -make widget -``` - -To install it manually, you need to copy the _low-can-service.wgt_ file on your target, then from it execute the following commands : - -On your host, to copy over the network : - -```bash -scp low-can-service.wgt root@:~ -``` - -On the target, assuming _**wgt**_ file is in the root home directory: - -```bash -afm-util install low-can-service.wgt -{ "added": "low-can-service@4.0" } -``` diff --git a/docs/4_APIs_and_Services/4.5_Message_Signaling/2_AGL_Service_CAN_Low_Level/3_Installation-J1939.md b/docs/4_APIs_and_Services/4.5_Message_Signaling/2_AGL_Service_CAN_Low_Level/3_Installation-J1939.md deleted file mode 100644 index 6ba03af..0000000 --- a/docs/4_APIs_and_Services/4.5_Message_Signaling/2_AGL_Service_CAN_Low_Level/3_Installation-J1939.md +++ /dev/null @@ -1,90 +0,0 @@ ---- -edit_link: '' -title: Installation Guide for J1939 -origin_url: >- - https://git.automotivelinux.org/apps/agl-service-can-low-level/plain/docs/3-Installation-J1939.md?h=master ---- - - - -# Installation j1939 for AGL - -#### Minimum kernel version : 4.19 - -## Compilation of kernel j1939 - -##### Clone linux-can-next repository on kernel.org - -```bash -git clone https://git.kernel.org/pub/scm/linux/kernel/git/mkl/linux-can-next.git/ -``` - -##### Checkout on j1939 branch - -```bash -git checkout j1939 -``` - -##### Add the compilation of the j1939 - -```bash -make menuconfig - - Networking Support - - Can bus subsystem support - - SAE J1939 - - [*] debug SAE J1939 -``` - -##### Compile - -```bash -make -``` - -##### Install - -```bash -make modules_install -make install -``` - -##### Update grub - -###### CentOS/RHEL/Oracle/Scientific and Fedora Linux - -```bash -grub2-mkconfig -o /boot/grub2/grub.cfg -grubby --set-default /boot/vmlinuz-... -reboot -``` - -###### Debian/Ubuntu Linux - -```bash -update-grub -reboot -``` - -##### Check if the installation is correct - -```bash -modprobe can-j1939 -``` - -If no errors are generated you have successfully install a kernel with j1939 module. - -You can have a problem with header file, to check that go in the file /usr/include/linux/can.h - -```bash -vi /usr/include/linux/can.h -``` - -If in the struct sockaddr_can you don't see j1939, the header are not upgrade. - -So you need to do this manually, go to you're linux-can-next repository and do the following command: - -```bash -cp include/uapi/linux/can.h /usr/include/linux/can.h -cp include/uapi/linux/can/j1939.h /usr/include/linux/can/ -``` - diff --git a/docs/4_APIs_and_Services/4.5_Message_Signaling/2_AGL_Service_CAN_Low_Level/4_Installation-ISOTP.md b/docs/4_APIs_and_Services/4.5_Message_Signaling/2_AGL_Service_CAN_Low_Level/4_Installation-ISOTP.md deleted file mode 100644 index 066ef27..0000000 --- a/docs/4_APIs_and_Services/4.5_Message_Signaling/2_AGL_Service_CAN_Low_Level/4_Installation-ISOTP.md +++ /dev/null @@ -1,59 +0,0 @@ ---- -edit_link: '' -title: Installation Guide for ISOTP -origin_url: >- - https://git.automotivelinux.org/apps/agl-service-can-low-level/plain/docs/4-Installation-ISOTP.md?h=master ---- - - - -# Installation isotp for AGL - -## Compilation and installation of module kernel isotp - -##### Clone repository Linux Kernel Module for ISO 15765-2:2016 CAN transport protocol - -```bash -git clone https://github.com/hartkopp/can-isotp.git -``` - -##### Move into the new repository - -```bash -cd can-isotp -``` - -##### Install packages to build - -```bash -sudo apt-get install build-essential linux-headers-$(uname -r) -``` - -##### Compile - -```bash -make -``` - -##### Install - -```bash -sudo make modules_install -``` - -##### Load module - - -```bash -modprobe can -modprobe vcan -sudo insmod ./net/can/can-isotp.ko -``` - - -## Include headers files - - -```bash -sudo cp include/uapi/linux/can/isotp.h /usr/include/linux/can/ -``` \ No newline at end of file diff --git a/docs/4_APIs_and_Services/4.5_Message_Signaling/2_AGL_Service_CAN_Low_Level/5_Usage.md b/docs/4_APIs_and_Services/4.5_Message_Signaling/2_AGL_Service_CAN_Low_Level/5_Usage.md deleted file mode 100644 index 77aad7f..0000000 --- a/docs/4_APIs_and_Services/4.5_Message_Signaling/2_AGL_Service_CAN_Low_Level/5_Usage.md +++ /dev/null @@ -1,433 +0,0 @@ ---- -edit_link: '' -title: Usage Guide -origin_url: >- - https://git.automotivelinux.org/apps/agl-service-can-low-level/plain/docs/5-Usage.md?h=master ---- - - - -# Configure the AGL system - -## Virtual CAN device - -Connected to the target, here is how to load the virtual CAN device driver and -set up a new vcan device : - -```bash -modprobe vcan -ip link add vcan0 type vcan -ip link set vcan0 up -``` - -You also can named your linux CAN device like you want and if you need name it -`can0` : - -```bash -modprobe vcan -ip link add can0 type vcan -ip link set can0 up -``` - -## CAN device using the USB CAN adapter - -Using real connection to CAN bus of your car using the USB CAN adapter -connected to the OBD2 connector. - -Once connected, launch `dmesg` command and search which device to use: - -```bash -dmesg -[...] -[ 131.871441] usb 1-3: new full-speed USB device number 4 using ohci-pci -[ 161.860504] can: controller area network core (rev 20120528 abi 9) -[ 161.860522] NET: Registered protocol family 29 -[ 177.561620] usb 1-3: USB disconnect, device number 4 -[ 191.061423] usb 1-2: USB disconnect, device number 3 -[ 196.095325] usb 1-2: new full-speed USB device number 5 using ohci-pci -[ 327.568882] usb 1-2: USB disconnect, device number 5 -[ 428.594177] CAN device driver interface -[ 1872.551543] usb 1-2: new full-speed USB device number 6 using ohci-pci -[ 1872.809302] usb_8dev 1-2:1.0 can0: firmware: 1.7, hardware: 1.0 -[ 1872.809356] usbcore: registered new interface driver usb_8dev -``` - -Here device is named `can0`. - -This instruction assuming a speed of 500000kbps for your CAN bus, you can try -others supported bitrate like 125000, 250000 if 500000 doesn't work: - -```bash -ip link set can0 type can bitrate 500000 -ip link set can0 up -ip link show can0 - can0: mtu 16 qdisc pfifo_fast state UNKNOWN qlen 10 - link/can - can state ERROR-ACTIVE (berr-counter tx 0 rx 0) restart-ms 0 - bitrate 500000 sample-point 0.875 - tq 125 prop-seg 6 phase-seg1 7 phase-seg2 2 sjw 1 - sja1000: tseg1 1..16 tseg2 1..8 sjw 1..4 brp 1..64 brp-inc 1 - clock 16000000 -``` - -On a Rcar Gen3 board, you'll have your CAN device as `can1` because `can0` -already exists as an embedded device. - -The instructions will be the same: - -```bash -ip link set can1 type can bitrate 500000 -ip link set can1 up -ip link show can1 - can0: mtu 16 qdisc pfifo_fast state UNKNOWN qlen 10 - link/can - can state ERROR-ACTIVE (berr-counter tx 0 rx 0) restart-ms 0 - bitrate 500000 sample-point 0.875 - tq 125 prop-seg 6 phase-seg1 7 phase-seg2 2 sjw 1 - sja1000: tseg1 1..16 tseg2 1..8 sjw 1..4 brp 1..64 brp-inc 1 - clock 16000000 -``` - -## Rename an existing CAN device - -You can rename an existing CAN device using following command and doing so move -an existing `can0` device to anything else and then use another device as `can0` -. For a Rcar Gen3 board do the following by example: - -```bash -sudo ip link set can0 down -sudo ip link set can0 name bsp-can0 -sudo ip link set bsp-can0 up -``` - -Then connect your USB CAN device that will be named `can0` by default. - -# Configure the binding - -The binding reads system configuration file _/etc/dev-mapping.conf_ at start to -map logical name from signals described in JSON file to linux devices name -initialized by the system. - -Edit file _/etc/dev-mapping.conf_ and add mapping in section `CANbus-mapping`. - -Default binding configuration use a CAN bus named `hs` so you need to map it to -the real one, here are some examples: - -* Using virtual CAN device as described in the previous chapter: - -```ini -[CANbus-mapping] -hs="vcan0" -ls="vcan1" -``` - -* Using real CAN device, this example assume CAN bus traffic will be on can0. - -```ini -[CANbus-mapping] -hs="can0" -ls="can1" -``` - -* On a Rcar Gen3 board there is an embedded CAN device so `can0` already exists. So you might want to use your USB CAN adapter plugged to the OBD2 connector, in this case use `can1`: - -```ini -[CANbus-mapping] -hs="can1" -``` - -* You can use this configuration for j1939: - -```ini -[CANbus-mapping] -hs="can0" -ls="can1" -j1939="can2" -``` - -> **CAUTION VERY IMPORTANT:** Make sure the CAN bus\(es\) you specify in your -> configuration file match those specified in your generated source file with -> the `CAN-config-generator`. - - - -## Change name of ECU for J1939 - -To change the name of an ECU to J1939, you must go to the file conf.d/cmake/config.cmake and modify the value at : - - -```cmake -# Define name for ECU -set(J1939_NAME_ECU 0x1239) -``` - - - -# Run it, test it, use it. - -You can run the binding using **afm-util** tool, here is the classic way to go : - -```bash -afm-util run low-can-service@4.0 -1 -``` - -You can find instructions to use afm-util tool -[here](../../reference/af-main/1-afm-daemons.html#using-afm-util), - as well as documentation about Application Framework. - -But you can't control nor interact with it because you don't know security -token that **Application Framework** gaves it at launch. - -So, to test it, it is better to launch the binding manually. In the following -example, it will use port **1234** and left empty security token for testing -purpose: - -```bash -afb-daemon --binding=/var/lib/afm/applications/low-can-service/4.0/lib/afb-low-can.so --rootdir=/var/lib/afm/applications/low-can-service/4.0/ --port=1234 --token=1 -NOTICE: binding [/usr/lib/afb/afb-dbus-binding.so] calling registering function afbBindingV1Register -NOTICE: binding /usr/lib/afb/afb-dbus-binding.so loaded with API prefix dbus -NOTICE: binding [/usr/lib/afb/authLogin.so] calling registering function afbBindingV1Register -NOTICE: binding /usr/lib/afb/authLogin.so loaded with API prefix auth -NOTICE: binding [/var/lib/afm/applications/low-can-service/4.0/libs//low-can-binding.so] calling registering function afbBindingV1Register -NOTICE: binding /var/lib/afm/applications/low-can-service/4.0/libs//low-can-binding.so loaded with API prefix low-can -NOTICE: Waiting port=1234 rootdir=/var/lib/afm/applications/low-can-service/4.0/ -NOTICE: Browser URL= http:/*localhost:1234 -``` - -On another terminal, connect to the binding using previously installed -**AFB Websocket CLI** tool: - -```bash -afb-client-demo ws://localhost:1234/api?token=1 -``` - -You will be on an interactive session where you can communicate directly with -the binding API. - -The binding provides at this moment 2 verbs, _subscribe_ and _unsubscribe_, -which can take argument by a JSON **event** object. - -The argument value is the CAN message **generic\_name** as described in the -JSON file used to generate cpp file for the binding. - -To use the _**AFB Websocket CLI**_ tool, a command line will be like the -following: - -``` - -``` - -Where: - -* API : _**low-can**_. -* Verb : _**subscribe**_ or _**unsubscribe**_ -* Arguments : _**{ "event": "driver.doors.open" }**_ - -## Subscription and unsubscription - -You can ask to subscribe to chosen CAN event with a call to _subscribe_ API -verb with the CAN messages name as JSON argument. - -> **NOTE:** If no argument is provided, then you'll subscribe to all signals -> at once. - -For example from a websocket session: - -```json -low-can subscribe { "event": "doors.driver.open" } -ON-REPLY 1:low-can/subscribe: {"jtype":"afb-reply","request":{"status":"success","uuid":"a18fd375-b6fa-4c0e-a1d4-9d3955975ae8"}} -``` - -Subscription and unsubscription can take wildcard in their _event_ value and are -**case-insensitive**. - -To receive all doors events : - -```json -low-can subscribe { "event" : "doors*" } -ON-REPLY 1:low-can/subscribe: {"jtype":"afb-reply","request":{"status":"success","uuid":"511c872e-d7f3-4f3b-89c2-aa9a3e9fbbdb"}} -``` - -Then you will receive an event each time a CAN message is decoded for the event -named _doors.driver.open_ with its received timestamp if available: - -```json -ON-EVENT low-can/messages.doors.driver.open({"event":"low-can\/messages.doors.driver.open","data":{"name":"messages.doors.driver.open","value":true, "timestamp": 1505812906020023},"jtype":"afb-event"}) -``` - -Notice that event shows you that the CAN event is named -_messages.doors.driver.open_ but you ask for event about -_doors.driver.open_. - -This is because all CAN messages or diagnostic messages are prefixed by the -JSON parent node name, **messages** for CAN messages and -**diagnostic\_messages** for diagnostic messages like OBD2. - -This will let you subscribe or unsubcribe to all signals at once, not -recommended, and better make filter on subscribe operation based upon their type. Examples: - -```json -low-can subscribe { "event" : "*speed*" } --> will subscribe to all messages with speed in their name. Search will be make without prefix for it. -low-can subscribe { "event" : "speed*" } --> will subscribe to all messages begin by speed in their name. Search will be make without prefix for it. -low-can subscribe { "event" : "messages*speed*" } --> will subscribe to all CAN messages with speed in their name. Search will be on prefixed messages here. -low-can subscribe { "event" : "messages*speed" } --> will subscribe to all CAN messages ending with speed in their name. Search will be on prefixed messages here. -low-can subscribe { "event" : "diagnostic*speed*" } --> will subscribe to all diagnostic messages with speed in their name. Search will be on prefixed messages here. -low-can subscribe { "event" : "diagnostic*speed" } --> will subscribe to all diagnostic messages ending with speed in their name. Search will be on prefixed messages here. -``` - -You can also subscribe to an event with the ID or the PGN of the message definition : - - -```json -low-can subscribe {"id" : 1568} -low-can subscribe {"pgn" : 61442} -``` - -And subscribe to all ID or PGN : - -```json -low-can subscribe {"id" : "*"} -low-can subscribe {"pgn" : "*"} -``` - - -You can stop receiving event from it by unsubscribe the signal the same way you did for subscribe - -```json -low-can unsubscribe { "event": "doors.driver.open" } -ON-REPLY 2:low-can/unsubscribe: {"jtype":"afb-reply","request":{"status":"success"}} -low-can unsubscribe { "event" : "doors*" } -ON-REPLY 3:low-can/unsubscribe: {"jtype":"afb-reply","request":{"status":"success"}} -``` - -### Filtering capabilities - -It is possible to limits received event notifications into minimum and maximum -boundaries as well as doing frequency thinning. This is possible using the -argument filter with one or more of the filters available : - -* frequency: specify in Hertz the frequency which will be used to getting - notified of new CAN events for the designated signal. If, during the blocked - time, further changed CAN messages are received, the last valid one will be - transferred after the lockout with a RX_CHANGED. -* min: Minimum value that the decoded value needs to be above to get pushed to - the subscribed client(s). -* max: Maximum value that the decoded value needs to be below to get pushed to - the subscribed client(s) -* rx_id : For the ISO TP protocol, define the id of source to write a message -* tx_id : For the ISO TP protocol, define the id of emitter to receive message - -Order doesn't matter neither the number of filters chosen, you can use one, two -or all of them at once. - -Usage examples : - -```json -low-can subscribe {"event": "messages.engine.speed", "filter": { "frequency": 3, "min": 1250, "max": 3500}} -low-can subscribe {"event": "messages.engine.load", "filter": { "min": 30, "max": 100}} -low-can subscribe {"event": "messages.vehicle.speed", "filter": { "frequency": 2}} -# ISOTP -low-can subscribe {"id": 273, "filter": {"tx_id" : 562}} -``` - -## Get last signal value and list of configured signals - -You can also ask for a particular signal value on one shot using **get** verb, like -this: - -```json -low-can get {"event": "messages.engine.speed"} -ON-REPLY 1:low-can/get: {"response":[{"event":"messages.engine.speed","value":0}],"jtype":"afb-reply","request":{"status":"success"}} -``` - -> **CAUTION** Only one event could be requested. - -Also, if you want to know the supported CAN signals loaded by **low-can**, use -verb **list** - -```json -low-can list -ON-REPLY 2:low-can/list: {"response":["messages.hvac.fan.speed","messages.hvac.temperature.left","messages.hvac.temperature.right","messages.hvac.temperature.average","messages.engine.speed","messages.fuel.level.low","messages.fuel.level","messages.vehicle.average.speed","messages.engine.oil.temp","messages.engine.oil.temp.high","messages.doors.boot.open","messages.doors.front_left.open","messages.doors.front_right.open","messages.doors.rear_left.open","messages.doors.rear_right.open","messages.windows.front_left.open","messages.windows.front_right.open","messages.windows.rear_left.open","messages.windows.rear_right.open","diagnostic_messages.engine.load","diagnostic_messages.engine.coolant.temperature","diagnostic_messages.fuel.pressure","diagnostic_messages.intake.manifold.pressure","diagnostic_messages.engine.speed","diagnostic_messages.vehicle.speed","diagnostic_messages.intake.air.temperature","diagnostic_messages.mass.airflow","diagnostic_messages.throttle.position","diagnostic_messages.running.time","diagnostic_messages.EGR.error","diagnostic_messages.fuel.level","diagnostic_messages.barometric.pressure","diagnostic_messages.ambient.air.temperature","diagnostic_messages.commanded.throttle.position","diagnostic_messages.ethanol.fuel.percentage","diagnostic_messages.accelerator.pedal.position","diagnostic_messages.hybrid.battery-pack.remaining.life","diagnostic_messages.engine.oil.temperature","diagnostic_messages.engine.fuel.rate","diagnostic_messages.engine.torque"],"jtype":"afb-reply","request":{"status":"success","uuid":"32df712a-c7fa-4d58-b70b-06a87f03566b"}} -``` - -## Write on CAN buses - -Two modes could be used for that which is either specifying the CAN bus and a -*RAW* CAN message either by specifying a defined signal, **case-insensitively**, -and its value. - -Examples: - -```json -# Authentification -low-can auth -# Write a raw can frame to the CAN id 0x620 -low-can write { "bus_name": "hs", "frame": { "can_id": 1568, "can_dlc": 8, "can_data": [ 255, 255, 255, 255, 255, 255, 255, 255]} } -# Write a signal's value. -low-can write { "signal_name": "engine.speed", "signal_value": 1256} -# Write J1939 'single frame' -low-can write { "bus_name": "j1939", "frame": { "pgn": 61442, "length":8, "data": [ 255, 255, 255, 255, 255, 255, 255, 255]} } -# Write J1939 'multi frame' -low-can write { "bus_name": "j1939", "frame": { "pgn": 61442, "length":9, "data": [ 255, 255, 255, 255, 255, 255, 255, 255, 254]} } -# Write ISOTP 'single frame' -low-can write {"bus_name": "hs", "filter": {"rx_id" : 562}, "frame": { "can_id": 273, "can_dlc": 8, "can_data": [ 255, 255, 255, 255, 255, 255, 255, 255]} } -# Write ISOTP 'multi frame' -low-can write {"bus_name": "hs", "filter": {"rx_id" : 562}, "frame": { "can_id": 273, "can_dlc": 9, "can_data": [ 255, 255, 255, 255, 255, 255, 255, 255, 25]} } -``` - -To be able to use write capability, you need to add the permission - ```urn:AGL:permission::platform:can:write``` to your package configuration - file that need to write on CAN bus through **low-can** api. - -Then in order to write on bus, your app needs to call verb **auth** -before calling **write**, to raise its **LOA**, Level Of Assurance, -which controls usage of verb **write**. - -## Using CAN utils to monitor CAN activity - -You can watch CAN traffic and send custom CAN messages using can-utils -preinstalled on AGL target. - -To watch watch going on a CAN bus use: - -```bash -candump can0 -``` - -Or for an USB CAN adapter connected to porter board: - -```bash -candump can1 -``` - -Send a custom message: - -```bash -cansend can0 ID#DDDDAAAATTTTAAAA -``` - -You can also replay a previously dumped CAN logfiles. These logfiles can be -found in _can_samples_ directory under Git repository. Following examples use -a real trip from an Auris Toyota car. - -Trace has been recorded from a CAN device `can0` so you have to map it to the -correct one you use for your tests. - -Replay on a virtual CAN device `vcan0`: - -```bash -canplayer -I trip_test_with_obd2_vehicle_speed_requests vcan0=can0 -``` - -Replay on a CAN device `can0`: - -```bash -canplayer -I trip_test_with_obd2_vehicle_speed_requests can0 -``` - -Replay on a CAN device `can1` (porter by example): - -```bash -canplayer -I trip_test_with_obd2_vehicle_speed_requests can1=can0 -``` diff --git a/docs/4_APIs_and_Services/4.5_Message_Signaling/2_AGL_Service_CAN_Low_Level/images/CAN_bindings_communication.png b/docs/4_APIs_and_Services/4.5_Message_Signaling/2_AGL_Service_CAN_Low_Level/images/CAN_bindings_communication.png deleted file mode 100644 index 426e2f7..0000000 Binary files a/docs/4_APIs_and_Services/4.5_Message_Signaling/2_AGL_Service_CAN_Low_Level/images/CAN_bindings_communication.png and /dev/null differ diff --git a/docs/4_APIs_and_Services/4.5_Message_Signaling/2_AGL_Service_CAN_Low_Level/images/CAN_level_mapping.png b/docs/4_APIs_and_Services/4.5_Message_Signaling/2_AGL_Service_CAN_Low_Level/images/CAN_level_mapping.png deleted file mode 100644 index 1f1d906..0000000 Binary files a/docs/4_APIs_and_Services/4.5_Message_Signaling/2_AGL_Service_CAN_Low_Level/images/CAN_level_mapping.png and /dev/null differ diff --git a/docs/4_APIs_and_Services/4.5_Message_Signaling/2_AGL_Service_CAN_Low_Level/images/OpenXC_to_AGL.png b/docs/4_APIs_and_Services/4.5_Message_Signaling/2_AGL_Service_CAN_Low_Level/images/OpenXC_to_AGL.png deleted file mode 100644 index 6e40336..0000000 Binary files a/docs/4_APIs_and_Services/4.5_Message_Signaling/2_AGL_Service_CAN_Low_Level/images/OpenXC_to_AGL.png and /dev/null differ diff --git a/docs/4_APIs_and_Services/4.5_Message_Signaling/3_High_Level_VIWI_Service/1_Architecture_presentation.md b/docs/4_APIs_and_Services/4.5_Message_Signaling/3_High_Level_VIWI_Service/1_Architecture_presentation.md deleted file mode 100644 index a675c98..0000000 --- a/docs/4_APIs_and_Services/4.5_Message_Signaling/3_High_Level_VIWI_Service/1_Architecture_presentation.md +++ /dev/null @@ -1,32 +0,0 @@ ---- -edit_link: '' -title: Architecture presentation -origin_url: >- - https://git.automotivelinux.org/apps/agl-service-can-high-level-viwi/plain/docs/1-Architecture.md?h=master ---- - - - -# AGL VIWI HIGH-VIWI binding architecture - -This binding is intended to act between low-level binding(s) and clients. It builds ViWi resources as defined in a json configuration file. It implements subscribe/unsubscribe/get verbs for the clients accordingly with protocol specification. - -Each ViWi resource can be composed of several elements, for which subscriptions will be made to the low-level binding with configurable frequencies or filters. - -![ViWi High Level binding architecture](./images/high-level-arch.png) - - - -## Brief VIWI description - -ViWi (Volkswagen Infotainment Web Interface) protocol defines a serie of objects, which can be queried or updated via JSon messages. - -Each object is assigned with a unique URI. - -The depth of the URI tree is limited to 3, i.e. _/service/resource>/element/_, for instance **/car/doors/3901a278-ba17-44d6-9aef-f7ca67c04840**. - -To retrieve the list of elements for a given resource, one can use the get command, for instance **get /car/doors/**. - -It is also possible to subscribe to elements or group of elements, for instance **subscribe /car/doors/3901a278-ba17-44d6-9aef-f7ca67c04840**. Requests can also have various filters, or specify a frequency. - -More details in the [ViWi general documentation](https://www.w3.org/Submission/viwi-protocol/) and in the [ViWi.service.car documentation](https://www.w3.org/Submission/viwi-service-car/) diff --git a/docs/4_APIs_and_Services/4.5_Message_Signaling/3_High_Level_VIWI_Service/2_Install_Usage.md b/docs/4_APIs_and_Services/4.5_Message_Signaling/3_High_Level_VIWI_Service/2_Install_Usage.md deleted file mode 100644 index cde838f..0000000 --- a/docs/4_APIs_and_Services/4.5_Message_Signaling/3_High_Level_VIWI_Service/2_Install_Usage.md +++ /dev/null @@ -1,208 +0,0 @@ ---- -edit_link: '' -title: Installation and Usage Guide -origin_url: >- - https://git.automotivelinux.org/apps/agl-service-can-high-level-viwi/plain/docs/2-Install-Usage.md?h=master ---- - - - -## Installation - -## Prerequisites - -Low level CAN service (>=4.0) must be installed. Prerequisites are the same. - -```bash -$ git clone --recursive https://gerrit.automotivelinux.org/gerrit/apps/low-level-can-service -``` - -## Clone and build high level binding - -### Build requirements - -* CMake version 3.0 or later -* G++, Clang++ or any C++11 compliant compiler. - -### Clone - -```bash -$ export WD=$(pwd) -$ git clone --recusive https://github.com/iotbzh/high-level-viwi-service.git -``` - -### Build - -```bash -$ cd $WD/high-level-viwi-service -$ mkdir build -$ cd build -$ cmake .. -$ make -``` - - - -# Usage - -## JSON configuration file - -This file must be named *high.json*, and must accessible from afb-daemon. - -> **NOTE** A sample is available at the root of the git repository. - -The json configuration file consists in 2 sections: - -### Definitions section - -This section describes each resources defined in the high-level binding. Each resource is composed with different properties having a name, a type and a description. -Type can be boolean, double, string, or int. Properties "id", "uri" and "name" are compulsory. - -For instance: - -```json -{ - "name": "/car/demoboard/", - "properties": { - "id": { - "type": "string", - "description": "identifier" - }, - "uri": { - "type": "string", - "description": "object uri" - }, - "name": { - "type": "string", - "description": "name" - }, - "unit": { - "type": "string", - "description": "units" - }, - "speed": { - "type": "double", - "description": "vehicle centerpoint speed as shown by the instrument cluster" - }, - "rpm": { - "type": "double", - "description": "engine rotations per minute" - }, - "level": { - "type": "double", - "description": "level of tankage" - }, - "load": { - "type": "double", - "description": "engine load" - } - } -} -``` - - - -### Resources section - -This section defines which values should be assigned to resource's properties as defined in the definitions section. -The link to the definitions section is made through the name of the resource. - -Some values are static, some are linked to low-level requests. - -In case a value is linked to a low-level request, the value will start with "${" and end with "}". In that case the value will consist in the name of the low-level signal, followed -with the frequency of the signal in ms. -1 in the frequency means that high level binding should subscribe to low level binding for all changes, without specifying a frequency. - -For instance: -```json -{ - "name": "/car/demoboard/", - "values": [{ - "name": "vehicleSpeed", - "unit": "km/h", - "speed": "${diagnostic_messages.vehicle.speed,1000}" - }, { - "name": "engineSpeed", - "unit": "rpm", - "rpm": "${diagnostic_messages.engine.speed,1000}" - }, { - "name": "fuelLevel", - "unit": "litre", - "level": "${diagnostic_messages.fuel.level,1000}" - }, { - "name": "engineLoad", - "unit": "Nm", - "load": "${diagnostic_messages.engine.load,1000}" - }] -} -``` - - - -## Running and testing - -### Launch the binder together with the two bindings - -The Json high level configuration file *high.json* must be placed in the directory where you launch afb-daemon. - -```bash -$ cp $WD/high-level-viwi-service/high.json $WD - cd $WD -``` - -Then you can natively under linux you can launch afb-daemon with the low-level and high-level bindings with a command like: - -```bash -$ cd $WD -$ afb-daemon --rootdir=$WD/low-level-can-service/CAN-binder/build/package --binding=$WD/low-level-can-service/CAN-binder/build/package/lib/afb-low-can.so --binding=$WD/high-level-viwi-service/build/package/lib/afb-high-viwi.so --port=1234 --tracereq=common --token=1 --verbose -``` - -### Use afb-client-demo to test high level binding - -On another terminal, connect to the binding using previously installed _**AFB Websocket CLI**_ tool: - -```bash -$ afb-client-demo ws://localhost:1234/api?token=1 -``` - -You will be on an interactive session where you can communicate directly with the binding API. - -The binding provides at this moment 3 verbs, _get_, _subscribe_ and _unsubscribe_, which can take a JSON object as an argument. - - -To use the _**AFB Websocket CLI**_ tool, a command line will be like the following : - -``` - -``` - -Where: - -* API : _**high-viwi**_. -* Verb : _**get**_, _**subscribe**_ or _**unsubscribe**_ -* Arguments : _**{ "name": "/car/doors/" }**_ - -You can therefore use commands such as: - -``` -high-viwi subscribe {"name":"/car/doors/","interval":10000} -high-viwi unsubscribe {"name":"/car/doors/","interval":10000} -high-viwi get {"name":"/car/demoboard/"} -high-viwi get {"name":"/car/demoboard/","fields":["fuelLevel","engineLoad"]} -``` - -For instance the output of the third command should be: - -``` -high-viwi get {"name":"/car/demoboard/"} -ON-REPLY 1:high-viwi/get: {"response":{"\/car\/demoboard\/2159e2-5b638a-39e242-7a2f5":{"id":"2159e2-5b638a-39e242-7a2f5","name":"vehicleSpeed","speed":0.000000,"unit":"km\/h","uri":"\/car\/demoboard\/2159e2-5b638a-39e242-7a2f5"},"\/car\/demoboard\/22ad2c-5a3c2b-50fabb-324c82":{"id":"22ad2c-5a3c2b-50fabb-324c82","level":0.000000,"name":"fuelLevel","unit":"litre","uri":"\/car\/demoboard\/22ad2c-5a3c2b-50fabb-324c82"},"\/car\/demoboard\/3a3ab9-2bd52c-11d30-689acf":{"id":"3a3ab9-2bd52c-11d30-689acf","name":"engineSpeed","rpm":0.000000,"unit":"rpm","uri":"\/car\/demoboard\/3a3ab9-2bd52c-11d30-689acf"},"\/car\/demoboard\/5ae808-8093cb-99716-30a605":{"id":"5ae808-8093cb-99716-30a605","load":0.000000,"name":"engineLoad","unit":"Nm","uri":"\/car\/demoboard\/5ae808-8093cb-99716-30a605"}},"jtype":"afb-reply","request":{"status":"success","uuid":"44ce03f9-a7ca-49e1-a62a-40c74db0caa0"}} -``` - -As you can see for the moment all values are 0, because we didn't inject any CAN data in the binder. To do this, you can use **canplayer** to feed the bindings with some data. -You can find an example of data in high level binding, "samples" directory. - -For instance, on a third terminal: - -```bash -$ canplayer -I candata -``` - diff --git a/docs/4_APIs_and_Services/4.5_Message_Signaling/3_High_Level_VIWI_Service/images/high-level-arch.png b/docs/4_APIs_and_Services/4.5_Message_Signaling/3_High_Level_VIWI_Service/images/high-level-arch.png deleted file mode 100644 index b4a1e8c..0000000 Binary files a/docs/4_APIs_and_Services/4.5_Message_Signaling/3_High_Level_VIWI_Service/images/high-level-arch.png and /dev/null differ diff --git a/docs/4_APIs_and_Services/4.5_Message_Signaling/4_AGL_Service_Signal_Composer/1_Architecture.md b/docs/4_APIs_and_Services/4.5_Message_Signaling/4_AGL_Service_Signal_Composer/1_Architecture.md deleted file mode 100644 index 62c2f0f..0000000 --- a/docs/4_APIs_and_Services/4.5_Message_Signaling/4_AGL_Service_Signal_Composer/1_Architecture.md +++ /dev/null @@ -1,73 +0,0 @@ ---- -edit_link: '' -title: Architecture presentation -origin_url: >- - https://git.automotivelinux.org/apps/agl-service-signal-composer/plain/docs/part-1/1-Architecture.md?h=master ---- - - - -# Signal Composer - -## Architecture - -Here is a quick picture about the signaling architecture : - -![GlobalArchitecture] - -Key here are on both layers, **low** and **high**. - -- **Low levels** binding used as _AGL service_, handle data exchange protocol to - decode/encode and retransmit with an AGL compatible format using **Application - Framework** events. These are divided into two parts, which are : - - A transport Layer binding's plug-in that is able to read/write from a device. - - Decoding/Encoding parts that expose signals. -- **High level signal composer** binding gathers multiple **low level** signaling - sources. Then from these sources, it exposes theirs **raw** signals or more interesting - can creates new virtuals signals from them. Example: - A signal made from gps latitude and longitude that computes the heading of - vehicle. This is modular and each signal source should be handled by specific - plugins which take care of get the underlying event from **low level** or - define signaling composition with simple or complex operation to output value - from **raw** signals. - -A transport plug-in is a shared library that shares a common API to be -compatible with **low level** services that is: - -- **open/close**: method to open a handle which could be a socket, file or - device by example. -- **read/write**: method to read and write a stream of data. - -Configuration is made by sending a special packet using a write method to the -handle. In brief, this could be compared to the layer 1 and 2 of [OSI model]. - -There are three main parts with **Signal Composer**: - -- Configuration files which could be splitted in differents files. That will - define: - - metadata with name of **signal composer** api name - - additionnals configurations files - - plugins used if so, **low level** signals sources - - signals definitions -- Dedicated plugins -- Signal composer API - -## Terminology - -Here is a little terminology guide to set the vocabulary: - -- **api**: a binding API name -- **action**: a function called at a certain time -- **callbacks**: a function called at a certain time -- **event**: the raw event that materialize the signal -- **plugins**: a C/C++ code with functions that be called by signal composer - service -- **sources**: an external binding API that generate signals for the signal - composer service -- **signals**: an event generated by the **Application Framework** -- **virtual signals**: a signal composed of **raw signals** with value - calculated by a **callbacks** -- **raw signals**: an event generated by a **low level** binding - -[OSI model]: https://en.wikipedia.org/wiki/OSI_model -[GlobalArchitecture]: pictures/Global_Signaling_Architecture.png "Global architecture" diff --git a/docs/4_APIs_and_Services/4.5_Message_Signaling/4_AGL_Service_Signal_Composer/2_Configuration.md b/docs/4_APIs_and_Services/4.5_Message_Signaling/4_AGL_Service_Signal_Composer/2_Configuration.md deleted file mode 100644 index 6bd3a8a..0000000 --- a/docs/4_APIs_and_Services/4.5_Message_Signaling/4_AGL_Service_Signal_Composer/2_Configuration.md +++ /dev/null @@ -1,109 +0,0 @@ ---- -edit_link: '' -title: Configuration -origin_url: >- - https://git.automotivelinux.org/apps/agl-service-signal-composer/plain/docs/part-1/2-Configuration.md?h=master ---- - - - -# Configuration - -Configuration defines all in **Signal composer** each signals and sources has -to be defined in it. At start, configuration will be searched in default -binding configuration directory which should be _/var/local/lib/afm/applications/signal-composer/VER/etc/_, -VER is the version of **signal composer**. -Binding search for a file name as _init-daemon*.json_. Others files could be -used to split sections and don't have 1 big fat definitions file. - -Saying that you have 4 sections to define: - -- **metadata**: Main parts and the only one that can't be in a separates - configuration. This must appears in the main configuration file. -- **plugins** (optional): Declare plugins that will be used by *sources* and - *signals* for the subscription and composition. -- **sources**: Declare **low level** signals sources (eg. low-can, gps, mraa, - ...). -- **signals**: Declare signals, virtuals and raw. - -## Metadata - -Here we define some metadata about **signal composer** binding. Fields to configure -are : - -- **uid**: self-explanatory -- **version** (optional): self-explanatory -- **api** (optional): name that the binding will be initialized to and later - be accessible by **Application Framework** -- **info** (optional): self-explanatory -- **require** (optional): list of required external apis. - -## Plugins - -This section is the only which is optional, it is needed if you develop -specifics C/C++ plugins to be used with signal-composer. LUA and API -consumption does not need plugins. - -Default path to search for a plugin is in the binding library directory -in a subdirectory _plugins_ _/var/local/lib/afm/applications/signal-composer/VER/lib/plugins_. -Else you could use the environment variable _CONTROL_PLUGIN_PATH_ with a -semicolon separated list of directory. - -Fields are: - -- **uid**: Define the plugin name. This is that label that will be used on - **sources** and **signals** callbacks. -- **ldpath** (optional): path to the plugin directory -- **info** (optional): self-explanatory -- **basename**: shared library file name **without** the extension. -- **files** (optional): list of additionnals files. **ONLY NAME** or part of - it, without extension. Don't mix up section object with this key, either one - or the other but avoid using both - -## Sources - -A source is a **low level** API that will be consume by the **signal composer** -to be able to expose those signals with additionnals treatments, filtering, -thinning,... and create new virtuals signals composed with basic raw signals. - -A source is defined with following fields: - -- **uid**: An unique identifier name for thatuid source API. -- **api**: Name of the source API. -- **info** (optional): self-explanatory -- **init** (optional): an **action** to take to initialize a source. May you - have to call a verb from that API, of create a files etc. -- **getSignals** (optional); an **action** to take to get signals from that - source. These callback will be used for each signals defined later in the - **signals** section. Dedicated arguments for each signal could be defined in - **signals**. -- **files** (optional): list of additionnals files. **ONLY NAME** or part of - it, without extension. Don't mix up section object with this key, either one - or the other but avoid using both - -## Signals - -A signal definition could be either a **raw** one or a **virtual** one. A - **virtual signal** is a set of existing **raw signals** associated to an - **action** on reception which will compute the value of the signal. - -- **uid**: Unique identifier used inside **signal composer**, used to compose - virtual signals. -- **event**: specify a **raw signal** coming from **low level** sources. - Couldn't be used with **depends** field, only one of them is possible. -- **depends**: specify others signals **id** that compose it (eg: heading is - composed with longitude+latitude signals.). Couldn't be used with **event** - field at same time. -- **retention** (optional): retention duration in seconds -- **unit** (optional): Unit used to exprime the signal -- **frequency** (optional): Frequency maximum at which the signal could be - requested or sent. This is a thinning made at **high level** so not best - suited for performance. Used **low level** native filtering capabilities when - possible. -- **getSignalsArgs**: a JSON object used at subscription time. Meant to enabled - filtering capabilities at subscription and to be able to customize in general - a subcription request by signal if needed. -- **onReceived**: an **action** to take when this signal is received! -- **files** (optional): list of additionnals files. **ONLY NAME** or part of - it, without extension. Don't mix up section object with this key, either one - or the other but avoid using both diff --git a/docs/4_APIs_and_Services/4.5_Message_Signaling/4_AGL_Service_Signal_Composer/3_Plugins.md b/docs/4_APIs_and_Services/4.5_Message_Signaling/4_AGL_Service_Signal_Composer/3_Plugins.md deleted file mode 100644 index aa0ebb4..0000000 --- a/docs/4_APIs_and_Services/4.5_Message_Signaling/4_AGL_Service_Signal_Composer/3_Plugins.md +++ /dev/null @@ -1,32 +0,0 @@ ---- -edit_link: '' -title: Plugins -origin_url: >- - https://git.automotivelinux.org/apps/agl-service-signal-composer/plain/docs/part-1/3-Plugins.md?h=master ---- - - - -# Plugins - -Plugins are C/C++ shared libraries loaded by the binding to execute some -simple routine. Routine could be on reception of a new signal or at sources -initialization time or signal subscription with the respective JSON field -`onReceived` `init` and `getSignals` - -A default plugin (builtin) is provided with 2 functions: - -- **defaultOnReceived**: set and record a new signal value and its timestamp - in the signal composer service. It simply tooks the incoming event JSON object - and search for *key* `value` and `timestamp` then call function - `setSignalValue`. -- **setSignalValueWrap**: a `lua2c` function the could be called from any LUA - script to record a new signal value. - -> **CAUTION**: `timestamp` value has to be typed as *uint64_t* with -> a **nanosecond** precision using a realtime clock. To correctly store it in -> a JSON-C object use the int64 type with the according fonctions: -> *json_object_new_int64()* -> *json_object_get_int64()* -> *json_object_set_int64()* -> *...* diff --git a/docs/4_APIs_and_Services/4.5_Message_Signaling/4_AGL_Service_Signal_Composer/4_SignalComposerAPI.md b/docs/4_APIs_and_Services/4.5_Message_Signaling/4_AGL_Service_Signal_Composer/4_SignalComposerAPI.md deleted file mode 100644 index cc1688c..0000000 --- a/docs/4_APIs_and_Services/4.5_Message_Signaling/4_AGL_Service_Signal_Composer/4_SignalComposerAPI.md +++ /dev/null @@ -1,71 +0,0 @@ ---- -edit_link: '' -title: Signal Composer API -origin_url: >- - https://git.automotivelinux.org/apps/agl-service-signal-composer/plain/docs/part-1/4-SignalComposerAPI.md?h=master ---- - - - -# Signal Composer API - -## subscribe/unsubscribe - -Using subscribe you can get update on change for signals you chose and you can -using wildcard to subscribe several signals in the same time. - -```json -signal-composer subscribe {"signal": "rear_left*"} -ON-REPLY 1:signal-composer/subscribe: {"jtype":"afb-reply","request":{"status":"success","uuid":"3d4b743b-7ac6-4d3c-8fce-721107f9dee5"}} -``` - -Then event comes up like the following: - -```json -ON-EVENT signal-composer/257b343e-8ea9-4cd7-8f9e-1904fa77f8f2({"event":"signal-composer\/257b343e-8ea9-4cd7-8f9e-1904fa77f8f2","data":{"uid":"rear_left_door","event":"low-can\/messages.doors.rear_left.open","timestamp":4833910845032292484,"value":false},"jtype":"afb-event"}) -``` - -Unsubscribe happens the same way. When no more signals are holded by the client -then it unsubscribe from the *AGL Application Framework* event handle. - -## addObjects - -Let you add sources or signals objects to the signal composer service after -its initialization phase. Use this verb and specify the file as argument, you -could use only the file name or the file name with its absolute path. - -```json -signal-composer addObjects {"file": "sig_doors.json"} -ON-REPLY 1:signal-composer/addObjects: {"jtype":"afb-reply","request":{"status":"success","uuid":"00d7a519-816e-486a-8163-3afb1face4fa"}} -signal-composer addObjects {"file": "/tmp/sig_doors.json"} -ON-REPLY 2:signal-composer/addObjects: {"jtype":"afb-reply","request":{"status":"success"}} -``` - -You can follow the activity using the service log journal and check that the -correct number of objects has been added. - -> **CAUTION**: You need to get the following permission to be able to load new -objects : `urn:AGL:permission::platform:composer:addObjects` - -## get - -You can get a signal value be requesting the API with the verb *get*: - -```json -signal-composer get {"signal": "vehicle_speed", "options": {"average": 10}} -signal-composer get {"signal": "vehicle_speed", "options": {"minimum": 10}} -signal-composer get {"signal": "vehicle_speed", "options": {"maximum": 10}} -signal-composer get {"signal": "vehicle_speed"} -``` - -You apply some simple mathematical functions by default present in the -binding, by default **last** is used: - -- **average**: make an average on X latest seconds. -- **minimum**: return the minimum value found in the X latest seconds. -- **maximum**: return the maximum value found in the X latest seconds. -- **last**: return the latest value. - -## list - -Verb **list** will output the list of defined signals. diff --git a/docs/4_APIs_and_Services/4.5_Message_Signaling/4_AGL_Service_Signal_Composer/pictures/Global_Signaling_Architecture.png b/docs/4_APIs_and_Services/4.5_Message_Signaling/4_AGL_Service_Signal_Composer/pictures/Global_Signaling_Architecture.png deleted file mode 100644 index 5cfba98..0000000 Binary files a/docs/4_APIs_and_Services/4.5_Message_Signaling/4_AGL_Service_Signal_Composer/pictures/Global_Signaling_Architecture.png and /dev/null differ diff --git a/docs/4_APIs_and_Services/4.5_Message_Signaling/5_AGL-Message-Signaling-Developer-Guidelines/4.5.5_AGL-Message-Signaling-Developer-Guidelines.pdf b/docs/4_APIs_and_Services/4.5_Message_Signaling/5_AGL-Message-Signaling-Developer-Guidelines/4.5.5_AGL-Message-Signaling-Developer-Guidelines.pdf deleted file mode 100644 index 885695d..0000000 Binary files a/docs/4_APIs_and_Services/4.5_Message_Signaling/5_AGL-Message-Signaling-Developer-Guidelines/4.5.5_AGL-Message-Signaling-Developer-Guidelines.pdf and /dev/null differ diff --git a/docs/4_APIs_and_Services/4.5_Message_Signaling/5_AGL-Message-Signaling-Developer-Guidelines/AGL-Message-Signaling-Developer-Guidelines.md b/docs/4_APIs_and_Services/4.5_Message_Signaling/5_AGL-Message-Signaling-Developer-Guidelines/AGL-Message-Signaling-Developer-Guidelines.md deleted file mode 100644 index 52718e2..0000000 --- a/docs/4_APIs_and_Services/4.5_Message_Signaling/5_AGL-Message-Signaling-Developer-Guidelines/AGL-Message-Signaling-Developer-Guidelines.md +++ /dev/null @@ -1 +0,0 @@ -[**4.5.5_AGL-Message-Signaling-Developer-Guidelines**](4.5.5_AGL-Message-Signaling-Developer-Guidelines.pdf) diff --git a/docs/4_APIs_and_Services/4.5_Message_Signaling/6_AGL-AppFW-CAN-Signaling-Benchmark/4.5.6_AGL-AppFW-CAN-Signaling-Benchmark.pdf b/docs/4_APIs_and_Services/4.5_Message_Signaling/6_AGL-AppFW-CAN-Signaling-Benchmark/4.5.6_AGL-AppFW-CAN-Signaling-Benchmark.pdf deleted file mode 100644 index 25823c8..0000000 Binary files a/docs/4_APIs_and_Services/4.5_Message_Signaling/6_AGL-AppFW-CAN-Signaling-Benchmark/4.5.6_AGL-AppFW-CAN-Signaling-Benchmark.pdf and /dev/null differ diff --git a/docs/4_APIs_and_Services/4.5_Message_Signaling/6_AGL-AppFW-CAN-Signaling-Benchmark/AGL-AppFW-CAN-Signaling-Benchmark.md b/docs/4_APIs_and_Services/4.5_Message_Signaling/6_AGL-AppFW-CAN-Signaling-Benchmark/AGL-AppFW-CAN-Signaling-Benchmark.md deleted file mode 100644 index b9b0316..0000000 --- a/docs/4_APIs_and_Services/4.5_Message_Signaling/6_AGL-AppFW-CAN-Signaling-Benchmark/AGL-AppFW-CAN-Signaling-Benchmark.md +++ /dev/null @@ -1 +0,0 @@ -[**4.5.6_AGL-AppFW-CAN-Signaling-Benchmark.pdf**](4.5.6_AGL-AppFW-CAN-Signaling-Benchmark.pdf) diff --git a/docs/4_APIs_and_Services/4.5_Message_Signaling/7_CanDevStudio_Quickstart/candevstudio/1_Usage.md b/docs/4_APIs_and_Services/4.5_Message_Signaling/7_CanDevStudio_Quickstart/candevstudio/1_Usage.md deleted file mode 100644 index a58171c..0000000 --- a/docs/4_APIs_and_Services/4.5_Message_Signaling/7_CanDevStudio_Quickstart/candevstudio/1_Usage.md +++ /dev/null @@ -1,26 +0,0 @@ ---- -edit_link: '' -title: Usage Guide -origin_url: >- - https://raw.githubusercontent.com/automotive-grade-linux/docs-sources/master/agl-documentation/candevstudio/docs/1_Usage.md ---- - - - -# Usage - -You can find the installation part -[here](http://docs.automotivelinux.org/master/docs/devguides/en/dev/reference/host-configuration/docs/5_Candevstudio.html). - -The official repo of CanDevStudio is a subpart of GENIVI and can be found -[here](https://github.com/GENIVI/CANdevStudio/). - -Launch it with following command: - -```bash -CANdevStudio -``` - -Then start a new project. - -![CANdevStudio general screenshot](pictures/CANdevStudio.png) diff --git a/docs/4_APIs_and_Services/4.5_Message_Signaling/7_CanDevStudio_Quickstart/candevstudio/2_can_device_socketcan_backend.md b/docs/4_APIs_and_Services/4.5_Message_Signaling/7_CanDevStudio_Quickstart/candevstudio/2_can_device_socketcan_backend.md deleted file mode 100644 index 1a6a52b..0000000 --- a/docs/4_APIs_and_Services/4.5_Message_Signaling/7_CanDevStudio_Quickstart/candevstudio/2_can_device_socketcan_backend.md +++ /dev/null @@ -1,44 +0,0 @@ ---- -edit_link: '' -title: Bringing up a CAN device using socketcan backend -origin_url: >- - https://raw.githubusercontent.com/automotive-grade-linux/docs-sources/master/agl-documentation/candevstudio/docs/2_can_device_socketcan_backend.md ---- - - - -# Bringing up a CAN device using socketcan backend - -* [Using a supported Linux CAN device](https://www.elinux.org/CAN_Bus): - -```bash -# Find your interface name (e.g. can0) -ip link -# Configure bitrate -sudo ip link set can0 type can bitrate 1000000 -# Bring the device up -sudo ip link set can0 up -# Optionally configure CAN termination -sudo ip link set can0 type can termination 1 -``` - -## Using slcand - -* Based on FTDI Serial driver -* Requires slcand to "convert" serial device to SocketCAN. -* Officially supported in Linux Kernel v2.6.38 - -```bash -# Create SocketCAN device from serial interface -sudo slcand -o -c -s8 -S1000000 /dev/ttyUSB0 can0 -# Bring the device up -sudo ip link set can0 up -``` - -## Using builtin Linux kernel virtual CAN module vcan - -```bash -sudo modprobe vcan -sudo ip link add dev can0 type vcan -sudo ip link set can0 up -``` diff --git a/docs/4_APIs_and_Services/4.5_Message_Signaling/7_CanDevStudio_Quickstart/candevstudio/3_Add_CAN_Device.md b/docs/4_APIs_and_Services/4.5_Message_Signaling/7_CanDevStudio_Quickstart/candevstudio/3_Add_CAN_Device.md deleted file mode 100644 index 9eef2c7..0000000 --- a/docs/4_APIs_and_Services/4.5_Message_Signaling/7_CanDevStudio_Quickstart/candevstudio/3_Add_CAN_Device.md +++ /dev/null @@ -1,41 +0,0 @@ ---- -edit_link: '' -title: Add a CAN device in CANdevStudio -origin_url: >- - https://raw.githubusercontent.com/automotive-grade-linux/docs-sources/master/agl-documentation/candevstudio/docs/3_Add_CAN_Device.md ---- - - - -# Add a CAN device in CANdevStudio - -Start a new project and grab a ***CanDevice*** from the left pane in the -***Device Layer*** section and drop it on the grid workspace. Right-Click on it -and open its ***Properties***. Here you have to set the ***backend*** and the -***interface*** name you'll want to use. Backend available are: - -- socketcan: CAN stack present by default in the Linux Kernel. This use Linux socket and open source CAN device driver (More information here). -- systeccan: CAN bus backend using the SYS TEC CAN adapters. -- peakcan: CAN bus plugin using the PEAK CAN adapters. -- tinycan: CAN bus plugin using the MHS CAN adapters. -- vectorcan: CAN bus plugin using the Vector CAN adapters. - -More details about CANdevStudio CAN bus support [here](http://doc.qt.io/qt-5.10/qtcanbus-backends.html). - -***Interface*** is the name of the device you want to use. Bring up your CAN device and use the following command to find out which one are available: - -```bash -ip link -1: lo: mtu 65536 qdisc noqueue state UNKNOWN mode DEFAULT group default qlen 1000 - link/loopback 00:00:00:00:00:00 brd 00:00:00:00:00:00 -2: enp0s25: mtu 1500 qdisc fq_codel state UP mode DEFAULT group default qlen 1000 - link/ether 90:b1:1c:6b:b2:21 brd ff:ff:ff:ff:ff:ff -3: virbr0: mtu 1500 qdisc noqueue state DOWN mode DEFAULT group default qlen 1000 - link/ether 52:54:00:56:86:80 brd ff:ff:ff:ff:ff:ff -4: virbr0-nic: mtu 1500 qdisc fq_codel master virbr0 state DOWN mode DEFAULT group default qlen 1000 - link/ether 52:54:00:56:86:80 brd ff:ff:ff:ff:ff:ff -5: docker0: mtu 1500 qdisc noqueue state DOWN mode DEFAULT group default - link/ether 02:42:81:38:a8:75 brd ff:ff:ff:ff:ff:ff -12: can0: mtu 72 qdisc noqueue state UNKNOWN mode DEFAULT group default qlen 1000 - link/can -``` diff --git a/docs/4_APIs_and_Services/4.5_Message_Signaling/7_CanDevStudio_Quickstart/candevstudio/4_Configure_CanRawSender_Node.md b/docs/4_APIs_and_Services/4.5_Message_Signaling/7_CanDevStudio_Quickstart/candevstudio/4_Configure_CanRawSender_Node.md deleted file mode 100644 index 9fc2675..0000000 --- a/docs/4_APIs_and_Services/4.5_Message_Signaling/7_CanDevStudio_Quickstart/candevstudio/4_Configure_CanRawSender_Node.md +++ /dev/null @@ -1,28 +0,0 @@ ---- -edit_link: '' -title: Configure a CanRawSender node -origin_url: >- - https://raw.githubusercontent.com/automotive-grade-linux/docs-sources/master/agl-documentation/candevstudio/docs/4_Configure_CanRawSender_Node.md ---- - - - -# Configure a CanRawSender node - -CanRawSender node lets you set a predefined list of CAN Raw messages to send. - -![CanRawSender screenshot](pictures/canrawsender.png) - -Click on the + sign to add as much as needed signals to send. For each signals, you has to define: - -- the CAN arbitration ID -- Data load -- Loop checkbox make the signal repeat infinitely -- Interval is used with loop to define how much time between 2 sends - -Once clicked on ***Play*** button in the main Window to launch the simulation, -then each signals will be sent in the same order than defined in the -CanRawSender node then using interval to repeat themselves. - -Signals without ***loop*** checked will not be sent, you have to click manually -on the ***Send*** button to trigger a sending. diff --git a/docs/4_APIs_and_Services/4.5_Message_Signaling/7_CanDevStudio_Quickstart/candevstudio/5_Using_CanRawView.md b/docs/4_APIs_and_Services/4.5_Message_Signaling/7_CanDevStudio_Quickstart/candevstudio/5_Using_CanRawView.md deleted file mode 100644 index 0d44a87..0000000 --- a/docs/4_APIs_and_Services/4.5_Message_Signaling/7_CanDevStudio_Quickstart/candevstudio/5_Using_CanRawView.md +++ /dev/null @@ -1,18 +0,0 @@ ---- -edit_link: '' -title: Using CanRawView -origin_url: >- - https://raw.githubusercontent.com/automotive-grade-linux/docs-sources/master/agl-documentation/candevstudio/docs/5_Using_CanRawView.md ---- - - - -# Using CanRawView - -***CanRawViewer*** is pretty simple to use, once simulation launched you'll see -signal flows in the window. You can use ***Clear*** button to wipe the window. - -![CanRawViewer screenshot](pictures/canrawviewer.png) - -Use the ***Combine*** button to stack by arbitration ID the CAN signals. -Then only the latest signal for each arbitration ID will be displayed. diff --git a/docs/4_APIs_and_Services/4.5_Message_Signaling/7_CanDevStudio_Quickstart/candevstudio/pictures/CANdevStudio.png b/docs/4_APIs_and_Services/4.5_Message_Signaling/7_CanDevStudio_Quickstart/candevstudio/pictures/CANdevStudio.png deleted file mode 100644 index c944e02..0000000 Binary files a/docs/4_APIs_and_Services/4.5_Message_Signaling/7_CanDevStudio_Quickstart/candevstudio/pictures/CANdevStudio.png and /dev/null differ diff --git a/docs/4_APIs_and_Services/4.5_Message_Signaling/7_CanDevStudio_Quickstart/candevstudio/pictures/canrawsender.png b/docs/4_APIs_and_Services/4.5_Message_Signaling/7_CanDevStudio_Quickstart/candevstudio/pictures/canrawsender.png deleted file mode 100644 index 766ca63..0000000 Binary files a/docs/4_APIs_and_Services/4.5_Message_Signaling/7_CanDevStudio_Quickstart/candevstudio/pictures/canrawsender.png and /dev/null differ diff --git a/docs/4_APIs_and_Services/4.5_Message_Signaling/7_CanDevStudio_Quickstart/candevstudio/pictures/canrawviewer.png b/docs/4_APIs_and_Services/4.5_Message_Signaling/7_CanDevStudio_Quickstart/candevstudio/pictures/canrawviewer.png deleted file mode 100644 index f20488b..0000000 Binary files a/docs/4_APIs_and_Services/4.5_Message_Signaling/7_CanDevStudio_Quickstart/candevstudio/pictures/canrawviewer.png and /dev/null differ diff --git a/docs/4_APIs_and_Services/4.5_Message_Signaling/8_Resources/index.md b/docs/4_APIs_and_Services/4.5_Message_Signaling/8_Resources/index.md deleted file mode 100644 index dd52e88..0000000 --- a/docs/4_APIs_and_Services/4.5_Message_Signaling/8_Resources/index.md +++ /dev/null @@ -1,95 +0,0 @@ ---- -edit_link: '' -title: Resources -origin_url: >- - https://raw.githubusercontent.com/automotive-grade-linux/docs-sources/master/docs/app-framework/index.md ---- - - - -# AGL Application Framework - -This page summarizes all materials related to AGL Application Framework - -## Source Code - -The current code of AGL App-Framework is stored on AGL Code Repository. It's divided in the following projects: - -* [src/app-framework-main](https://gerrit.automotivelinux.org/gerrit/gitweb?p=src%2Fapp-framework-main.git;a=summary) Main services -* [src/app-framework-binder](https://gerrit.automotivelinux.org/gerrit/gitweb?p=src%2Fapp-framework-binder.git;a=summary): Binder Daemon -* [src/app-framework-demo](https://gerrit.automotivelinux.org/gerrit/gitweb?p=src%2Fapp-framework-demo.git;a=summary) Demos - -## Building AGL with Application Framework support - -The Application Framework can be added easily to an AGL build using the feature 'agl-appfw-smack'. - -Typically, the following command can be called to initialize AGL build: - - # meta-agl/scripts/aglsetup.sh -m porter agl-appfw-smack agl-demo agl-devel - ... - # bitbake agl-demo-platform - -## Documentation - -Technical documentation is maintained in the source code and should be browsable with the [upcoming AGL documentation system](https://github.com/automotive-grade-linux/docs-agl) - -Temporarily, a static documentation has been made in PDF format: - -* [Introduction to Application Framework](http://iot.bzh/download/public/2016/appfw/01_Introduction-to-AppFW-for-AGL-1.0.pdf) -* [AppFW Core Documentation](http://iot.bzh/download/public/2016/appfw/02_Documentation-AppFW-Core-2.0.pdf) -* [Privileges Management](http://iot.bzh/download/public/2016/appfw/03-AGL-AppFW-Privileges-Management.pdf) - -Some extra guides are also available in PDF format: - -* [Build your 1st AGL Application](http://iot.bzh/download/public/2016/sdk/AGL-Devkit-Build-your-1st-AGL-Application.pdf) -* Applications Templates are available on [github:iotbzh/app-framework-templates](https://github.com/iotbzh/app-framework-templates) - -### Bindings Examples - -Some bindings are available to quickstart new projects: - -* GPS - see [github:iotbzh/af-gps-binding](https://github.com/iotbzh/af-gps-binding/blob/master/src/af-gps-binding.c) -* OpenXC Reader - see [github:iotbzh/txc-demo](https://github.com/iotbzh/txc-demo/blob/master/binding/txc-binding.c) -* CPU/Memory stats - see [github:iotbzh/txc-demo](https://github.com/iotbzh/txc-demo/blob/master/binding/stat-binding.c) -* Radio - see [gerrit:src/app-framework-binder](https://gerrit.automotivelinux.org/gerrit/gitweb?p=src/app-framework-binder.git;a=tree;f=bindings/radio;hb=master) -* Audio - see [gerrit:src/app-framework-binder](https://gerrit.automotivelinux.org/gerrit/gitweb?p=src/app-framework-binder.git;a=tree;f=bindings/audio;hb=master) - -The list is not exhaustive. ***Please add other bindings here !*** - -### Demos - -* Simple HTML5 Demos apps (ported from Tizen) on [github:iotbzh/afm-widget-examples](https://github.com/iotbzh/afm-widget-examples) -* Installable package with [TXC Demo Application](http://iot.bzh/download/public/2016/afb-demos/txc-demo_0.1.wgt) -* Applications available in [gerrit:app-framework-demo](https://gerrit.automotivelinux.org/gerrit/gitweb?p=src/app-framework-demo.git;a=summary) - -## Presentations - -* Oct 16 - [Application Security Model - Status Update](http://iot.bzh/download/public/2016/genivi/CyberSecurity-Genivi-Q42016-Fulup-IoTbzh.pdf) -* Sept 16 - [Building Applications with AGL Framework](http://iot.bzh/download/public/2016/genivi/CyberSecurity-Genivi-Q42016-Fulup-IoTbzh.pdf) - Also visible in [PDF version](http://iot.bzh/download/public/2016/publications/build-agl-application-AMM-Munich-2016.pdf) -* Feb 16 - [HTML5 Apps for Automotive Systems](http://iot.bzh/download/public/2016/publications/HTML5_Applications_for_Automotive_Systems.pdf) -* Feb 16 - [Application & Security Framework Proposal AGL 2.0](http://iot.bzh/download/public/2016/security/Security-Proposal-AGL20-Fulup.pdf) -* Jan 16 - [Security Architecture Proposal](http://iot.bzh/download/public/2016/security/Security-Architecture-AGL20.pdf) - -## History - -### Motivation for rewriting the App. Framework - -To get the background and motivation on why Application Framework has been rewritten: - -* [Tizen Security: lessons learnt](http://iot.bzh/download/public/2015/tizen-security-lessons-learnt-initial.pdf) -* [this discussion](https://lists.linuxfoundation.org/pipermail/automotive-discussions/2016-October/002749.html) -* [Linux Automotive Security](http://iot.bzh/download/public/2016/security/Linux-Automotive-Security-v10.pdf) - -### Comparison/Relationship with Tizen - - Tizen AGL - ---------------------------------- - App/OS isolation yes yes - Container option no possible - Native App partial* yes - HTML5 App yes yes - Cloud App No yes - Unified API (HTLM/Native) No yes - service as App** No yes - Adding API *** core core or App - Devel model bespoke Standard Web diff --git a/docs/4_APIs_and_Services/4.6_Audio_Framework/4.6.1_Overview.md b/docs/4_APIs_and_Services/4.6_Audio_Framework/4.6.1_Overview.md deleted file mode 100644 index 672f6da..0000000 --- a/docs/4_APIs_and_Services/4.6_Audio_Framework/4.6.1_Overview.md +++ /dev/null @@ -1,167 +0,0 @@ ---- -edit_link: '' -title: Overview -origin_url: >- - https://raw.githubusercontent.com/automotive-grade-linux/docs-sources/master/docs/audio/pipewire.md ---- - - - -# PipeWire Audio System Overview - -## Overview - -AGL uses the PipeWire daemon service to provide audio playback and capture -capabilities. PipeWire is accompanied by a secondary service, WirePlumber -(also referred to as the *session manager*), which provides policy management, -device discovery, configuration and more. - -Applications can connect to the PipeWire service through its UNIX socket, by -using the *libpipewire* library as a front-end to that socket. - -## Configuration - -The Audio System's configuration is mainly done in the session manager. -The session manager is the service that dictates policy, therefore this is -the place to configure options such as device properties, device priorities -and application linking policy. - -An extensive listing of configuration options for the session manager, -WirePlumber, is available in the next chapter, -[Session Manager Configuration](./wireplumber_configuration.md) - -### wireplumber-cli - -WirePlumber supports runtime configuration of devices, through the -`wireplumber-cli` tool. This tool supports the following sub-commands: - -* `wireplumber-cli ls-endpoints`: - This lists all the known audio endpoints, including devices and applications - that are streaming. In front of the devices, there is a `*` (star) character - on the "default" device, i.e. the device that is chosen by default to link - applications to. The volume and mute status of the devices is also shown. -* `wireplumber-cli set-default [id]`: - Changes the default endpoint of a specific category (capture or playback, - determined automatically by the endpoint's type) - and sets it to be the endpoint with the specified `[id]`. The id is the - number shown in front of each endpoint's name in `ls-endpoints`. -* `wireplumber-cli set-volume [id] [vol]`: - Sets the volume of `[id]` to `[vol]`. `[vol]` must be a floating point - number between 0.0 (0%) and 1.0 (100%). -* `wireplumber-cli device-node-props`: - Lists all the properties of the device nodes, useful for writing `.endpoint` - configuration files, as discussed in the _Session Management Configuration_ - chapter. - -Due to a system limitation, before running this tool on the command line, -you need to export the `XDG_RUNTIME_DIR` environment variable, like this: - -``` -export XDG_RUNTIME_DIR=/run/user/1001 -``` - -### pipewire.conf - -PipeWire also ships with **/etc/pipewire/pipewire.conf**, which can be used to -configure which pipewire modules are being loaded in the PipeWire deamon. You -should normally not need to modify anything there, unless you understand what -you are doing. - -## APIs - -### Native API - libpipewire - -The main entry point for applications to access the audio system is the API -offered by *libpipewire*. The functionality offered by *libpipewire* is vast -and it is beyond the scope of this document to describe it all. - -For playback and capture, applications should use *struct pw_stream* and its -associated methods. There are usage examples for it in the PipeWire -[source code](https://gitlab.freedesktop.org/pipewire/pipewire). - -### Native API - GStreamer (Recommended) - -For convenience, applications that use GStreamer can use the PipeWire GStreamer -elements to plug the functionality offered by *struct pw_stream* directly in -the GStreamer pipeline. These elements are called *pwaudiosrc* and *pwaudiosink* - -Example: -``` -gst-launch-1.0 audiotestsrc ! pwaudiosink -``` - -Through these elements, it is possible to specify the application role by setting -it in the *stream-properties* property of the element, as shown below: - -``` -gst-launch-1.0 audiotestsrc ! pwaudiosink stream-properties=p,media.role=Multimedia -``` - -or, in the C API: - -``` -gst_util_set_object_arg (sink, "stream-properties", "p,media.role=Multimedia"); -``` - -When using these GStreamer elements, applications **should** handle the -**GST_MESSAGE_REQUEST_STATE** message on the bus and change their state accordingly. -This message will be sent when the *session manager* requests a change in the state -due to a higher priority stream taking over. - -### ALSA Compatibility - -AGL offers a virtual ALSA device that redirects audio to PipeWire -through an ALSA PCM plugin. This device is the default one, so unless you -explicitly specify a device in your ALSA client application, audio will go -through PipeWire instead. - -This mode has limitations, however. -* There is no way to specify the role of the application. WirePlumber will -always assume it is a "Multimedia" application -* There is no way for the application to be notified when another stream -takes over. When this happens, the audio clock will simply stop progressing and -the ALSA API will likely block. - -### Audiomixer service - -See the separate -[agl-service-audiomixer](https://git.automotivelinux.org/apps/agl-service-audiomixer/about/) -documentation. - -## Runtime mechanics - -The PipeWire service is activated on demand, via systemd socket activation. -The WirePlumber service is always started and stopped together with the PipeWire -service. - -If you wish to manually start/stop/restart the service, you can do so by using -*systemctl*: -``` -systemctl start/stop/restart pipewire@1001.service -``` - -## Debugging - -When something is wrong with the audio setup, it is useful to know how to debug -it... - -### PipeWire & WirePlumber - -The PipeWire and WirePlumber daemons can be configured to be more verbose -by editing **/etc/pipewire/environment** - -* Set `G_MESSAGES_DEBUG=all` to enable WirePlumber's debug output. -* Set `PIPEWIRE_DEBUG=n` (n=1-5) to enable PipeWire's debug output. - -All messages will be available in the systemd journal, inspectable with -journalctl. - -`PIPEWIRE_DEBUG` can be set to a value between 1 and 5, with 5 being the -most verbose and 1 the least verbose. - -### AGL applications & services (AppFW) - -For AGL applications and services that are installed by the app framework, -you can set the *PIPEWIRE_DEBUG* environment variable in **/etc/afm/unit.env.d/pipewire**. -This will enable the debug messages that are printed by *libpipewire* and will -make them available also in the systemd journal. diff --git a/docs/4_APIs_and_Services/4.6_Audio_Framework/4.6.2_Session_Manager_Configuration.md b/docs/4_APIs_and_Services/4.6_Audio_Framework/4.6.2_Session_Manager_Configuration.md deleted file mode 100644 index e53a449..0000000 --- a/docs/4_APIs_and_Services/4.6_Audio_Framework/4.6.2_Session_Manager_Configuration.md +++ /dev/null @@ -1,450 +0,0 @@ ---- -edit_link: '' -title: Session Manager Configuration -origin_url: >- - https://raw.githubusercontent.com/automotive-grade-linux/docs-sources/master/docs/audio/wireplumber_configuration.md ---- - - - -# WirePlumber Configuration - -WirePlumber is a heavily modular daemon. By itself, it doesn't do anything -except load the configured modules. All the rest of the logic is implemented -inside those modules. - -Modular design ensures that it is possible to swap the implementation of -specific functionality without having to re-implement the rest of it, allowing -flexibility on target-sensitive parts, such as policy management and -making use of non-standard hardware. - -## `wireplumber.conf` - -This is WirePlumber's main configuration file. It is read at startup, before -connecting to the PipeWire daemon. Its purpose is to list all the modules -that need to be loaded by WirePlumber. - -The format of this file is custom and resembles a script with commands: - -``` -# comment -command parameter1 parameter2 ... -``` - -Lines are executed in the order they appear and each of them executes an -action defined by the command. Lines starting with `#` are treated as comments -and ignored. Possible commands are: - -* `add-spa-lib` - - Associates SPA plugin names with the names of the SPA modules that they - can be loaded from. This takes 2 parameters: a name pattern and a library name. - - This actually does not load the SPA plugin, it only calls `pw_core_add_spa_lib` - with the 2 paramteres given as arguments. As a consequence, it is safe to - call this even if the SPA module is not actually installed on the system. - - Example: - ``` - add-spa-lib api.alsa.* alsa/libspa-alsa - ``` - - In this example, we let `libpipewire` know that any SPA plugin whose name - starts with `api.alsa.` can be loaded from the SPA module - `alsa/libspa-alsa.so` (relative to the standard SPA modules directory). - -* `load-pipewire-module` - - Loads a `libpipewire` module. This is similar to the `load-module` commands - that would appear on `pipewire.conf`, the configuration file of the PipeWire - daemon. - - This takes at least 1 parameter, the module name, and optionally any module - arguments, in the format that they would be given in `pipewire.conf` - - Format: - ``` - load-pipewire-module module-name some-argument some-property=value - ``` - Example: - ``` - load-pipewire-module libpipewire-module-client-device - ``` - - This command does not affect the PipeWire daemon by any means. It exists - simply to allow loading `libpipewire` modules in the pipewire core that - runs inside WirePlumber. This is usually useful to load pipewire protocol - extensions, so that you can export custom objects to PipeWire and other - clients. - -* `load-module` - - Loads a WirePlumber module. This takes 2 arguments and an optional parameter - block. - - Format: - ``` - load-module ABI module-name { - "parameter": <"value"> - } - ``` - - The `ABI` parameter specifies the binary interface that WirePlumber shall use - to load this module. Currently, the only supported ABI is `C`. It exists to - allow future expansion, writing modules in other languages. - - The `module-name` should be the name of the `.so` file without the `.so` - extension. - - Optionally, if the `load-module` line ends with a `{`, the next lines up to - and including the next matching `}` are treated as a parameter block. - This block essentially is a - [GVariant](https://developer.gnome.org/glib/stable/glib-GVariant.html) - of type - [`a{sv}`](https://developer.gnome.org/glib/stable/gvariant-format-strings.html) - in the - [GVariant Text Format](https://developer.gnome.org/glib/stable/gvariant-text.html). - As a rule of thumb, parameter names in this block must always be strings - enclosed in double quotes, the separation between names and values is done - with the `:` character and values, regardless of their inner type, must always - be enclosed in `<` `>`. - - Note that starting the parameter block on the next line is an error. The - starting brace (`{`) must always be on the `load-module` line. - - Example: - ``` - load-module C libwireplumber-module-monitor { - "factory": <"api.alsa.enum.udev">, - "flags": <["use-adapter", "activate-devices"]> - } - ``` - - Parameters are module-dependent. They are passed as a GVariant in the - module's initialization function and it is up to the module to interpret - their meaning. WirePlumber does not have any reserved parameters. - -## Location of configuration files - -WirePlumber's default location of its configuration files is determined at -compile time by the build system. Typically, it ends up being `/etc/wireplumber`. - -In more detail, this is controlled by the `--sysconfdir` meson option. When -this is set to an absolute path, such as `/etc`, the location of the -configuration files is set to be `$sysconfdir/wireplumber`. When this is set -to a relative path, such as `etc`, then the installation prefix (`--prefix`) -is prepended to the path: `$prefix/$sysconfdir/wireplumber` - -WirePlumber expects its `wireplumber.conf` to reside in that directory. -It is possible to override that at runtime by setting the -`WIREPLUMBER_CONFIG_FILE` environment variable: - -``` -WIREPLUMBER_CONFIG_FILE=src/config/wireplumber.conf wireplumber -``` - -It is also possible to override the whole configuration directory, so that -all other configuration files are being read from a different location as well, -by setting the `WIREPLUMBER_CONFIG_DIR` environment variable: -``` -WIREPLUMBER_CONFIG_DIR=src/config wireplumber -``` - -## Location of modules - -### WirePlumber modules - -Like with configuration files, WirePlumber's default location of its modules is -determined at compile time by the build system. Typically, it ends up being -`/usr/lib/wireplumber-0.1` (or `/usr/lib//wireplumber-0.1` on -multiarch systems) - -In more detail, this is controlled by the `--libdir` meson option. When -this is set to an absolute path, such as `/lib`, the location of the -modules is set to be `$libdir/wireplumber-$abi_version`. When this is set -to a relative path, such as `lib`, then the installation prefix (`--prefix`) -is prepended to the path: `$prefix/$libdir/wireplumber-$abi_version`. - -It is possible to override this directory at runtime by setting the -`WIREPLUMBER_MODULE_DIR` environment variable: -``` -WIREPLUMBER_MODULE_DIR=build/modules wireplumber -``` - -### PipeWire and SPA modules - -PipeWire and SPA modules are not loaded from the same location as WirePlumber's -modules. They are loaded from the location that PipeWire loads them. - -It is also possible to override these locations by using environment variables: -`SPA_PLUGIN_DIR` and `PIPEWIRE_MODULE_DIR`. For more details, refer to -PipeWire's documentation. - -# module-monitor - -This module internally loads a SPA "device" object which enumerates all the -devices of a certain subsystem. Then it listens for "node" objects that are -being created by this device and exports them to PipeWire, after adjusting -their properties to provide enough context. - -`module-monitor` does not read any configuration files, however, it supports -configuration through parameters defined in the main `wireplumber.conf`. -Possible parameters are: - -* `factory` - - A string that specifies the name of the SPA factory that loads the intial - "device" object. - - Well-known factories are: - - * "api.alsa.enum.udev" - Discovers ALSA devices via udev - * "api.v4l2.enum.udev" - Discovers V4L2 devices via udev - * "api.bluez5.enum.dbus" - Discovers bluetooth devices by calling bluez5 API via D-Bus - - * `flags` - - An array of strings that enable specific functionality in the monitor. - Possible flags include: - - * "use-adapter" - - Instructs the monitor to wrap all the created nodes in an "adapter" - SPA node, which provides automatic port splitting/merging and format/rate - conversion. This should be always enabled for audio device nodes. - - * "local-nodes" - - Instructs the monitor to run all the created nodes locally in in the - WirePlumber process, instead of the default behavior which is to create - the nodes in the PipeWire process. This is useful for bluetooth nodes, - which should run outside of the main PipeWire process for performance - reasons. - - * "activate-devices" - - Instructs the monitor to automatically set the device profile to "On", - so that the nodes are created. If not specified, the profile must be - set externally by the user before any nodes appear. - -# module-config-endpoint - -This module creates endpoints when WirePlumber detects new nodes in the -pipewire graph. Nodes themselves can be created in two ways: -Device modes are being created by "monitors" that watch a specific subsystem -(udev, bluez, etc...) for devices. Client nodes are being created by client -applications that try to stream to/from pipewire. As soon as a node is created, -the `module-config-endpoint` iterates through all the `.endpoint` configuration -files, in the order that is determined by the `match-node.priority` field, -and tries to match the node to the node description in the `[match-node]` table. -Upon a successful match, a new endpoint that follows the description in the -`[endpoint]` table is created. - -## `*.endpoint` configuration files - -These files are TOML v0.5 files. At the top-level, they must contain exactly -2 tables: `[match-node]` and `[endpoint]` - -The `[match-node]` table contains properties that match a pipewire node that -exists on the graph. Possible fields of this table are: - -* `priority` - - Specifies the order in which the `.endpoint` files are being searched for a - match with a node. If a node matches the description of more than one - `.endpoint` file, the one with the highest priority wins. - - The type of this field is unsigned integer. Bigger numbers mean higher - priority. - -* `properties` - - This is a TOML array of tables, where each table must contain two fields: - `name` and `value`, both being strings. Each table describes a match against - one of the pipewire properties of the node. For a successful node match, all - the described properties must match with the node. - - The value of the `name` field must match exactly the name of the pipewire - property, while the value of the `value` field can contain '*' (wildcard) - and '?' (joker), adhering to the rules of the - [GLib g_pattern_match() function](https://developer.gnome.org/glib/stable/glib-Glob-style-pattern-matching.html). - - When writing `.endpoint` files, a useful utility that you can use to list - device node properties is: - - ``` - $ wireplumber-cli device-node-props - ``` - - Another way to figure out some of these properties *for ALSA nodes* is - by parsing the aplay/arecord output. For example, this line from `aplay -l` - is interpreted as follows: - - ``` - card 0: PCH [HDA Intel PCH], device 2: ALC3246 [ALC3246 Analog] - ``` - - ``` - { name = "api.alsa.path", value = "hw:0,2" }, - { name = "api.alsa.card", value = "0" }, - { name = "api.alsa.card.id", value = "PCH" }, - { name = "api.alsa.card.name", value = "HDA Intel PCH" }, - { name = "api.alsa.pcm.device", value = "2" }, - { name = "api.alsa.pcm.id", value = "ALC3246" }, - { name = "api.alsa.pcm.name", value = "ALC3246 Analog" }, - ``` - -The `[endpoint]` table contains a description of the endpoint to be created. -Possible fields of this table are: - -* `type` - - Required. Specifies the factory to be used for construction. - The only well-known factory at the moment of writing is: `pw-audio-softdsp-endpoint` - -* `direction` - - Required. Can be set to either `"sink"` or `"source"`. Specifies the - direction of the media flow of this endpoint. A `source` is an endpoint that - produces data (i.e. an audio capture device or a playback application) and - a `sink` is an endpoint that consumes data (audio playback device or - capture application). - -* `name` - - Optional. The name of the newly created endpoint. If not specified, - the endpoint is named after the node (from the `node.name` property of the node). - -* `media_class` - - Optional. A string that specifies an override for the `media.class` property - of the node. It can be used in special circumstances to declare that an - endpoint is dealing with a different type of data. This is only useful in - combination with a policy implementation that is aware of this media class. - -* `priority` - - Optional. An unsigned integer that specifies the order in which endpoints are - chosen to be the default of a specific device group. Possible device groups - are (determined by the endpoint's `media.class`): - - * Audio/Sink - * Audio/Source - * Video/Source - - Every time a new device endpoint is created, wireplumber picks the "default" - of the group that it belongs to, based on this priority number: the endpoint - with the biggest priority number wins. - - If not specified, the default priority of an endpoint is equal to zero - (i.e. the lowest priority). - -* `streams` - - Optional. Specifies the name of a `.streams` file that contains the - descriptions of the streams to create for this endpoint. This currently - specific to the implementation of the `pw-audio-softdsp-endpoint` and might - change in the future. - -## `*.streams` configuration files - -These files contain lists of streams with their names and priorities. -They are TOML v0.5 files. - -Each `.streams` file must contain exactly one top-level array of tables, -called `streams`. Every table must contain exactly two fields: -`name` and `priority`. - -The `name` of each stream is used to create the streams on new endpoints. - -The `priority` of each stream is being interpreted by the policy module to -apply restrictions on which app can use the stream at a given time. - -# module-config-policy - -This module implements demo-quality policy management that is partly driven -by configuration files. The configuration files that this module reads are -described below: - -## `*.endpoint-link` - -These files contain rules to link endpoints with each other. -They are TOML v0.5 files. - -Endpoints are normally created by another module, such -as `module-config-endpoint` which is described above. -As soon as an endpoint is created, the `module-config-policy` uses the -information gathered from the `.endpoint-link` files in order to create a -link to another endpoint. - -`.endpoint-link` files can contain 3 top-level tables: -* `[match-endpoint]`, required -* `[target-endpoint]`, optional -* `[endpoint-link]`, required - -The `[match-endpoint]` table contains properties that match an endpoint that -exists on the graph. Possible fields of this table are: - -* `priority` - - Specifies the order in which the `.endpoint-link` files are being searched - for a match with an endpoint. If an endpoint matches the description of more - than one `.endpoint-link` file, the one with the highest priority wins. - - The type of this field is unsigned integer. Bigger numbers mean higher - priority. - -* `direction` - - Required. Can be set to either `"sink"` or `"source"`. Specifies the - direction of the media flow of this endpoint. A `source` is an endpoint that - produces data (i.e. an audio capture device or a playback application) and - a `sink` is an endpoint that consumes data (audio playback device or - capture application). - -* `name` - - Optional. The name of the endpoint. It is possible to use wildcards here to - match only parts of the name. - -* `media_class` - - Optional. A string that specifies the `media.class` that the endpoint - must have in order to match. - -* `properties` - - This is a TOML array of tables, where each table must contain two fields: - `name` and `value`, both being strings. Each table describes a match against - one of the pipewire properties of the endpoint. For a successful endpoint - match, all the described properties must match with the endpoint. - -The `[target-endpoint]` table contains properties that match an endpoint that -exists on the graph. The purpose of this table is to match a second endpoint -that the original matching endpoint from `[match-endpoint]` will be linked to. -If not specified, `module-config-policy` will look for the session "default" -endpoint for the type of media that the matching endpoint produces or consumes -and will use that as a target. Possible fields of this table are: - -* `direction`, `name`, `media_class`, `properties` - - All these fields are permitted and behave exactly as described above for the - `[match-endpoint]` table. - -* `stream` - - This field specifies a stream name that the link will use on the target - endpoint. If it is not specified, the stream name is acquired from the - `media.role` property of the matching endpoint. If specified, the value of - this field overrides the `media.role`. - -The `[endpoint-link]` table specifies properties of the link. Possible fields -of this table are: - -* `keep` - - A boolean field. If set to true, the link is always kept active and ignores - policy rules regarding corking or stream priority. This link will also not - affect the rules for other links. For example, if a keep=true link is - activating a high priority stream, lower priority streams can still work on - the same target endpoint for links with keep=false. diff --git a/docs/4_APIs_and_Services/4.6_Audio_Framework/4.6.3_Bluetooth.md b/docs/4_APIs_and_Services/4.6_Audio_Framework/4.6.3_Bluetooth.md deleted file mode 100644 index 668b2f3..0000000 --- a/docs/4_APIs_and_Services/4.6_Audio_Framework/4.6.3_Bluetooth.md +++ /dev/null @@ -1,122 +0,0 @@ ---- -edit_link: '' -title: Bluetooth -origin_url: >- - https://raw.githubusercontent.com/automotive-grade-linux/docs-sources/master/docs/audio/bluez-alsa.md ---- - - - -# bluez-alsa - -## Introduction - -Bluetooth Audio ALSA Backend allow bluetooth audio without PulseAudio. - -This project is a rebirth of a direct integration between Bluez and ALSA. Since Bluez >= 5, the build-in integration has been removed in favor of 3rd party audio applications. From now on, Bluez acts as a middleware between an audio application, which implements Bluetooth audio profile, and a Bluetooth audio device. - -github source : [bluez-alsa](https://github.com/Arkq/bluez-alsa) - -## Add bluez-alsa to an AGL image - -You can add bluez-alsa to your image - -```yocto -IMAGE_INSTALL_append = "bluez-alsa" -``` - -## Check bluez-alsa status - -You can check the bluez-alsa status by running: - -```bash -systemctl status bluez-alsa.service -``` - -## Stop pulseaudio - -You must disable pulseaudio if you want to use bluez-alsa - -```bash -systemctl --user stop pulseaudio -``` - -or disable pulseaudio bluetooth support - -```bash -vi /etc/pulse/default.pa -#.ifexists module-bluetooth-policy.so -#load-module module-bluetooth-policy -#.endif - -#.ifexists module-bluetooth-discover.so -#load-module module-bluetooth-discover -#.endif -``` - -## Connect your Bluetooth device - -You need to connect a bluetooth device - -```bash -$ bluetoothctl -[bluetooth]# pair ${BT_ADDR} -[bluetooth]# connect ${BT_ADDR} -[bluetooth]# info ${BT_ADDR} -``` - -Here somes documentation links: - -* [Bluetooth headset from archlinux](https://wiki.archlinux.org/index.php/Bluetooth_headset) -* [Bluetooth Headset from gentoo](https://wiki.gentoo.org/wiki/Bluetooth_Headset) -* [Bluez A2DP AudioSink for ALSA](http://www.lightofdawn.org/blog/?viewDetailed=00032) -* [Bluez A2DP](http://www.lightofdawn.org/wiki/wiki.cgi/BluezA2DP) - -## Test bluez-alsa speacker - -```bash -wget http://www.kozco.com/tech/piano2.wav - -aplay -D bluealsa:HCI=hci0,DEV=${BT_ADDR},PROFILE=a2dp ./piano2.wav -``` - -## Add bluez-alsa pcm config to alsa - -```bash -vi /etc/asound.conf -# Bluetooth headset -pcm.btheadset { - type plug - slave.pcm { - type bluealsa - device "${BT_ADDR}" - profile "a2dp" - } - hint { - show on - description "Bluetooth Audio ALSA Backend" - } -} -``` - -Doc [asoundrc](https://alsa.opensrc.org/Asoundrc) - -Test bluez-alsa pcm - -```bash -aplay -D btheadset ./piano2.wav -``` - -## Test gstreamer player - -```bash -gst-launch-1.0 uridecodebin uri=file:///mnt/Holy-Mountain.mp3 ! alsasink device=btheadset -``` - -## Test bluez-alsa phone - -After connected your phone with bluez: - -```bash -bluealsa-aplay ${BT_ADDR} -``` diff --git a/docs/4_APIs_and_Services/4.7_HMI_Framework/4.7.1_Home_Screen_Developer_Guide.md b/docs/4_APIs_and_Services/4.7_HMI_Framework/4.7.1_Home_Screen_Developer_Guide.md deleted file mode 100644 index 50baf6d..0000000 --- a/docs/4_APIs_and_Services/4.7_HMI_Framework/4.7.1_Home_Screen_Developer_Guide.md +++ /dev/null @@ -1,532 +0,0 @@ ---- -edit_link: '' -title: Home Screen Developer Guide -origin_url: >- - https://git.automotivelinux.org/apps/agl-service-homescreen/plain/doc/ApplicationGuide.md?h=master ---- - - - -**HomeScreen GUI Application / HomeScreen Service Guide** -==== - Revision: 0.1 - TOYOTA MOTOR CORPORATION - Advanced Driver Information Technology - 13th/May/2019 - -* * * - -## Table of content -- [Target reader of this document](#target-reader-of-this-document) -- [Overview](#overview) -- [Getting Start](#getting-start) - - [Supported environment](#supported-environment) - - [Build](#build) - - [Configuring](#configuring) - - [How to call HomeScreen APIs from your Application?](#how-to-call-homescreen-apis-from-your-application) -- [Supported usecase](#supported-usecase) -- [Software Architecture](#software-architecture) -- [API reference](#api-reference) -- [Sequence](#sequence) - - [Initialize](#initialize-sequence) - - [Tap Shortcut(deprecated)](#tap-shortcut-sequence) - - [ShowWindow](#showwindow-sequence) - - [On Screen Message / Reply Sequence(deprecated)](#on-screen-message-reply-sequence) - - [ShowOnscreen](#showonscreen-sequence) - - [ShowNotification](#shownotification-sequence) - - [ShowInformation](#showinformation-sequence) -- [Sample code](#sample-code) -- [Limitation](#limitation) -- [Next Plan](#next-plan) -- [Appendix](#appendix) - -* * * - -## Target reader of this document -Application developer whose software uses HomeScreen. - -* * * - -## Overview -HomeScreen is built with a GUI application created with Qt(referred as HomeScreenGUI), and a service running on afb-daemon (referred as HomeScreenBinder). -HomeScreen can start/switch applications run in AGL, also displays information such as onscreen messages. - -You can find these projects in AGL gerrit. - -- [homescreen(HomeScreenGUI)](https://gerrit.automotivelinux.org/gerrit/#/admin/projects/apps/homescreen) -- [launcher(LauncherGUI)](https://gerrit.automotivelinux.org/gerrit/#/admin/projects/apps/launcher) -- [agl-service-homescreen(HomeScreenBinder's binding library)](https://gerrit.automotivelinux.org/gerrit/#/admin/projects/apps/agl-service-homescreen) -- [libhomescreen(library for application to communication with HomeScreenBinder]( https://gerrit.automotivelinux.org/gerrit/#/admin/projects/src/libhomescreen) -- [libqthomescreen(library for qt application to communication with HomeScreenBinder based on libhomescreen)](https://gerrit.automotivelinux.org/gerrit/#/admin/projects/src/libqthomescreen) - -Also HomeScreenGUI is using libwindowmanager. - -* * * - -## Getting Start - -### Supported environment - -| Item | Description | -|:------------|:----------------------------------| -| AGL version | Grumpy Guppy | -| Hardware | Renesas R-Car Starter Kit Pro(M3) | - - -### Build - -**Download recipe** - -``` -$ mkdir WORK -$ cd WORK -$ repo init -u https://gerrit.automotivelinux.org/gerrit/AGL/AGL-repo -$ repo sync - -``` - -Then you can find the following recipes. - -* `meta-agl-demo/recipes-demo-hmi/homescreen` - -* `meta-agl-devel/meta-hmi-framework/recipes-demo-hmi/launcher` - -* `meta-agl-demo/recipes-demo-hmi/agl-service-homescreen` - -* `meta-agl-demo/recipes-demo-hmi/libhomescreen` - -* `meta-agl-devel/meta-hmi-framework/recipes-demo-hmi/qlibhomescreen` - - -**Bitbake** - -``` -$ source meta-agl/scripts/aglsetup.sh -m m3ulcb agl-demo agl-devel agl-appfw-smack agl-hmi-framework -$ bitbake agl-demo-platform -``` - -### Configuring -To use HomeScreen API, an application shall paste the following configuration definition into "config.xml" of application. - -``` - - - - -``` - -### How to call HomeScreen APIs from your Application? -HomeScreen provides a library which is called "libhomescreen". -This library treats "json format" as API calling. -For example, if an application wants to call "showWIndow()" API, then you should implement as below. - -At first the application should create the instance of libhomescreen. - -``` -LibHomeScreen* libhs; -libhs = new LibHomeScreen(); -libhs->init(port, token); -``` - -The port and token is provided by Application Framework - -Execute the "showWindow()" function. - -``` -libhs->showWindow("application_id", "display_area"); -``` - -Regarding the detail of showWindow() API, please refer [this](#homescreen-specific-api) section. -The first parameter is the appid of application which want to display,liked "dashboard". -And the second parameter corresponds to display_area which defined by windowmanager,usually "normal", -so in this case "showWindow" the two parameters are proper string. - -See also our [Sample code](#sample-code). - -* * * - -## Supported usecase -1. HomeScreenGUI sending showWindow event to applications - - Applications using libhomescreen to subscribe the showWindow event, - HomeScreenGUI will send showWindow event to applications. -2. Display OnScreen messages(deprecated) - - Applications sending OnScreen messages to homescreen-service, and OnScreenAPP - will get these message and display. -3. Get OnSreen Reply event(deprecated) - - When OnScreen messages is displaying, OnScreenAPP will send a reply event to applications. -4. Display OnScreen by showWindow - - When application who want to show OnScreen,it can call "showWindow",then OnScreenApp will - display request OnScreen. -5. Hide OnScreen by hideWindow - - When application who want to hide OnScreen which is displaying,it can call "hideWindow",then OnScreenApp - will hide OnScreen. -6. Send OnScreen Reply by replyShowWindow - - When user touch the button of OnScreen, OnScreenApp can call "relplyShowWindow" to send reply information - back to application. -7. Show Notification on HomeScreenGUI - - When application who want to display a notification,it can call "showNotification",then HomeScreenGUI will - display the notification contents on the screen top area. -8. Show Information on HomeScreenGUI - - When application who want to display a information,it can call "showInformation",then HomeScreenGUI will - display the information contents on the screen bottom area. - -* * * - -## Software Architecture -The architecture of HomeScreen is shown below. -HomeScreen is the service designed to be used by multiple applications. -Therefore HomeScreen framework consists on two binder layers. Please refer the following figure. -The upper binder is for application side security context for applications. The lower binder is for servide side security context. -Usually application side binder has some business logic for each application, so the number of binders depend on the number of applications which use HomeScreen. -On the other hand, regarding lower binder there is only one module in the system. This binder receives all messages from multiple applications (in detail, it comes from upper layer binder). - -The communication protocols between libhomescreen and upper binder, upper binder and lower binder(homescreen-binding) are WebSocket. - -![software-stack.png](parts/software-stack.png) - -* * * - -## API reference -"libhomescreen" and "agl-service-homescreen" provides several kinds of APIs. - -### HomeScreen Specific API - -- LibHomeScreen::init (const int port, const std::string &token) -``` - port [in] : This argument should be specified to the port number to be used for WebSocket - token [in] : This argument should be specified to the token to be used for WebSocket - - Create connection to homescreen-service by port and token which provided by - application framework. This API must be called before calling other api. -``` -- LibHomeScreen::tapShortcut(const char *application_id) -``` - application_id [in] : Tapped application id (label) - - This api is deprecated, recommend using showWindow. -``` -- LibHomeScreen::onScreenMessage(const char *display_message) -``` - display_message [in] : message for display - - This api is deprecated, recommend using showWindow/hideWindow to call onscreenapp. -``` -- LibHomeScreen::onScreenReply(const char *reply_message) -``` - reply_message [in] : message for reply - - This api is deprecated, recommend using replyShowWindow. -``` -- LibHomeScreen::registerCallback(void(*event_cb)(const std::string &event, struct json_object *event_contents), void(*reply_cb)(struct json_object *reply_contents), void(*hangup_cb)(void)=nullptr) -``` - event_cb [in] : This argument should be specified to the callback for subscribed event - reply_cb [in] : This argument should be specified to the reply callback for call function - hangup_cb [in] : This argument should be specified to the hangup callback for call function - - This api is deprecated, recommend using set_event_handler. -``` -- LibHomeScreen::set_event_handler(enum EventType et, handler_func f) -``` - et [in] : event name - f [in] : event handler - - Setting event handler for Homescreen-Service Event. -``` -- LibHomeScreen::call(const string& verb, struct json_object* arg) -- LibHomeScreen::call(const char* verb, struct json_object* arg) -``` - verb [in] : This argument should be specified to the API name (e.g. "tap_shortcut") - arg [in] : This argument should be specified to the argument of API. - And this argument expects JSON object - - Call homescreen-service verb. -``` -- LibHomeScreen::subscribe(const string& event_name) -``` - event_name [in] : This argument should be specified to the event name - - Subscribe homescreen-service event. Deprecated, recommend using set_event_handler. -``` -- LibHomeScreen::unsubscribe(const string& event_name) -``` - event_name [in] : This argument should be specified to the event name - - Unsubscribe homescreen-service event. Deprecated, recommend using set_event_handler. -``` -- LibHomeScreen::showWindow(const char* application_id, json_object* json) -``` - application_id [in] : This argument should be specified to the application's id - json [in] : This argument should be specified to the json parameters - - Request to show the window of application_id, and set display area in json liked - {"area":"normal.full"}. -``` -- LibHomeScreen::hideWindow(const char* application_id) -``` - application_id [in] : This argument should be specified to the application's id - - Request to hide the window of application_id. -``` -- LibHomeScreen::replyShowWindow(const char* application_id, json_object* json) -``` - application_id [in] : This argument should be specified to the onscreen reply to applilcation id - json [in] : This argument should be specified to the json parameters - - Post reply information to who called showWindow. -``` -- LibHomeScreen::showNotification(json_object* json) -``` - json [in] : This argument should be specified to the json parameters. - - Post Notification to Homescreen which will display at top area of Homescreen. -``` -- LibHomeScreen::showInformation(json_object* json) -``` - json [in] : This argument should be specified to the json parameters. - - Post Information to Homescreen which will display at bottom area of Homescreen. -``` - -* * * - -## Sequence - -### Initialize Sequence -![initialize-set-event-handler](parts/initialize-set-event-handler.svg) - -### Tap Shortcut Sequence -![tap_shortcut.svg](parts/tap_shortcut.svg) - -### ShowWindow Sequence -![showWindow.svg](parts/showWindow.svg) - -### On Screen Message / Reply Sequence -![on_screen_message.svg](parts/on_screen_message.svg) - -### ShowOnScreen Sequence -![showOnScreen.svg](parts/showOnScreen.svg) - -### ShowNotification Sequence -![showNotification.svg](parts/showNotification.svg) - -### ShowInformation Sequence -![showInformation.svg](parts/showInformation.svg) - -* * * - -## Sample code -You can find sample implementation of HomeScreen as below. - -* `libhomescreen/sample/simple-egl` - -* `libhomescreen/sample/template` - -* * * - -## Limitation -None. - -* * * - -## Next Plan -None. - -* * * - -## Appendix - -``` -@startuml - -title Application initialization phase - -entity App -entity HomeScreenBinder -entity HomeScreenGUI - -App->HomeScreenBinder: init(port, token) -App->HomeScreenBinder: set_event_handler() - -note over HomeScreenBinder - setup event handler the App wishes to receive - ・LibHomeScreen::Event_ShowWindow - ・LibHomeScreen::Event_HideWindow - ・LibHomeScreen::Event_ReplyShowWindow -end note - -@enduml -``` - -``` -@startuml -title Application Callback Event TapShortcut phase -entity App -entity HomeScreenBinder -entity HomeScreenGUI -App->HomeScreenBinder: set_event_handler() - -note over App - LibHomeScreen::Event_TapShortcut -end note - -HomeScreenGUI->HomeScreenBinder: tapShortcut(application_id) -HomeScreenBinder->App: event_handler(application_id) -@enduml -``` - -``` -@startuml - -title Application callback event showWindow phase - -actor user -entity "homescreen-service" as hss -entity launcher -entity App -entity windowmanager as wm - -user-->launcher: tap app's icon -launcher->hss: showWindow() -note over hss,App -{"application_id":"tapped application id", "parameter":{"area":"display area", ...}} -end note -hss->App: push showWindow event -App->wm: activateWindow("application_name","display area") -wm-->App: push syncDraw event -App->App: display - -@enduml -``` - -``` -@startuml -title Application Callback Event On Screen Message / Reply phase -entity App -entity HomeScreenBinder -entity HomeScreenGUI - -HomeScreenGUI->HomeScreenBinder: set_event_handler() - -note over HomeScreenGUI - LibHomeScreen::Event_OnScreenMessage -end note - - -App->HomeScreenBinder: set_event_handler() - -note over App - LibHomeScreen::Event_OnScreenReply -end note - -App->HomeScreenBinder: onScreenMessage(display_message) -HomeScreenBinder->HomeScreenGUI: event_handler(display_message) -HomeScreenGUI->HomeScreenBinder: onScreenReply(reply_message) -HomeScreenBinder->App: event_handler(reply_message) -@enduml -``` - -``` -@startuml - -title show/hide onscreen phase - -actor user -entity "homescreen-service" as hss -entity App -entity onscreenapp -entity windowmanager as wm - -== show onscreen == -user->App: the operation request onscreen -App->hss: showWindow() -note over App,hss -{"application_id":"onscreenapp", -"parameter":{"area":"display area", "file":"qml file path", -"data":{"the datas to onscreen qml"}}} -end note - -hss->onscreenapp: push showWindow event -note over hss,onscreenapp -{"application_id":"onscreenapp", -"parameter":{"area":"display area", "file":"qml file path", -"data":{"the datas to onscreen qml"}, -"replyto":"caller application id" -}} -end note - -onscreenapp->onscreenapp: get and save parameters -onscreenapp->wm: activateWindow("onscreeapp", "display area") -alt can show -wm-->onscreenapp: push syncDraw event -onscreenapp->wm: endDraw("onscreeapp") -onscreenapp->onscreenapp: load and display qml file -else can't show -note over onscreenapp,wm -do nothing -end note -end - -== hide onscreen == - -user->onscreenapp: tap onscreen's button -onscreenapp->hss: replyShowWindow() -note over onscreenapp,hss -{"application_id":"the application id who called onscreenapp", -"parameter": {"buttonName": "VOLUME_UP", "buttonPressMode": "shortPress", "buttonPressState": "release"}} -end note -hss->App: push replyShowWindow event -App->App: call reply function -App->hss: hideWindow("onscreenapp") -hss->onscreenapp: push hideWindow event -note over hss,onscreenapp -{"application_id":"request hideWindow application id"} -end note -onscreenapp->wm: deactivateWindow("onscreenapp"); -onscreenapp->onscreenapp: hide window - -@enduml -``` - -``` -@startuml - -title show notification on HomeScreen top area - -entity "homescreen-service" as hss -entity homescreen -entity App - -App->hss: showNotification() -note over App,hss -{"icon":"display icon", "text":"display text"} -end note -hss-> homescreen: push showNotification event -note over hss,homescreen -{"application_id":"request application id", -"parameter":{"icon":"display icon", "text":"display text"}} -end note - -homescreen->homescreen: display notification message 3s - -@enduml -``` - -``` -@startuml - -title show information on HomeScreen bottom area - -entity "homescreen-service" as hss -entity homescreen -entity App - -App->hss: showInformation() -note over hss -{"info":"display information"} -end note -hss-> homescreen: push showInformation event - -homescreen->homescreen: display information message 3s - -@enduml -``` diff --git a/docs/4_APIs_and_Services/4.7_HMI_Framework/4.7.2_WindowManager-Guide.md b/docs/4_APIs_and_Services/4.7_HMI_Framework/4.7.2_WindowManager-Guide.md deleted file mode 100644 index d372be7..0000000 --- a/docs/4_APIs_and_Services/4.7_HMI_Framework/4.7.2_WindowManager-Guide.md +++ /dev/null @@ -1,938 +0,0 @@ ---- -edit_link: '' -title: Window Manager Developer Guide -origin_url: >- - https://git.automotivelinux.org/apps/agl-service-windowmanager/plain/doc/ApplicationGuide.md?h=master ---- - - - -# Window Manager Application Guide - -## Table of content - -- [Target reader of this document](#target-reader-of-this-document) -- [Overview](#overview) - - [Supported usecase](#supported-usecase) -- [Getting Started](#getting-started) - - [Build](#build-by-sdk) - - [Install](#install) - - [Bitbake](#bitbake) - - [Enable to call Window Manager](#enable-to-call-window-manager) -- [Software Architecture](#software-architecture) -- [Sequence](#sequence) -- [API reference](#api-reference) - - [Request to Window Manager](#request-to-window-manager) - - [Event from Window Manager](#event-from-window-manager) - - [Client Library](#client-library) -- [Sample code](#sample-code) -- [Policy Manager](#policy-manager) - - [Enabling split](#enabling-split) -- [Release Note](#release-note) - -| Version | Author | Updated at | -|:-:|:-:|:-:| -| 0.8 | TOYOTA MOTOR CORPORATION| 22th/Feb/2019 | - -* * * - -## Target reader of this document - -This document is intended for developers and system integrators who -need to know, how Window manager works and how it is to be used. - -### Scope of this Document - -This document covers Window manager that was implemented for TMC and -delivered to the Automotive Grade Linux (AGL) project. It includes its -implementation details, concepts of operation, configuration and usage. - -It does not include - -- document of the underlying architecture, see - [HMI-Framework](https://wiki.automotivelinux.org/hmiframework). - -- document of the AGL application framework and its technologies, - see [AGL Application - Framework](https://wiki.automotivelinux.org/agl-distro/app-framework). - -- document of HomeScreen, see - [HomeScreen](./ApplicationGuide.html). - -It is highly recommended to have a good understanding of these documents -and projects before using Window manager. - -* * * - -# Overview - -Window Manager is the service process which provides window management based on policy. -And implements a layout switching of applications on -multiple layers and with different layer layouts. -Window Manager is based on ivi layer management from GENIVI and AGL application framework. - -Window Manager consists of - -- afb-binder -- service binding library -- shared library for policy management -- configuration files - -In order to understand Window Manager, the below figure shows the one of typical usecases. -In this example, there are two mode for window management. - -1. Window Management in `Car Stops` -1. Window Management in `Car Runs` - -![Figure: Typical usecase](parts/state_change_example.png) - -The important points are: - -- Window transition should be done by Window Manager - - Window Manager switch application displayed on top layer by user operation(touch shortcut button). - In this example, when an user touches `navigation` shortcut button, Window Manager displays `navigation` and hide `launcher`. Next, when an user touches `videoplayer` shortcut button, Window Manager divides a screen into two parts and display two applications. - -- There is a priority `role` for each application. - - Window Manager realizes state transition change based on the policy which consists of `role`. - According to the state transition table, it controls the visibility of application window, layout change, and so on. - The reasons why this is necessary are - -- to support user driving -- not to disturb a driver concerns on driving for safety - - In this example, for safety, when the car starts running, Window Manager set up the role `videoplayer` - to be masked and uncontrollable by user not to disturb driver concerns. - And, for supporting driving, set up `navigation` role to be displayed 3 seconds after the car ran. - In `Car Run` state, the user can't switch to other application from Navigation application until car stops. - -## Supported usecase - -1. Window Management -- When an user chooses a different application, Window Manager changes the layout and then displays the application. -- When an user chooses a different application, Window Manager changes the layout and then hides the displayed application. -2. Policy Management -- Window Manager changes layout according to policy table based on `role`. -3. Define Layout by `area` configuration -- Window Manager realizes the abstracted `area` and can resize the window by using it. User can easily edit this configuration. - -* * * - -## Getting Started - -### Build by SDK - -```bash -git clone https://gerrit.automotivelinux.org/gerrit/apps/agl-service-windowmanager -cd agl-service-windowmanager -mkdir build -cd build -source // normally this is /opt/agl-sdk/environment -cmake .. -make -make package -``` - -The widget package is populated in the 'package' directory. - -```bash -ls package/ -root windowmanager-service.wgt -``` - -### Install - -Copy windowmanager-service.wgt to the file system then execute the following command. - -```bash -afm-util install windowmanager-service.wgt -``` - -## Bitbake - -You can make Window Manager object files with the following two stage operations. - -### Download recipe - -```bash -mkdir WORK -cd WORK -repo init -u https://gerrit.automotivelinux.org/gerrit/AGL/AGL-repo -repo sync -``` - -### Execute Bitbake - -```bash -source meta-agl/scripts/aglsetup.sh -m m3ulcb agl-demo hmi-framework -bitbake agl-demo-platform -``` - -* * * - -## Enable to call Window Manager - -To call Window Manager, it is important to enable the permission from security framework. -To use Window Manager API, an application or a service shall add the following configuration definition into "config.xml" of your application. - -```xml - - - -``` - -To call Window Manager function easily, Window Manager provides a library which is called "libwindowmanager". -This library provides a function style API calling interface. -So you can include the libwindowmanager.hpp header file, and can link against this library. -Please also refer to the sample application. - -See also our [Sample code](#sample-code). - -* * * - -## Software Architecture - -The static relationship with other components is shown below. -The actual logic of Window Manager is the binding in Binder(afb-daemon). -Window Manager is based on AGL application framework, -so the IPC via websocket is protected by AGL application framework. - -The upper binder is for the application side security context. -The lower binder is the Window Manager for the server side security context. -Usually an application side binder has some business logic for each application, so the number of binders depend on the number of applications which use Window Manager. -On the other hand, regarding lower binder there is only one module in the system. This binder receives messages from multiple applications. - -An application can use libwindowmanager.so to call Window Manager API simply. - -Window Manager is based on the GENIVI layer management system. - -![wm_software_stack.png](parts/wm_software_stack.png) - -### Layers - -Layers are entities that means the application stack group defined in `layers.json`. -This doesn't mean layer ID defined in GENIVI ivi layer. -The layer ID is used for application itself in Window Manager. -Currently, application can't have multiple surfaces in Window Manager. - -### Surfaces - -Surfaces are *placed* on layers . The surface -will then be resized to dimensions, according to the name of `areas.json` -application requests by `activateWindow` or policy management. -As default, `normal.full` is set by libwindowmanager for native application. - -### Configuration - -The window manager is configured with the *layers.json*, *areas.json*, *roles.db* configuration -files. By default they are searched in `${AFM_APP_INSTALL_DIR}/etc/`. - -Sample configurations are provided with the window manager -implementation, these samples are installed to ${AFM_APP_INSTALL_DIR}/etc/ . - -This configuration is supposed to be configured by policy designer which means OEM or Tier1. - -#### layers.json - -`layers.json` has three roles. - -1. Create application containers `Layer`. -1. Set id range for applications. -1. Attach application to `Layer` according to the role application requests. - -The sample configuration is here - -```json -{ - "comment": "Surface ID to Layer ID mapping", - - "main_surface": { - "surface_role": "HomeScreen", - "comment": "This surface should never be made invisible (The HomeScreen)" - }, - - "mappings": [ - { - "role": "BackGroundLayer", - "name": "BackGroundLayer", - "layer_id": 999, - "comment": "Single BackGround layer map for the map, radio, music and video" - }, - { - "role": "homescreen", - "name": "FarHomeScreen", - "layer_id": 1000, - "comment": "FarHomeScreen is the part of HomeScreen. The z order of this layer is lower than NearHomeScreen" - }, - { - "role": "music|video|browser|radio|phone|map|hvac|settings|dashboard|poi|mixer|sdl|launcher|fallback", - "name": "Apps", - "layer_id": 1001, - "comment": "Range of IDs that will always be placed on layer 1001" - }, - { - "role": "^on_screen.*", - "name": "OnScreen", - "layer_id": 9999, - "comment": "Range of IDs that will always be placed on the OnScreen layer, that gets a very high 'dummy' id of 9999" - } - ] -} -``` - -Each mapping defines the following items to map corresponding surfaces -to a layer. - -- `role` defines what kind of ability the application has. And the application will be attached to `Layer` according to the `role`. - A regular expression that application drawing names - are matched against. If applications match this regular expression, - the surface will be visible on this layer. - -- `name` is just a name definition for `Layer`, it has no - functional use apart from identifying a layer with a name. -- `layer_id` is the id used in GENIVI IVI layer management control. - -`Layer` stacks from beginning to end. - -The above `Layer` example image is below. - -![wm_layer_stack.png](parts/wm_layer_stack.png) - -Note: -"fallback" role is the special role. This role is set if the role application requests doesn't exist -in `layers.json`. Then, Window Manager will accept any applications. -If the "fallback" is not set in layers.json, window manager blocks the application displaying in such case. -In such a situation, you have to add your role(application name) at "role" in layers.json. - -Note: -`BackGroundLayer` name of `Layer` is exception for work around. This layer is fallback layer not to stop event loop of application when it becomes invisible. -The problem is issued in . - -#### areas.json - -Area means abstract expressions of 2-dimensional size and position. -`areas.json` defines the area which an application is set. - -```json -{ - "areas": [ - { - "name": "fullscreen", - "rect": { - "x": 0, - "y": 0, - "w": 1080, - "h": 1920 - } - }, - { - "name": "normal.full", - "rect": { - "x": 0, - "y": 218, - "w": 1080, - "h": 1488 - } - }, - { - "name": "split.main", - "rect": { - "x": 0, - "y": 218, - "w": 1080, - "h": 744 - } - }, - { - "name": "split.sub", - "rect": { - "x": 0, - "y": 962, - "w": 1080, - "h": 744 - } - } - ] -} -``` - -The image of the above setting is described below. - -![wm_area.png](parts/wm_area.png) - -- `name` is an abstract data of rectangle. - -- `rect` has 4 arguments. `x`, `y` means the offset from (0, 0) of screen.`w` means the width of the area, and `h` means the height of the area. The dimensions can be specified relative to the screen dimensions. - -The dimensions can be specified absolute to the screen dimensions. But if `fullscreen` is not suitable to screen dimensions, Window Manager scales the area automatically. - -Note: - -`fullscreen` must be set because this is the base size of scaling in Window Manger. - -Note: - -The direction of the coordinates depends on `transform` in weston.ini. -Currently, agl-demo-platform set `transform=270`. -This suppose to use screen vertically. - -#### roles.db - -* * * - -## Sequence - -To understand the sequence between application and window manager, refer to the [spec document](https://wiki.automotivelinux.org/hmiframework). - -The typical sequence to render your application, follow the sequence below. - -1. Register your role (and request surfaceID) - -![request_role.png](parts/request_role.png) - -The above sequence is the initialization phase of your application to use Window Manager. -An Application has to register your `role` to Window Manager. For ivi-shell application, Window Manager generates surfaceID to input it into the function -to create surface. And also it is important for synchronization to get `syncDraw` event for receiving the request for resize and redraw, and notifying Window Manager of `endDraw`, so register callback function with setEventHandler for `syncDraw`. - -[requestSurface](#requestSurface) - -[setEventHandler](#wm_subscribe) - -setEventHandler is API of libwindowmanager. This calls wm_subscribe internally. - -2. Display your window - -![hmi_framework_designed_seq_toyota.png](parts/hmi_framework_designed_seq_toyota.png) - -To display your window, your application has to request `activateWindow` with `role` and `area` to Window Manager. -Window Manager checks the app should be visible on the `area` according to the policy table using `role` . -If it is accepted, afb_req_success will be returned, and next Window Manager -will push the event `syncDraw` to applications which will be displayed. If it is denied, afb_req_fail will be returned. In this sample sequence, `syncDraw` is emitted to the apps who requested only, -but this shall be emitted to other applications whose size shall be changed. - -[activateWindow](#activateWindow) - -[syncDraw](#syncDraw) - -[endDraw](#endDraw) - -[flushDraw](#flushDraw) - -3. Activate OnScreen Window - -![deactivate_window.png](parts/deactivate_window.png) - -[deactivateWindow](#deactivateWindow) - -[See sample code for more detail about OnScreen Window.](https://gerrit.automotivelinux.org/gerrit/gitweb?p=apps%2Fonscreenapp.git;a=summary) - -The above sequence shows the sample of OnScreen Window. -If the role is high priority than NormapApp, Window Manager rejects NormalApp -request when OnScreenApp is displayed. - -Note : Above repository is currently empty, so please refer to the sandbox branch. - -* * * - -## API reference - -### Request to Window Manager - -| Use | verb | version | -|:-:|:-:|:-:| -| Initialize | requestSurface | from 0.7 | -| | wm_subscribe | from 0.7 | -| | requestSurfaceXDG | from 0.7 | -|Activate/Deactivate| activateWindow | from 0.7 | -| | deactivateWindow | from 0.7 | -| | endDraw | from 0.7 | -| Change area size | changeAreaSize | from 0.8 | -| Get Infomation | getDisplayInfo | from 0.7 | -| | getAreaList | from 0.8 | - -Note: We created this table from 0.7 - -The data of IPC via websocket consists of JSON. -This section describes the verb of API and key. -Normally, the body of requesting API will be here. - -### Initialize - -#### *requestSurface* - -Register your role to Window Manager and get surfaceID for ivi-shell. The role is used for policy management. SurfaceID is supposed to be set to the API `ivi_application_surface_create` of ivi-application protocol or set it to environment variable `QT_IVI_SURFACE_ID` if your app is Qt and integrate ivi-shell. - -- verb : "requestSurface" -- argument : {"drawing_name":"your role"} - -the value must be selected in layers.json. - -argument example : - -```json -{ - "drawing_name" : "navigation" -} -``` - -#### *requestSurfaceXDG* - -This API is for XDGLauncher, so it is not necessary for normal application. -XDGLauncher is created for XDG application for desktop app without editing for HMI-Framework. -Please see the repository in detail. - - -#### *wm_subscribe* - -Subscribe the Window Manager's event. -Application must subscribe `syncDraw` event. - -- verb : "wm_subscribe" -- argument : {"event" : *event number*} - -argument example : - -```json -{ - "event" : 5 -} -``` - -The event is abstracted with a number (enumeration). - -| Number | Event | -|:-:|:-:| -| 0 | "active" | -| 1 | "inactive" | -| 2 | "visible" | -| 3 | "invisible" | -| 4 | "syncDraw" | -| 5 | "flushDraw" | -| 6 | "screenUpdated" | - -### Activate/Deactivate - -#### *activateWindow* - -Request to display your application with `role` on the `area` to Window Manager. -Window Manager checks the app should be visible on the `area` and change layout according to the policy table using `role` . -If it is accepted, afb_req_success will be returned, and next Window Manager -will push the event `syncDraw` to applications which will be displayed. -If it is denied, afb_req_fail will be returned. - -- verb : "activateWindow" -- argument : {"drawing_name" : "your role", "drawing_area" : "your area"} - -the value must be selected among layers.json. - -argument example : - -```json -{ - "drawing_name" : "navigation", - "drawing_area" : "normal.full" -} -``` - -#### *deactivateWindow* - -Request to hide your application to Window Manager. -This verb is supposed to be used by high priority application which -are for example popup application or system UI application such like alert. -If Window Manager set the priority of popup high in the policy, Window Manager may not hide the popup even if normal applications -send `activateWindow` until popup application send `deactivateWindow` . This behavior depends on the policy table. After this request, Window Manager checks which app should be visible and change layout according to the policy table. - -- verb : "deactivateWindow" -- argument : None - -#### *endDraw* - -Notify Window Manager of application finishes drawing. -This function must be sent in event `syncDraw`. -Otherwise, Window Manager will roll back to previous state and reject your request `activateWindow` . - -- verb : "endDraw" -- argument : {"drawing_name" : "your role"} - -argument example : - -```json -{ - "drawing_name" : "navigation", -} -``` - -#### *changeAreaSize* - -Request to change the size of area and location. Then Window Manager sends `syncDraw` to the applications whose size and location will be changed. -The caller has responsible of appearance of layouts. - -The use case of this function is shown in below. -The system application such like HomeScreen call this function, then the layout changes. The trigger may be user request on GUI, or system events and so on. - -![chnage_layout_img](parts/wm_change_layout.png) - -The sequence is below. - -![change_layout_sequnce](parts/change_layout_seq.png) - -- verb : "changeAreaSize" -- argument : {"areas" : [{"name":"area_name","rect":{"x":int,"y":int,"w":int,"h":int}, ...}]} - -Note: Only the application whose role is written in whitelist is allowed to call this API. This is because marcious application can change the layouts. The layout should be controled by system application. - -### Get Information - -#### *getDisplayInfo* - -Get screen information such as resolution. - -- verb : "getDisplayInfo" -- argument : None - -Return : The screen information will return. - -Return example : - -```json -{ - "response":{ - "width_pixel":1080, - "height_pixel":1920, - "width_mm":320, - "height_mm":520, - "scale":1 - }, - "jtype" : "afb-reply", - "request":{ - "status":"success", - "info":"success", - "uuid":"05ae219a-0e56-4f46-af9f-3186a18cb110" - } -} -``` - -Note : - -"width_mm", "height_mm" is from output which is one of the wayland object. -These items lack reliability, so recommend not to use. - -#### *getAreaList* - -Get area definition defined in areas.json. - -- verb : "getAreaList" -- argument : None - -Return : The area definition list. - -Return example : - -```json -{ - "response":{ - "areas":[ - { - "name":"on_screen", - "rect":{ - "x":0, - "y":218, - "w":1080, - "h":1488 - } - }, - { - "name":"restriction.split.sub", - "rect":{ - "x":0, - "y":962, - "w":1080, - "h":744 - } - } - ] - }, - "jtype":"afb-reply", - "request":{ - "status":"success", - "uuid":"0e6b8835-0df0-4a34-9718-125e6258b378" - } -} -``` - -### Event from Window Manager - -| Number | Event | version | -|:-:|:-:|:-:| -| 0 | "active" | from 0.7| -| 1 | "inactive" | from 0.7 | -| 2 | "visible" | from 0.7 | -| 3 | "invisible" | from 0.7 | -| 4 | "syncDraw" | from 0.7 | -| 5 | "flushDraw" | from 0.7 | -| 6 | "screenUpdated" | from 0.7 | - -Events also consists of JSON. -The data of event is contained in `data` such like - -```json -{ - "event":"windowmanager\/active", - "date":{ - "drawing_name":"navigation" - }, - "jtype":"afb-event" -} -``` - -"event" is the event name. -"data" is the data object from Window Manager and contains -the message of event. -This section describes "event" and the contents of "data". - -#### active - -This event means when the application becomes active state. - -example : - -```json -{ - "event":"windowmanager\/active", - "data":{ - "drawing_name":"launcher" - } - }, - "jtype":"afb-event" -} -``` - -#### inactive - -This event means when the application becomes inactive state. - -example : - -```json -{ - "event":"windowmanager\/inactive", - "data":{ - "drawing_name":"launcher" - } - }, - "jtype":"afb-event" -} -``` - -#### visible - -This event is issued when the application is visible state. - -example : - -```json -{ - "event":"windowmanager\/visible", - "data":{ - "drawing_name":"launcher" - } - }, - "jtype":"afb-event" -} -``` - -#### invisible - -This event is issued when the application is invisible state. - -example : - -```json -{ - "event":"windowmanager\/invisible", - "data":{ - "drawing_name":"launcher" - } - }, - "jtype":"afb-event" -} -``` - -#### syncDraw - -This event is issued by Window Manager state change operation in policy to the following cases. - -- Your app requested `activateWindow` then your application will be resized or visible. -- Other app requested `activateWindow` then your application will be resized or visible. -- Window Manager change layout due to vehicle condition. - -This event is the requests from Window Manager to - -- request your app to callback `endDraw` to Window Manager. -- request your app to resize and redraw according to "drawing_area". - -This is the abstract word then the real size is given in "drawing_rect". - -example : - -```json -{ - "event":"windowmanager\/syncDraw", - "data":{ - "drawing_name":"radio", - "drawing_area":"normal.full", - "drawing_rect":{ - "x":0, - "y":218, - "width":1080, - "height":1488 - } - }, - "jtype":"afb-event" -} -``` - -An application which gets this event must send `endDraw`. -For details, please see the sequence. - -#### flushDraw - -This event is issued after Window Manager receives all `endDraw` from applications who recieved `syncDraw` . After this event, Window Manager expects applications to update its surface. - -example : - -```json -{ - "event":"windowmanager\/flushDraw", - "data":{ - "drawing_name":"launcher" - } - }, - "jtype":"afb-event" -} -``` - -#### screenUpdated - -This event is issued after the visible application changes as a state transition change. This contains resized applications and visible applications. This event is issued to all subscriber. Typical usecase is only for HomeScreen. If HomeScreen has an animation until the started application is visible such as progress bar, this signal may become a switch to stop the animation. - -```json -{ - "event":"windowmanager\/screenUpdated", - "data":{ - "ids":[ - "mediaplayer", - "navi" - ] - }, - "jtype":"afb-event" -} -``` - -"ids" is the application_id described in config.xml of application. - -### Client library - -A client library implementation that internally uses the *libafbwsc*, is -provided in the `libwindowmanager`. -This library is for C++ native application. - -Regarding more detail, please refer to - -* * * - -## Sample code - -In order to enable application to activate application(render on layer), -above described steps need to be implemented. - -As a minimal example the usage and initialization can look like the -following. - -Typical implementation of C++ application. - -- Repo: `git clone https://gerrit.automotivelinux.org/gerrit/src/libhomescreen` - - Path: `sample/simple-egl/main.c` - -Typical implementation of Qt application. - -- Repo: `git clone https://gerrit.automotivelinux.org/gerrit/apps/radio` -- Repo: `git clone https://gerrit.automotivelinux.org/gerrit/apps/videoplayer` - -This is the good example to write more simply for Qt application using QtAGLExtras. - -## Policy Manager - -### Concepts - -Policy Manager decides next layout by using input event data and current state -based on the policy table. - -And PolicyManager is plugin for WindowManager. -Therefore the OEMs can replace it. - -### Enabling split - -Window Manager supports split layout to change policy and `areas.json`. -This section describes how to play split layout. The sample image is here. - -![example_split.png](parts/example_split.png) - -To play the split layout, - -1. Edit in `policy_manager/CMakeLists.txt` as follows: - -```cmake:policy_manager/CMakeList.txt - #set(STM_DIR stub) - set(STM_DIR zipc) -``` - -This results in using source code generated by ZIPC. - -1. Set bool value "ON" to TRY_SPLIT_LAYOUT at line 28 in policy_manager/CMakeLists.txt as follows: - set(TRY_SPLIT_LAYOUT ON CACHE BOOL "Enable to show split layout") -1. compile -1. copy window manager to your board -1. re-install windowmanager and reboot - -As a result, if application requests `navi` with `activateWindow` when current layout is `video` or `mediaplayer`, Window Manager change layout to split window. The reverse is true. - -Note: - -Currently, the policy manager force application change the size even if the application which has the role doesn't have the split design. In that case, the view of application may be ugly. Window Manager supposes that applications may have multi designs according to system design by OEM. For example, if OEM sets 2 pattern layout for `navi`, the application which requests `navi` should have 2 pattern designs. - -* * * - -## Release Note - -### version: 0.8 - -#### New Feature - -- Add Policy Manager - -### version: 0.7 - -#### New Features - -- Add API of getting area list and changing area size on runtime - -#### Changes - -- Reduce binary size to use ilmControl library. -- Change layer management. Client has one ivi-layer and can have multi surfaces. -- Stop conversion table which is compatible with old role to avoid complexity. -- Upgrade bindings v3. -- Add configuration file over-ride mechanism. - -#### Limitation - -- Only single-surface Qt applications are support through the - libwindowmanager library. This is a limitation of how Qt creates surface - IDs for the ivi-application interface. - -- Currenly, Window Manager supports only one screen. Dual display is not supported. -- As implemented in sample code, Qt application has to wait requesting `activateWindow` until `frameSwapped` is emitted. -- Qt application conceals, wayland and openGL processes, so it is difficult to call `swapBuffer` after `flushDraw` event described in the architecture document. But no problem if you use toolkit such as Qt, because it is automatically processed between applications and compositor(weston). -- Editing ZIPC is difficult for open source developer due to licence. diff --git a/docs/4_APIs_and_Services/4.7_HMI_Framework/4.7.3_Sound_Manager_Developer_Guide.md b/docs/4_APIs_and_Services/4.7_HMI_Framework/4.7.3_Sound_Manager_Developer_Guide.md deleted file mode 100644 index 2462f4d..0000000 --- a/docs/4_APIs_and_Services/4.7_HMI_Framework/4.7.3_Sound_Manager_Developer_Guide.md +++ /dev/null @@ -1,388 +0,0 @@ ---- -edit_link: '' -title: Sound Manager Developper Guide -origin_url: >- - https://git.automotivelinux.org/apps/agl-service-soundmanager/plain/doc/ApplicationGuide.md?h=master ---- - - - -# **Sound Manager Application Guide** - -
Revision: 0.3alpha
-
TOYOTA MOTOR CORPORATION
-
Advanced Driver Information Technology
-
11th/Dec/2017
- -* * * - -
- -## Table of content - -- [Target reader of this document](#Target\ reader\ of\ this\ document) -- [Overview](#Overview) -- [Getting Start](#Getting\ Start) - - [Supported environment](#Supported\ environment) - - [Build](#Build) - - [Configuring](#Configuring) - - [Additional work](#Additional\ work) - - [How to call Sound Manager's APIs from your Application?](#How\ to\ call\ Sound\ Manager\ APIs\ from\ your\ Application?) -- [Supported usecase](#Supported\ usecase) -- [Software Architecture](#Software\ Architecture) -- [API reference](#API\ reference) - - [APIs](#APIs) - - [Events](#Events) -- [Sequence](#Sequence) - - [StartUp](#StartUp) - - [Registration](#Registration) - - [Request Sound Right](#Request\ Sound\ Right) - - [Connect Sound Route](#Connect\ Sound\ Route) - - [Start Sound Streaming](#Start\ Sound\ Streaming) - - [Stop Sound Streaming](#Stop\ Sound\ Streaming) - - [Disconnect Sound Route](#Disconnect\ Sound\ Route) - - [Change Volume](#Change\ Volume) - - [Set Mute State](#Set\ Mute\ State) - - [Release Sound Right](#Release\ Sound\ Right) - - [Audio Domain](#Audio\ Domain) -- [Sample code](#Sample\ code) -- [Limitation](#Limitation) - -* * * - -
- -## Target reader of this document - -Application developer whose software uses sound output. - -* * * - -
- -## Overview - -The sound manager is the service which provides **sound-right management** for multiple sound sources. -This service is based on GENIVI Audio Manager, and this package contains service binding and library for API calling. -The reason why this service is based on GENIVI Audio Manager is because GENIVI Audio Manager supports highly strong and flexible sound-right management function. - -In order to understand, the below figure shows the one of typical usecases. -In this example, there are four sound mode. - -1. Audio Off -1. Media Player -1. Tel (Ring and talking) -1. TTS (Text To Speech; typically it's used by Navigation sound) - -![Figure: Typical usecase](parts/typical-usecase.png) - -The important points are: - -- **There is a priority for each sound source.** - In this example, the priority of "Tel" and "TTS" is higher than "MediaPlayer". Therefore when the system got incoming call, all four outputs of MediaPlayer are muted automatically by Sound Manager. And in this timing, Sound Manager will issue the event to Media Player, then Media Player can stop the music. (Because depending on OEM's requirement, "Stop" is required.) - "Tel" and "TTS" have the same priority. So if TTS event happened on talking, each sound will output from independent speaker. - If on-hook button is touched, Sound Manager will resume previous sound mode. In this example, basically it's MediaPlayer sound. But if TTS still playing, three speaker will output MediaPlayer sound but one speaker will continue to output TTS sound. -- **Sound mode transition should be done by Sound Manager not Applications.** - Actually application cannot recognize all sound source and its priority, so some centerized manager is required. Sound Manager provides this function. Sound Manager has a database for usecase and priority and in line with this policy Sound Manager controls proper sound mode. - -The below links show the example of Sound/Window mode transition. - -- [Single window application](Display_Audio_Transition1.html) - This transition assumes target IVI system support only one window on screen. It's a similar transition to CES2017 demo. -- [Dual window application](Display_Audio_Transition2.html) - This transition assumes target IVI system support two window (split screen) on screen. - -Of course user can customize shortcut menu, but since it's too many states so this example limits shortcut menu as "Home", "MediaPlayer", "HVAC" and "Navigation". - -* * * - -
- -## Getting Start - -
- -### Supported environment - -| Item | Description | -|:------------|:----------------------------------| -| AGL version | Electric Eel | -| Hardware | Renesas R-Car Starter Kit Pro(M3) | - -
- -### Build - -You can make Sound Manager object files by the following two stage operations. - -#### Download recipe - -If repo is already done, please start with git clone - -```bash -mkdir WORK -cd WORK -repo init -u https://gerrit.automotivelinux.org/gerrit/AGL/AGL-repo -repo sync -``` - -#### Bitbake - -```bash -source meta-agl/scripts/aglsetup.sh -m m3ulcb agl-demo agl-devel agl-appfw-smack agl-hmi-framework -bitbake agl-demo-platform -``` - -* * * - -
- -### Configuring - -To use Sound Manager API, an application shall paste the following configuration definition into "config.xml" of application. - -```xml - - - -``` - -* * * - -
- -### Additional work - -#### **Add Policy file** - -To add Sound Manager Domain into policy, put the following file to /etc/audiomanager/control on the target rootfs. - -`${SOUNDMANAGER_DIR}/conf/audiomanager-config-sample/configuration.xml` - -This is a sample configuration. - -#### **Remove Module router of Pulse Audio** - -Because the module rounter accesses Audio manager for getting sound right instead of application in CES2017, after you changed your application code for Sound manager, you shall modify the configuration for puluse audio not to load module router. -To do this, you shall comment out line.143 of /etc/pulse/default.pa on the target rootfs as below. - -```conf -.ifexists module-router.so -#load-module module-router -.endif -``` - -* * * - -
- -### How to call Sound Manager APIs from your Application? - -Sound Manager provides a library which is called "libsoundmanager". -This library provides function style API calling interface. So you can include libsoundmanager.hpp headerfile, and can link this library. -Please also refer sample application and template. - -See also our [Sample code](#Sample\ code). - -* * * - -
- -## Supported usecase - -1. Active source change -- When user choose different audio source with current one, IVI system stop or pause current source and activate new one. -- When user connect external device e.g. iPhone, USB memory IVI system change active source automatically to connected one. -2. Active source locking -- When user is in phone call, IVI restrict to change active source. -3. Interrupt source mixing -- When car close to cross road IVI system reduce the volume of current source and mix with interrupt source e.g. Navigation Guidance. -4. Volume change -- User can change the volume of active source or sink. -- When user change volume during interruption e.g. Navigation Guidance, IVI system change its volume temporary or permanently. -5. Mute/unmute -- User can mute/unmute current active source. -6. Volume management -- When user change active source, IVI system mute/unmute to avoid distortion of sound. -7. Volume acceleration -- When road noise is increased by speed, IVI system automatically change the volume of active source. -8. Routing sound -- System needs to route sound stream to proper zones. (driver zone, passenger zone, rear seat zone) - -[See also this page](https://wiki.automotivelinux.org/eg-ui-graphics-req-audiorouting) - -* * * - -
- -## Software Architecture - -The architecture of Sound Manager is shown below. -Sound Manager is the service designed to be used by multiple applications. -Therefore Sound Manager framework consists of two binder layers. Please refer the following figure. -The upper binder is for application side security context. The lower binder is for server side security context. -Usually an application side binder has some business logic for each application, so the number of binders depend on the number of applications which use Sound Manager. -On the other hand, regarding lower binder there is only one module in the system. This binder receives messages from multiple applications (in detail, it comes from upper layer binder). - -The communication protocols between libsoundmanager and upper binder, upper binder and lower binder, are WebSocket. The protocols between lower binder (soundmanager-binding) and AudioManager is D-Bus. - -![software-stack.png](parts/software-stack.png) - -* * * - -
- -## API reference - -"libsoundmanager" and "soundmanager_binding" provides several kinds of APIs, and these APIs basically correspond to GENIVI Audio Manager API. (Some APIs are Sound Manager original functions.) - -For understanding, GENIVI Audio Manager stands for one core module and three plug-ins. - -1. AudioManagerDaemon - This is a core module of Audio Manager. -2. AudioManagerCommandPlugin - This is a command interface for Audio Manager. -3. AudioManagerController - This plug-in can be used for sound-right management. -4. AudioManagerRountingPlugin - This plug-in abstracts the hardware and software. And sometimes there may be multiple plug-ins. - -*) [See also GENIVI AudioManager Components](http://docs.projects.genivi.org/AudioManager/audiomanagercomponentspage.html) - -![See also GENIVI AudioManager Components](parts/am-component.png) -(This figure was copied from GENIVI Web page.) - -
- -### APIs - -- init(int port, const std::string& token) -- registerSource(const std::string& sourceName) -- connect(int sourceID, int sinkID) -- connect(int sourceID, const std::string& sinkName) -- disconnect(int connectionID) -- ackSetSourceState(int handle, int err) -- registerCallback( void (*event_cb)(const std::string& event, struct json_object* event_contents), void (*reply_cb)(struct json_object* reply_contents), void (*hangup_cb)(void) = nullptr) - -Regarding more detail, please refer doxygen documents. - -
- -### Events - -"libsoundmanager" provides the feature which receives the events which an app subscribes with "subscribe" API. -An application can get events to register a callback function with "registerCallback" API. - -And this event is subscribed automatically. (See below Note) - -- asyncSetSourceState - -The below events are available but not mandatory. - -- newMainConnection -- removedMainConnection -- mainConnectionStateChanged -- volumeChanged -- sinkMuteStateChanged -- setRoutingReady -- asyncConnect -- asyncDisconnect - -Note: - -"asyncSetSourceState" is always subscribed in init phase because this is the most important event for audio policy management. This event indicates the approval/disapproval/pause. - -Regarding more detail, please refer doxygen documents. - -* * * - -
- -## Sequence -
- -### StartUp - -![seq_startup.png](parts/seq_startup.svg) - -
- -### Registration - -![seq_registration.png](parts/seq_registration.svg) - -
- -### Request Sound Right - -![seq_requestsoundmode.png](parts/seq_requestsoundmode.svg) - -
- -### Connect Sound Route -![seq_connectsoundroute.png](parts/seq_connectsoundroute.svg) - -
- -### Start Sound Streaming - -![seq_startsoundstreaming.png](parts/seq_startsoundstreaming.svg) - -
- -### Stop Sound Streaming - -![seq_stopsoundstreaming.png](parts/seq_stopsoundstreaming.svg) - -
- -### Disconnect Sound Route - -![seq_disconnectsoundroute.png](parts/seq_disconnectsoundroute.svg) - -
- -### Change Volume - -![seq_changevolume.png](parts/seq_changevolume.svg) - -
- -### Set Mute State - -![seq_setmutestate.png](parts/seq_setmutestate.svg) - -
- -### Release Sound Right - -![seq_releasesoundmode.png](parts/seq_releasesoundmode.svg) - -* * * - -
- -### Audio Domain - -One of the most important concept of Audio Manager is Audio Domain. -To use GENIVI Audio Manager based system, it may be better to understand this concept. -The below document should bring good understanding. - -[GENIVI Audio Manager: Generic Controller Plug-in](http://events.linuxfoundation.org/sites/events/files/slides/AGL_AMM_presentation_A01.pdf) - -Although strongly recommended to read whole pages, but you can get quick understanding by page.10 to 14. - -
- -## Sample code - -You can find samples using Sound Manager as below. - -- `apps/agl-service-homescreen-2017/sample/template` -- `apps/radio (branch=sandbox/knimitz/hmi-framework)` - -
- -## Limitation - -- Sound of application is not automatically muted for now because Audio Manager doesn't stop with current plugins. Just notify stop/pause/play. diff --git a/docs/4_APIs_and_Services/4.7_HMI_Framework/4.7.4_Sound_Manager_Developer_Guide_2.md b/docs/4_APIs_and_Services/4.7_HMI_Framework/4.7.4_Sound_Manager_Developer_Guide_2.md deleted file mode 100644 index 020b0d7..0000000 --- a/docs/4_APIs_and_Services/4.7_HMI_Framework/4.7.4_Sound_Manager_Developer_Guide_2.md +++ /dev/null @@ -1,133 +0,0 @@ ---- -edit_link: '' -title: Sound Manager Developper Guide 2 -origin_url: >- - https://git.automotivelinux.org/apps/agl-service-soundmanager/plain/doc/Display_Audio_Transition1.md?h=master ---- - - - -# Sound mode transition for single window application - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
StateEvent
State IDDisplayAudioPowerPush HomeScreen buttonStart BTAIncoming callPush Shortcut buttonTTSPush Phone control buttonSafety hazard
Win#1PopUpFLFRRLRROnOffMedia PlayerRadioNaviHVACPhoneOther buttonHomeMedia PlayerHVACNaviNavi INT TTSEndedRejectOff hookOn hookDetectedRecovered
S1--offoffoffoffS2--------------------
S2Home-offoffoffoff-S1S22S27S37S57S77S97S17S4-S22S57S37S3----S117-
S3Home-offTTSoffoff-S1S23S28S38S58S78S98S18S4-S23S58S38-S2---S117-
S4HomeRingingTeloffoffoff-S1------S19-------S2S5-S117-
S5Phone-Teloffoffoff-S1------S20--S25S60S40S6---S2S117-
S6Phone-TelTTSoffoff-S1------S21--S26S61S41-S5--S3S117-
S7Home-MPMPMPMP-S1S22S27S42S62S82S102S17S9-S22S62S42S8----S117-
S8Home-MPTTSMPMP-S1S23S28S43S63S83S103S18S9-S23S63S43-S7---S117-
S9HomeRingingTeloffoffoff-S1------S19-------S7S10-S117-
S10Phone-Teloffoffoff-S1------S20--S25S65S45S11---S7S117-
S11Phone-TelTTSoffoff-S1------S21--S26S66S46-S10--S8S117-
S12Home-RadioRadioRadioRadio-S1S22S27S47S67S87S107S17S14-S22S67S47S13----S117-
S13Home-RadioTTSRadioRadio-S1S23S28S48S68S88S108S18S14-S23S68S48-S12---S117-
S14HomeRingingTeloffoffoff-S1------S19-------S12S15-S117-
S15Phone-Teloffoffoff-S1------S20--S25S70S50S16---S12S117-
S16Phone-TelTTSoffoff-S1------S21--S26S71S51-S15--S13S117-
S17Home-BTABTABTABTA-S1S32S27S52S72S92S112S17S19-S32S72S52S18----S117-
S18Home-BTATTSBTABTA-S1S33S28S53S73S93S113S18S19-S33S73S53-S17---S117-
S19HomeRingingTeloffoffoff-S1------S19-------S17S20-S117-
S20Phone-Teloffoffoff-S1------S20--S35S75S55S21---S17S117-
S21Phone-TelTTSoffoff-S1------S21--S36S76S56-S20--S18S117-
S22MP-MPMPMPMP-S1------S32S24S7-S62S42S23---S117-
S23MP-MPTTSMPMP-S1------S33S24S8-S63S43-S22--S117-
S24MPRingingTeloffoffoff-S1------S34-------S22S25-S117-
S25Phone-Teloffoffoff-S1------S35-S10-S65S45S26---S22S117-
S26Phone-TelTTSoffoff-S1------S36-S11-S66S46-S25--S23S117-
S27Radio-RadioRadioRadioRadio-S1------S32S29S12S22S67S47S28---S117-
S28Radio-RadioTTSRadioRadio-S1------S33S29S13S23S68S48-S27--S117-
S29RadioRingingTeloffoffoff-S1------S34-------S27S30-S117-
S30Phone-Teloffoffoff-S1------S35-S15S25S70S50S31---S27S117-
S31Phone-TelTTSoffoff-S1------S36-S16S26S71S51-S30--S28S117-
S32MP(BTA)-BTABTABTABTA-S1-------S34S17-S72S52S33---S117-
S33MP(BTA)-BTATTSBTABTA-S1-------S34S18-S73S53-S32--S117-
S34MP(BTA)RingingTeloffoffoff-S1--------------S32S35-S117-
S35Phone-Teloffoffoff-S1--------S20-S75S55S36---S32S117-
S36Phone-TelTTSoffoff-S1--------S21-S76S56-S35--S33S117-
S37Navioffoffoffoff-S1------S52S39S2S22S57S37S38----S117-
S38NavioffTTSoffoff-S1------S53S39S3S23S58S38-S37---S117-
S39NaviRingingTeloffoffoff-S1------S54-------S37S40-S117-
S40Phone-Teloffoffoff-S1------S55-S5S25S60S40S41---S37S117-
S41Phone-TelTTSoffoff-S1------S56-S6S26S61S41-S40--S38S117-
S42Navi-MPMPMPMP-S1------S52S44S7S22S62-S43----S117-
S43Navi-MPTTSMPMP-S1------S53S44S8S23S63--S42---S117-
S44NaviRingingTeloffoffoff-S1------S54-------S42S45-S117-
S45Phone-Teloffoffoff-S1------S55-S10S25S65-S46---S42S117-
S46Phone-TelTTSoffoff-S1------S56-S11S26S66--S45--S43S117-
S47Navi-RadioRadioRadioRadio-S1------S52S49S12S22S67-S48----S117-
S48Navi-RadioTTSRadioRadio-S1------S53S49S13S23S68--S47---S117-
S49NaviRingingTeloffoffoff-S1------S54-------S47S50-S117-
S50Phone-Teloffoffoff-S1------S55-S15S25S70-S51---S47S117-
S51Phone-TelTTSoffoff-S1------S56-S16S26S71--S50--S48S117-
S52Navi-BTABTABTABTA-S1-------S54S17S32S72S52S53----S117-
S53Navi-BTATTSBTABTA-S1-------S54S18S33S73S53-S52---S117-
S54NaviRingingTeloffoffoff-S1--------------S52S55-S117-
S55Phone-Teloffoffoff-S1--------S20S35S75S55S56---S52S117-
S56Phone-TelTTSoffoff-S1--------S21S36S76S56-S55--S53S117-
S57HVACoffoffoffoff-S1------S72S59S2S22-S37S58----S117-
S58HVACoffTTSoffoff-S1------S73S59S3S23-S38-S57---S117-
S59HVACRingingTeloffoffoff-S1------S74-------S57S60-S117-
S60Phone-Teloffoffoff-S1------S75-S5S25-S40S61---S57S117-
S61Phone-TelTTSoffoff-S1------S76-S6S26-S41-S60--S58S117-
S62HVAC-MPMPMPMP-S1------S72S64S7S22-S42S63----S117-
S63HVAC-MPTTSMPMP-S1------S73S64S8S23-S43-S62---S117-
S64HVACRingingTeloffoffoff-S1------S74-------S62S65-S117-
S65Phone-Teloffoffoff-S1------S75-S10S25-S45S66---S62S117-
S66Phone-TelTTSoffoff-S1------S76-S11S26-S46-S65--S63S117-
S67HVAC-RadioRadioRadioRadio-S1------S72S69S12S22-S47S68----S117-
S68HVAC-RadioTTSRadioRadio-S1------S73S69S13S23-S48-S67---S117-
S69HVACRingingTeloffoffoff-S1------S74-------S67S70-S117-
S70Phone-Teloffoffoff-S1------S75-S15S25-S50S71---S67S117-
S71Phone-TelTTSoffoff-S1------S76-S16S26-S51-S70--S68S117-
S72HVAC-BTABTABTABTA-S1-------S74S17S32-S52S73----S117-
S73HVAC-BTATTSBTABTA-S1-------S74S18S33-S53-S72---S117-
S74HVACRingingTeloffoffoff-S1--------------S72S75-S117-
S75Phone-Teloffoffoff-S1--------S20S35-S55S76---S72S117-
S76Phone-TelTTSoffoff-S1--------S21S36-S56-S75--S73S117-
S77Phoneoffoffoffoff-S1------S92S79S2S22S57S37S78----S117-
S78PhoneoffTTSoffoff-S1------S93S79S3S23S58S38-S77---S117-
S79PhoneRingingTeloffoffoff-S1------S94-------S77S80-S117-
S80Phone-Teloffoffoff-S1------S95-S5S25S60S40S81---S77S117-
S81Phone-TelTTSoffoff-S1------S96-S6S26S61S41-S80--S78S117-
S82Phone-MPMPMPMP-S1------S92S84S7S22S62S42S83----S117-
S83Phone-MPTTSMPMP-S1------S93S84S8S23S63S43-S82---S117-
S84PhoneRingingTeloffoffoff-S1------S94-------S82S85-S117-
S85Phone-Teloffoffoff-S1------S95-S10S25S65S45S86---S82S117-
S86Phone-TelTTSoffoff-S1------S96-S11S26S66S46-S85--S83S117-
S87Phone-RadioRadioRadioRadio-S1------S92S89S12S22S67S47S88----S117-
S88Phone-RadioTTSRadioRadio-S1------S93S89S13S23S68S48-S87---S117-
S89PhoneRingingTeloffoffoff-S1------S94-------S87S90-S117-
S90Phone-Teloffoffoff-S1------S95-S15S25S70S50S91---S87S117-
S91Phone-TelTTSoffoff-S1------S96-S16S26S71S51-S90--S88S117-
S92Phone-BTABTABTABTA-S1-------S94S17S32S72S52S93----S117-
S93Phone-BTATTSBTABTA-S1-------S94S18S33S73S53-S92---S117-
S94PhoneRingingTeloffoffoff-S1--------------S92S95-S117-
S95Phone-Teloffoffoff-S1--------S20S35S75S55S96---S92S117-
S96Phone-TelTTSoffoff-S1--------S21S36S76S56-S95--S93S117-
S97Other-offoffoffoff-S1------S112S99S2S22S57S37S98----S117-
S98Other-offTTSoffoff-S1------S113S99S3S23S58S38-S97---S117-
S99OtherRingingTeloffoffoff-S1------S114-------S97S100-S117-
S100Other-Teloffoffoff-S1------S115-S5S25S60S40S101---S97S117-
S101Other-TelTTSoffoff-S1------S116-S6S26S61S41-S100--S98S117-
S102OtherMPMPMPMP-S1------S112S104S7S22S62S42S103----S117-
S103OtherMPTTSMPMP-S1------S113S104S8S23S63S43-S102---S117-
S104OtherRingingTeloffoffoff-S1------S114-------S102S105-S117-
S105Other-Teloffoffoff-S1------S115-S10S25S65S45S106---S102S117-
S106Other-TelTTSoffoff-S1------S116-S11S26S66S46-S105--S103S117-
S107Other-RadioRadioRadioRadio-S1------S112S109S12S22S67S47S108----S117-
S108Other-RadioTTSRadioRadio-S1------S113S109S13S23S68S48-S107---S117-
S109OtherRingingTeloffoffoff-S1------S114-------S107S110-S117-
S110Other-Teloffoffoff-S1------S115-S15S25S70S50S111---S107S117-
S111Other-TelTTSoffoff-S1------S116-S16S26S71S51-S110--S108S117-
S112Other-BTABTABTABTA-S1-------S114S17S32S72S52S113----S117-
S113Other-BTATTSBTABTA-S1-------S114S18S33S73S53-S112---S117-
S114OtherRingingTeloffoffoff-S1--------------S112S115-S117-
S115Other-Teloffoffoff-S1--------S20S35S75S55S116---S112S117-
S116Other-TelTTSoffoff-S1--------S21S36S76S56-S115--S113S117-
S117anyanyanyWarnanyany-S1------------------S(previous)
diff --git a/docs/4_APIs_and_Services/4.7_HMI_Framework/4.7.5_Sound_Manager_Developer_Guide_3.md b/docs/4_APIs_and_Services/4.7_HMI_Framework/4.7.5_Sound_Manager_Developer_Guide_3.md deleted file mode 100644 index 9c3e54e..0000000 --- a/docs/4_APIs_and_Services/4.7_HMI_Framework/4.7.5_Sound_Manager_Developer_Guide_3.md +++ /dev/null @@ -1,343 +0,0 @@ ---- -edit_link: '' -title: Sound Manager Developper Guide 3 -origin_url: >- - https://git.automotivelinux.org/apps/agl-service-soundmanager/plain/doc/Display_Audio_Transition2.md?h=master ---- - - - -# Sound mode transition for dual window application - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
StateEvent
State IDDisplayAudioPowerPush HomeScreen buttonStart BTAIncoming callPush Shortcut buttonTouchTTSPush Phone control buttonSafety hazard
Win#1Win#2PopUpFLFRRLRROnOffMedia PlayerRadioNaviHVACPhoneOther buttonHomeMedia PlayerHVACNaviWin#1Win#2Navi INT TTSEndedRejectOff hookOn hookDetectedRecovered
S1---offoffoffoffS2----------------------
S2Home--offoffoffoff-S1S22S27S37S57S77S97S17S4-S22S57S37--S3----S327-
S3Home--offTTSoffoff-S1S23S28S38S58S78S98S18S4-S23S58S38---S2---S327-
S4Home-RingingTeloffoffoff-S1------S19---------S2S5-S327-
S5Phone--Teloffoffoff-S1------S20--S25S60S40--S6---S2S327-
S6Phone--TelTTSoffoff-S1------S21--S26S61S41---S5--S3S327-
S7Home--MPMPMPMP-S1S22S27S42S62S82S102S17S9-S22S62S42--S8----S327-
S8Home--MPTTSMPMP-S1S23S28S43S63S83S103S18S9-S23S63S43---S7---S327-
S9Home-RingingTeloffoffoff-S1------S19---------S7S10-S327-
S10Phone--Teloffoffoff-S1------S20--S25S65S45--S11---S7S327-
S11Phone--TelTTSoffoff-S1------S21--S26S66S46---S10--S8S327-
S12Home--RadioRadioRadioRadio-S1S22S27S47S67S87S107S17S14-S22S67S47--S13----S327-
S13Home--RadioTTSRadioRadio-S1S23S28S48S68S88S108S18S14-S23S68S48---S12---S327-
S14Home-RingingTeloffoffoff-S1------S19---------S12S15-S327-
S15Phone--Teloffoffoff-S1------S20--S25S70S50--S16---S12S327-
S16Phone--TelTTSoffoff-S1------S21--S26S71S51---S15--S13S327-
S17Home--BTABTABTABTA-S1S32S27S52S72S92S112S17S19-S32S72S52--S18----S327-
S18Home--BTATTSBTABTA-S1S33S28S53S73S93S113S18S19-S33S73S53---S17---S327-
S19Home-RingingTeloffoffoff-S1------S19---------S17S20-S327-
S20Phone--Teloffoffoff-S1------S20--S35S75S55--S21---S17S327-
S21Phone--TelTTSoffoff-S1------S21--S36S76S56---S20--S18S327-
S22MP--MPMPMPMP-S1------S32S24S7-S117S122--S23---S327-
S23MP--MPTTSMPMP-S1------S33S24S8-S118S123---S22--S327-
S24MP-RingingTeloffoffoff-S1------S34---------S22S25-S327-
S25Phone--Teloffoffoff-S1------S35-S10-S120S125--S26---S22S327-
S26Phone--TelTTSoffoff-S1------S36-S11-S121S126---S25--S23S327-
S27Radio--RadioRadioRadioRadio-S1------S32S29S12S132S147S152--S28---S327-
S28Radio--RadioTTSRadioRadio-S1------S33S29S13S133S148S153---S27--S327-
S29Radio-RingingTeloffoffoff-S1------S34---------S27S30-S327-
S30Phone--Teloffoffoff-S1------S35-S15S135S150S155--S31---S27S327-
S31Phone--TelTTSoffoff-S1------S36-S16S136S151S156---S30--S28S327-
S32MP(BTA)--BTABTABTABTA-S1-------S34S17S32S157S162--S33---S327-
S33MP(BTA)--BTATTSBTABTA-S1-------S34S18S33S158S163---S32--S327-
S34MP(BTA)-RingingTeloffoffoff-S1----------------S32S35-S327-
S35Phone--Teloffoffoff-S1--------S20S35S160S165--S36---S32S327-
S36Phone--TelTTSoffoff-S1--------S21S36S161S166---S35--S33S327-
S37Navi-offoffoffoff-S1------S52S39S2S247S257S37--S38----S327-
S38Navi-offTTSoffoff-S1------S53S39S3S248S258S38---S37---S327-
S39Navi-RingingTeloffoffoff-S1------S54---------S37S40-S327-
S40Phone--Teloffoffoff-S1------S55-S5S250S260S40--S41---S37S327-
S41Phone--TelTTSoffoff-S1------S56-S6S251S261S41---S40--S38S327-
S42Navi--MPMPMPMP-S1------S52S44S7S247S262S42--S43----S327-
S43Navi--MPTTSMPMP-S1------S53S44S8S248S263S43---S42---S327-
S44Navi-RingingTeloffoffoff-S1------S54---------S42S45-S327-
S45Phone--Teloffoffoff-S1------S55-S10S250S265S45--S46---S42S327-
S46Phone--TelTTSoffoff-S1------S56-S11S251S266S46---S45--S43S327-
S47Navi--RadioRadioRadioRadio-S1------S52S49S12S247S267S47--S48----S327-
S48Navi--RadioTTSRadioRadio-S1------S53S49S13S248S268S48---S47---S327-
S49Navi-RingingTeloffoffoff-S1------S54---------S47S50-S327-
S50Phone--Teloffoffoff-S1------S55-S15S250S270S50--S51---S47S327-
S51Phone--TelTTSoffoff-S1------S56-S16S251S271S51---S50--S48S327-
S52Navi--BTABTABTABTA-S1-------S54S17S252S272S52--S53----S327-
S53Navi--BTATTSBTABTA-S1-------S54S18S253S273S53---S52---S327-
S54Navi-RingingTeloffoffoff-S1----------------S52S55-S327-
S55Phone--Teloffoffoff-S1--------S20S255S275S55--S56---S52S327-
S56Phone--TelTTSoffoff-S1--------S21S256S276S56---S55--S53S327-
S57HVAC-offoffoffoff-S1------S72S59S2S167S57S177--S58----S327-
S58HVAC-offTTSoffoff-S1------S73S59S3S168S58S178---S57---S327-
S59HVAC-RingingTeloffoffoff-S1------S74---------S57S60-S327-
S60Phone--Teloffoffoff-S1------S75-S5S170S60S177--S61---S57S327-
S61Phone--TelTTSoffoff-S1------S76-S6S171S61S178---S60--S58S327-
S62HVAC--MPMPMPMP-S1------S72S64S7S167S62S182--S63----S327-
S63HVAC--MPTTSMPMP-S1------S73S64S8S168S63S183---S62---S327-
S64HVAC-RingingTeloffoffoff-S1------S74---------S62S65-S327-
S65Phone--Teloffoffoff-S1------S75-S10S170S65S185--S66---S62S327-
S66Phone--TelTTSoffoff-S1------S76-S11S171S66S186---S65--S63S327-
S67HVAC--RadioRadioRadioRadio-S1------S72S69S12S167S67S187--S68----S327-
S68HVAC--RadioTTSRadioRadio-S1------S73S69S13S168S68S188---S67---S327-
S69HVAC-RingingTeloffoffoff-S1------S74---------S67S70-S327-
S70Phone--Teloffoffoff-S1------S75-S15S170S70S190--S71---S67S327-
S71Phone--TelTTSoffoff-S1------S76-S16S171S71S191---S70--S68S327-
S72HVAC--BTABTABTABTA-S1-------S74S17S172S72S192--S73----S327-
S73HVAC--BTATTSBTABTA-S1-------S74S18S173S73S193---S72---S327-
S74HVAC-RingingTeloffoffoff-S1----------------S72S75-S327-
S75Phone--Teloffoffoff-S1--------S20S175S75S195--S76---S72S327-
S76Phone--TelTTSoffoff-S1--------S21S176S76S196---S75--S73S327-
S77Phone-offoffoffoff-S1------S92S79S2S197S207S227--S78----S327-
S78Phone-offTTSoffoff-S1------S93S79S3S198S208S228---S77---S327-
S79Phone-RingingTeloffoffoff-S1------S94---------S77S80-S327-
S80Phone--Teloffoffoff-S1------S95-S5S200S210S230--S81---S77S327-
S81Phone--TelTTSoffoff-S1------S96-S6S201S211S231---S80--S78S327-
S82Phone--MPMPMPMP-S1------S92S84S7S197S212S232--S83----S327-
S83Phone--MPTTSMPMP-S1------S93S84S8S198S213S233---S82---S327-
S84Phone-RingingTeloffoffoff-S1------S94---------S82S85-S327-
S85Phone--Teloffoffoff-S1------S95-S10S200S215S235--S86---S82S327-
S86Phone--TelTTSoffoff-S1------S96-S11S201S216S236---S85--S83S327-
S87Phone--RadioRadioRadioRadio-S1------S92S89S12S197S217S237--S88----S327-
S88Phone--RadioTTSRadioRadio-S1------S93S89S13S198S218S238---S87---S327-
S89Phone-RingingTeloffoffoff-S1------S94---------S87S90-S327-
S90Phone--Teloffoffoff-S1------S95-S15S200S220S240--S91---S87S327-
S91Phone--TelTTSoffoff-S1------S96-S16S201S221S241---S90--S88S327-
S92Phone--BTABTABTABTA-S1-------S94S17S202S222S242--S93----S327-
S93Phone--BTATTSBTABTA-S1-------S94S18S203S223S243---S92---S327-
S94Phone-RingingTeloffoffoff-S1----------------S92S95-S327-
S95Phone--Teloffoffoff-S1--------S20S205S225S245--S96---S92S327-
S96Phone--TelTTSoffoff-S1--------S21S206S226S246---S95--S93S327-
S97Other--offoffoffoff-S1------S112S99S2S277S287S307--S98----S327-
S98Other--offTTSoffoff-S1------S113S99S3S278S288S308---S97---S327-
S99Other-RingingTeloffoffoff-S1------S114---------S97S100-S327-
S100Other--Teloffoffoff-S1------S115-S5S278S290S310--S101---S97S327-
S101Other--TelTTSoffoff-S1------S116-S6S278S291S311---S100--S98S327-
S102Other-MPMPMPMP-S1------S112S104S7S277S292S312--S103----S327-
S103Other-MPTTSMPMP-S1------S113S104S8S278S293S313---S102---S327-
S104Other-RingingTeloffoffoff-S1------S114---------S102S105-S327-
S105Other--Teloffoffoff-S1------S115-S10S278S295S315--S106---S102S327-
S106Other--TelTTSoffoff-S1------S116-S11S278S296S316---S105--S103S327-
S107Other--RadioRadioRadioRadio-S1------S112S109S12S277S297S317--S108----S327-
S108Other--RadioTTSRadioRadio-S1------S113S109S13S278S298S318---S107---S327-
S109Other-RingingTeloffoffoff-S1------S114---------S107S110-S327-
S110Other--Teloffoffoff-S1------S115-S15S278S300S320--S111---S107S327-
S111Other--TelTTSoffoff-S1------S116-S16S278S301S321---S110--S108S327-
S112Other--BTABTABTABTA-S1-------S114S17S282S302S322--S113----S327-
S113Other--BTATTSBTABTA-S1-------S114S18S283S303S323---S112---S327-
S114Other-RingingTeloffoffoff-S1----------------S112S115-S327-
S115Other--Teloffoffoff-S1--------S20S285S305S325--S116---S112S327-
S116Other--TelTTSoffoff-S1--------S21S286S306S326---S115--S113S327-
S117MPHVAC-MPMPMPMP-S1------S157S119S7--S122--S118----S327-
S118MPHVAC-MPTTSMPMP-S1------S158S119S8--S123---S117---S327-
S119MPHVACRingingTeloffoffoff-S1------S159---------S117S120-S327-
S120PhoneHVAC-Teloffoffoff-S1------S160-S10--S125--S121---S117S327-
S121PhoneHVAC-TelTTSoffoff-S1------S161-S11--S126---S120--S118S327-
S122MPNavi-MPMPMPMP-S1------S162S124S7-S117---S123----S327-
S123MPNavi-MPTTSMPMP-S1------S163S124S8-S118----S122---S327-
S124MPNaviRingingTeloffoffoff-S1------S164---------S122S125-S327-
S125PhoneNavi-Teloffoffoff-S1------S165-S10-S120---S126---S122S327-
S126PhoneNavi-Teloffoffoff-S1------S166-S11-S121----S125--S123S327-
S127RadioMP-RadioRadioRadioRadio-S1------S137S129S12S127S147S152-S132S128----S327-
S128RadioMP-RadioTTSRadioRadio-S1------S138S129S13S128S148S153-S133-S127---S327-
S129RadioMPRingingTeloffoffoff-S1------S139---------S127S130-S327-
S130PhoneMP-Teloffoffoff-S1------S140-S15S130S150S155-S135S131---S127S327-
S131PhoneMP-TelTTSoffoff-S1------S141-S16S131S151S156-S136-S130--S128S327-
S132RadioMP-MPMPMPMP-S1------S137S134S7S132S147S152S127-S133----S327-
S133RadioMP-MPTTSMPMP-S1------S138S134S8S133S148S153S128--S132---S327-
S134RadioMPRingingTeloffoffoff-S1------S139---------S132S135-S327-
S135PhoneMP-Teloffoffoff-S1------S140-S10S135S150S155S130-S136---S132S327-
S136PhoneMP-Teloffoffoff-S1------S141-S11S136S151S156S131--S135--S133S327-
S137RadioMP(BTA)-BTABTABTABTA-S1-------S139S17S137S147S152S142-S138----S327-
S138RadioMP(BTA)-BTATTSBTABTA-S1-------S139S18S138S148S153S143--S137---S327-
S139RadioMP(BTA)RingingTeloffoffoff-S1----------------S137S140-S327-
S140PhoneMP(BTA)-Teloffoffoff-S1--------S20S140S150S155S145-S141---S137S327-
S141PhoneMP(BTA)-TelTTSoffoff-S1--------S21S141S151S156S146--S140--S138S327-
S142RadioMP(BTA)-RadioRadioRadioRadio-S1-------S144S17S142S152S157-S137S143----S327-
S143RadioMP(BTA)-RadioTTSRadioRadio-S1-------S144S18S143S153S158-S138-S142---S327-
S144RadioMP(BTA)RingingTeloffoffoff-S1----------------S142S145-S327-
S145PhoneMP(BTA)-Teloffoffoff-S1--------S20S145S155S160-S140S146---S142S327-
S146PhoneMP(BTA)-TelTTSoffoff-S1--------S21S146S156S161-S141-S145--S143S327-
S147RadioHVAC-RadioRadioRadioRadio-S1------S157S149S12S132-S152--S148----S327-
S148RadioHVAC-RadioTTSRadioRadio-S1------S158S149S13S133-S153---S147---S327-
S149RadioHVACRingingTeloffoffoff-S1------S159---------S147S150-S327-
S150PhoneHVAC-Teloffoffoff-S1------S160-S15S135-S155--S151---S147S327-
S151PhoneHVAC-Teloffoffoff-S1------S161-S16S136-S156---S150--S148S327-
S152RadioNavi-RadioRadioRadioRadio-S1------S162S154S12S132S147---S153----S327-
S153RadioNavi-RadioTTSRadioRadio-S1------S163S154S13S133S148----S152---S327-
S154RadioNaviRingingTeloffoffoff-S1------S164---------S152S155-S327-
S155PhoneNavi-Teloffoffoff-S1------S165-S15S135S150---S156---S152S327-
S156PhoneNavi-Teloffoffoff-S1------S166-S16S136S151----S155--S153S327-
S157MP(BTA)HVAC-BTABTABTABTA-S1-------S159S17--S162--S158----S327-
S158MP(BTA)HVAC-BTATTSBTABTA-S1-------S159S18--S163---S157---S327-
S159MP(BTA)HVACRingingTeloffoffoff-S1----------------S157S160-S327-
S160PhoneHVAC-Teloffoffoff-S1--------S20--S165--S161---S157S327-
S161PhoneHVAC-Teloffoffoff-S1--------S21--S166---S160--S158S327-
S162MP(BTA)Navi-BTABTABTABTA-S1-------S164S17-S157---S163----S327-
S163MP(BTA)Navi-BTATTSBTABTA-S1-------S164S18-S158----S162---S327-
S164MP(BTA)NaviRingingTeloffoffoff-S1----------------S162S165-S327-
S165PhoneNavi-Teloffoffoff-S1--------S20-S160---S166---S162S327-
S166PhoneNavi-Teloffoffoff-S1--------S21-S161----S165--S163S327-
S167HVACMP-MPMPMPMP-S1------S172S169S7--S182--S168----S327-
S168HVACMP-MPTTSMPMP-S1------S173S169S8--S183---S167---S327-
S169HVACMPRingingTeloffoffoff-S1------S174---------S167S170-S327-
S170PhoneMP-Teloffoffoff-S1------S175-S10--S183--S171---S167S327-
S171PhoneMP-TelTTSoffoff-S1------S176-S11--S183---S170--S168S327-
S172HVACMP(BTA)-BTABTABTABTA-S1-------S174S17--S192--S173----S327-
S173HVACMP(BTA)-BTATTSBTABTA-S1-------S174S18--S193---S172---S327-
S174HVACMP(BTA)RingingTeloffoffoff-S1----------------S172S175-S327-
S175PhoneMP(BTA)-Teloffoffoff-S1--------S20--S195--S176---S172S327-
S176PhoneMP(BTA)-TelTTSoffoff-S1--------S21--S196---S175--S173S327-
S177HVACNavi-offoffoffoff-S1------S192S179S2S167----S178----S327-
S178HVACNavi-offTTSoffoff-S1------S193S179S3S167-----S177---S327-
S179HVACNaviRingingTeloffoffoff-S1------S194---------S177S180-S327-
S180PhoneNavi-Teloffoffoff-S1------S195-S20S170----S181---S177S327-
S181PhoneNavi-TelTTSoffoff-S1------S196-S21S171-----S180--S178S327-
S182HVACNavi-MPMPMPMP-S1------S192S184S7S167----S183----S327-
S183HVACNavi-MPTTSMPMP-S1------S193S184S8S167-----S182---S327-
S184HVACNaviRingingTeloffoffoff-S1------S194---------S182S185-S327-
S185PhoneNavi-Teloffoffoff-S1------S195-S10S170----S186---S182S327-
S186PhoneNavi-TelTTSoffoff-S1------S196-S11S171-----S185--S183S327-
S187HVACNavi-RadioRadioRadioRadio-S1------S192S189S12S167----S188----S327-
S188HVACNavi-RadioTTSRadioRadio-S1------S193S189S13S167-----S187---S327-
S189HVACNaviRingingTeloffoffoff-S1------S194---------S187S190-S327-
S190PhoneNavi-Teloffoffoff-S1------S195-S15S170----S191---S187S327-
S191PhoneNavi-TelTTSoffoff-S1------S196-S16S171-----S190--S188S327-
S192HVACNavi-BTABTABTABTA-S1-------S194S17S172----S193----S327-
S193HVACNavi-BTATTSBTABTA-S1-------S194S18S173-----S192---S327-
S194HVACNaviRingingTeloffoffoff-S1----------------S192S195-S327-
S195PhoneNavi-Teloffoffoff-S1--------S20S175----S196---S192S327-
S196PhoneNavi-TelTTSoffoff-S1--------S21S176-----S195--S193S327-
S197PhoneMPMPMPMPMP-S1------S202S199S7-S212S232--S198----S327-
S198PhoneMPMPTTSMPMP-S1------S203S199S8-S213S233---S197---S327-
S199PhoneMPRingingTeloffoffoff-S1------S204---------S197S200-S327-
S200PhoneMP-Teloffoffoff-S1------S205-S10-S215S235--S201---S197S327-
S201PhoneMP-TelTTSoffoff-S1------S206-S11-S216S236---S200--S198S327-
S202PhoneMP(BTA)-BTABTABTABTA-S1-------S204S17-S222S242--S203----S327-
S203PhoneMP(BTA)-BTATTSBTABTA-S1-------S204S18-S223S243---S202---S327-
S204PhoneMP(BTA)RingingTeloffoffoff-S1----------------S202S205-S327-
S205PhoneMP(BTA)-Teloffoffoff-S1--------S20-S225S245--S206---S202S327-
S206PhoneMP(BTA)-TelTTSoffoff-S1--------S21-S226S246---S205--S203S327-
S207PhoneHVAC-offoffoffoff-S1------S222S209S2S197-S227--S208----S327-
S208PhoneHVAC-offTTSoffoff-S1------S223S209S3S198-S228---S207---S327-
S209PhoneHVACRingingTeloffoffoff-S1------S224---------S207S210-S327-
S210PhoneHVAC-Teloffoffoff-S1------S225-S20S200-S230--S211---S207S327-
S211PhoneHVAC-TelTTSoffoff-S1------S226-S21S201-S231---S210--S208S327-
S212PhoneHVACMPMPMPMP-S1------S222S214S7S197-S232--S213----S327-
S213PhoneHVACMPTTSMPMP-S1------S223S214S8S198-S233---S212---S327-
S214PhoneHVACRingingTeloffoffoff-S1------S224---------S212S215-S327-
S215PhoneHVAC-Teloffoffoff-S1------S225-S10S200-S235--S216---S212S327-
S216PhoneHVAC-TelTTSoffoff-S1------S226-S11S201-S236---S215--S213S327-
S217PhoneHVAC-RadioRadioRadioRadio-S1------S222S219S12S197-S237--S218----S327-
S218PhoneHVAC-RadioTTSRadioRadio-S1------S223S219S13S198-S238---S217---S327-
S219PhoneHVACRingingTeloffoffoff-S1------S224---------S217S220-S327-
S220PhoneHVAC-Teloffoffoff-S1------S225-S15S200-S240--S221---S217S327-
S221PhoneHVAC-TelTTSoffoff-S1------S226-S16S201-S241---S220--S218S327-
S222PhoneHVAC-BTABTABTABTA-S1-------S224S17S202-S242--S223----S327-
S223PhoneHVAC-BTATTSBTABTA-S1-------S224S18S203-S243---S222---S327-
S224PhoneHVACRingingTeloffoffoff-S1----------------S222S225-S327-
S225PhoneHVAC-Teloffoffoff-S1--------S20S205-S245--S226---S222S327-
S226PhoneHVAC-TelTTSoffoff-S1--------S21S206-S246---S225--S223S327-
S227PhoneNavi-offoffoffoff-S1------S242S229S2S197S207---S228----S327-
S228PhoneNavi-offTTSoffoff-S1------S243S229S3S198S208----S227---S327-
S229PhoneNaviRingingTeloffoffoff-S1------S244---------S227S230-S327-
S230PhoneNavi-Teloffoffoff-S1------S245-S20S200S210---S231---S227S327-
S231PhoneNavi-TelTTSoffoff-S1------S246-S21S201S211----S230--S228S327-
S232PhoneNaviMPMPMPMP-S1------S242S234S7S197S212---S233----S327-
S233PhoneNaviMPTTSMPMP-S1------S243S234S8S198S213----S232---S327-
S234PhoneNaviRingingTeloffoffoff-S1------S244---------S232S235-S327-
S235PhoneNavi-Teloffoffoff-S1------S245-S10S200S215---S236---S232S327-
S236PhoneNavi-TelTTSoffoff-S1------S246-S11S201S216----S235--S233S327-
S237PhoneNavi-RadioRadioRadioRadio-S1------S242S239S12S197S217---S238----S327-
S238PhoneNavi-RadioTTSRadioRadio-S1------S243S239S13S198S218----S237---S327-
S239PhoneNaviRingingTeloffoffoff-S1------S244---------S237S240-S327-
S240PhoneNavi-Teloffoffoff-S1------S245-S15S200S220---S241---S237S327-
S241PhoneNavi-TelTTSoffoff-S1------S246-S16S201S221----S240--S238S327-
S242PhoneNavi-BTABTABTABTA-S1-------S244S17S202S222---S243----S327-
S243PhoneNavi-BTATTSBTABTA-S1-------S244S18S203S223----S242---S327-
S244PhoneNaviRingingTeloffoffoff-S1----------------S242S245-S327-
S245PhoneNavi-Teloffoffoff-S1--------S20S205S225---S246---S242S327-
S246PhoneNavi-TelTTSoffoff-S1--------S21S206S226----S245--S243S327-
S247NaviMP-MPMPMPMP-S1------S252S249S7-S262---S248----S327-
S248NaviMP-MPTTSMPMP-S1------S253S249S8-S263----S247---S327-
S249NaviMPRingingTeloffoffoff-S1------S254---------S247S248-S327-
S250PhoneMP-Teloffoffoff-S1------S255-S10-S265---S251---S247S327-
S251PhoneMP-TelTTSoffoff-S1------S256-S11-S266----S250--S248S327-
S252NaviMP(BTA)-BTABTABTABTA-S1-------S254S17-S272---S253----S327-
S253NaviMP(BTA)-BTATTSBTABTA-S1-------S254S18-S273----S252---S327-
S254NaviMP(BTA)RingingTeloffoffoff-S1----------------S252S253-S327-
S255PhoneMP(BTA)-Teloffoffoff-S1--------S20-S275---S256---S252S327-
S256PhoneMP(BTA)-TelTTSoffoff-S1--------S21-S276----S255--S253S327-
S257NaviHVAC-offoffoffoff-S1------S272S259S2S247----S258----S327-
S258NaviHVAC-offTTSoffoff-S1------S273S259S3S248-----S257---S327-
S259NaviHVACRingingTeloffoffoff-S1------S274---------S257S260-S327-
S260PhoneHVAC-Teloffoffoff-S1------S275-S20S250----S261---S257S327-
S261PhoneHVAC-TelTTSoffoff-S1------S276-S21S251-----S260--S258S327-
S262NaviHVAC-MPMPMPMP-S1------S272S264S7S247----S263----S327-
S263NaviHVAC-MPTTSMPMP-S1------S273S264S8S248-----S262---S327-
S264NaviHVACRingingTeloffoffoff-S1------S274---------S262S265-S327-
S265PhoneHVAC-Teloffoffoff-S1------S275-S10S250----S266---S262S327-
S266PhoneHVAC-TelTTSoffoff-S1------S276-S11S251-----S265--S263S327-
S267NaviHVAC-RadioRadioRadioRadio-S1------S272S269S12S247----S268----S327-
S268NaviHVAC-RadioTTSRadioRadio-S1------S273S269S13S248-----S267---S327-
S269NaviHVACRingingTeloffoffoff-S1------S274---------S267S270-S327-
S270PhoneHVAC-Teloffoffoff-S1------S275-S15S250----S271---S267S327-
S271PhoneHVAC-TelTTSoffoff-S1------S276-S16S251-----S270--S268S327-
S272NaviHVAC-BTABTABTABTA-S1-------S274S17S252----S273----S327-
S273NaviHVAC-BTATTSBTABTA-S1-------S274S18S253-----S272---S327-
S274NaviHVACRingingTeloffoffoff-S1----------------S272S275-S327-
S275PhoneHVAC-Teloffoffoff-S1--------S20S255----S276---S272S327-
S276PhoneHVAC-TelTTSoffoff-S1--------S21S256-----S275--S273S327-
S277OtherMP-MPMPMPMP-S1------S282S279S7-S292S312--S278----S327-
S278OtherMP-MPTTSMPMP-S1------S283S279S8-S293S313---S277---S327-
S279OtherMPRingingTeloffoffoff-S1------S284---------S277S280-S327-
S280PhoneMP-Teloffoffoff-S1------S285-S10-S295S317--S281---S277S327-
S281PhoneMP-TelTTSoffoff-S1------S286-S11-S296S318---S280--S278S327-
S282OtherMP(BTA)-BTABTABTABTA-S1-------S284S12-S302S322--S283----S327-
S283OtherMP(BTA)-BTATTSBTABTA-S1-------S284S13-S303S323---S282---S327-
S284OtherMP(BTA)RingingTeloffoffoff-S1----------------S282S285-S327-
S285PhoneMP(BTA)-Teloffoffoff-S1--------S20-S305S325--S286---S282S327-
S286PhoneMP(BTA)-TelTTSoffoff-S1--------S21-S306S326---S285--S283S327-
S287OtherHVAC-offoffoffoff-S1------S302S289S2S277-S307--S288----S327-
S288OtherHVAC-offTTSoffoff-S1------S303S289S3S278-S308---S287---S327-
S289OtherHVACRingingTeloffoffoff-S1------S304---------S287S290-S327-
S290PhoneHVAC-Teloffoffoff-S1------S305-S20S280-S310--S291---S287S327-
S291PhoneHVAC-TelTTSoffoff-S1------S306-S21S281-S311---S290--S288S327-
S292OtherHVAC-MPMPMPMP-S1------S302S294S7S277-S312--S293----S327-
S293OtherHVAC-MPTTSMPMP-S1------S303S294S8S278-S313---S292---S327-
S294OtherHVACRingingTeloffoffoff-S1------S304---------S292S295-S327-
S295PhoneHVAC-Teloffoffoff-S1------S305-S10S278-S315--S296---S292S327-
S296PhoneHVAC-TelTTSoffoff-S1------S306-S11S278-S316---S295--S293S327-
S297OtherHVAC-RadioRadioRadioRadio-S1------S302S299S12S277-S317--S298----S327-
S298OtherHVAC-RadioTTSRadioRadio-S1------S303S299S13S278-S318---S297---S327-
S299OtherHVACRingingTeloffoffoff-S1------S304---------S297S300-S327-
S300PhoneHVAC-Teloffoffoff-S1------S305-S15S280-S320--S301---S297S327-
S301PhoneHVAC-TelTTSoffoff-S1------S306-S16S281-S321---S300--S298S327-
S302OtherHVAC-BTABTABTABTA-S1-------S304S17S282-S322--S303----S327-
S303OtherHVAC-BTATTSBTABTA-S1-------S304S18S283-S323---S302---S327-
S304OtherHVACRingingTeloffoffoff-S1----------------S302S305-S327-
S305PhoneHVAC-Teloffoffoff-S1--------S20S285-S325--S306---S302S327-
S306PhoneHVAC-TelTTSoffoff-S1--------S21S286-S326---S305--S303S327-
S307OtherNavi-offoffoffoff-S1------S322S309S2S287S287---S308----S327-
S308OtherNavi-offTTSoffoff-S1------S323S309S3S288S288----S307---S327-
S309OtherNaviRingingTeloffoffoff-S1------S324---------S307S310-S327-
S310PhoneNavi-Teloffoffoff-S1------S325-S20S290S290---S311---S307S327-
S311PhoneNavi-TelTTSoffoff-S1------S326-S21S291S291----S310--S308S327-
S312OtherNavi-MPMPMPMP-S1------S322S314S7S292S292---S313----S327-
S313OtherNavi-MPTTSMPMP-S1------S323S314S8S293S293----S312---S327-
S314OtherNaviRingingTeloffoffoff-S1------S324---------S312S315-S327-
S315PhoneNavi-Teloffoffoff-S1------S325-S10S295S295---S316---S312S327-
S316PhoneNavi-TelTTSoffoff-S1------S326-S11S296S296----S315--S313S327-
S317OtherNavi-RadioRadioRadioRadio-S1------S322S319S12S297S297---S318----S327-
S318OtherNavi-RadioTTSRadioRadio-S1------S323S319S13S298S298----S317---S327-
S319OtherNaviRingingTeloffoffoff-S1------S324---------S317S320-S327-
S320PhoneNavi-Teloffoffoff-S1------S325-S15S300S300---S321---S317S327-
S321PhoneNavi-TelTTSoffoff-S1------S326-S16S301S301----S320--S318S327-
S322OtherNavi-BTABTABTABTA-S1-------S324S17S282S302---S323----S327-
S323OtherNavi-BTATTSBTABTA-S1-------S324S18S283S303----S322---S327-
S324OtherNaviRingingTeloffoffoff-S1----------------S322S325-S327-
S325PhoneNavi-Teloffoffoff-S1--------S20S285S305---S326---S322S327-
S326PhoneNavi-TelTTSoffoff-S1--------S21S286S306----S325--S323S327-
S327anyanyanyanyWarnanyany-S1--------------------S(previous)
diff --git a/docs/4_APIs_and_Services/4.7_HMI_Framework/parts/am-component.png b/docs/4_APIs_and_Services/4.7_HMI_Framework/parts/am-component.png deleted file mode 100644 index bf068bb..0000000 Binary files a/docs/4_APIs_and_Services/4.7_HMI_Framework/parts/am-component.png and /dev/null differ diff --git a/docs/4_APIs_and_Services/4.7_HMI_Framework/parts/change_layout_seq.png b/docs/4_APIs_and_Services/4.7_HMI_Framework/parts/change_layout_seq.png deleted file mode 100644 index 6895cfa..0000000 Binary files a/docs/4_APIs_and_Services/4.7_HMI_Framework/parts/change_layout_seq.png and /dev/null differ diff --git a/docs/4_APIs_and_Services/4.7_HMI_Framework/parts/deactivate_window.png b/docs/4_APIs_and_Services/4.7_HMI_Framework/parts/deactivate_window.png deleted file mode 100644 index cd0d48c..0000000 Binary files a/docs/4_APIs_and_Services/4.7_HMI_Framework/parts/deactivate_window.png and /dev/null differ diff --git a/docs/4_APIs_and_Services/4.7_HMI_Framework/parts/example_split.png b/docs/4_APIs_and_Services/4.7_HMI_Framework/parts/example_split.png deleted file mode 100644 index e9fd476..0000000 Binary files a/docs/4_APIs_and_Services/4.7_HMI_Framework/parts/example_split.png and /dev/null differ diff --git a/docs/4_APIs_and_Services/4.7_HMI_Framework/parts/hmi_framework_designed_seq_toyota.png b/docs/4_APIs_and_Services/4.7_HMI_Framework/parts/hmi_framework_designed_seq_toyota.png deleted file mode 100644 index 2dedabf..0000000 Binary files a/docs/4_APIs_and_Services/4.7_HMI_Framework/parts/hmi_framework_designed_seq_toyota.png and /dev/null differ diff --git a/docs/4_APIs_and_Services/4.7_HMI_Framework/parts/initialize-set-event-handler.svg b/docs/4_APIs_and_Services/4.7_HMI_Framework/parts/initialize-set-event-handler.svg deleted file mode 100644 index bd7fcfc..0000000 --- a/docs/4_APIs_and_Services/4.7_HMI_Framework/parts/initialize-set-event-handler.svg +++ /dev/null @@ -1,32 +0,0 @@ -Application initialization phase (ex. set_event_handler)AppAppHomeScreenBinderHomeScreenBinderHomeScreenGUIHomeScreenGUIinit(port, token)set_event_handler()setup event handler the App wishes to receive・LibHomeScreen::Event_ShowWindow・LibHomeScreen::Event_HideWindow・LibHomeScreen::Event_ReplyShowWindow \ No newline at end of file diff --git a/docs/4_APIs_and_Services/4.7_HMI_Framework/parts/on_screen_message.svg b/docs/4_APIs_and_Services/4.7_HMI_Framework/parts/on_screen_message.svg deleted file mode 100644 index 66ceed3..0000000 --- a/docs/4_APIs_and_Services/4.7_HMI_Framework/parts/on_screen_message.svg +++ /dev/null @@ -1,36 +0,0 @@ -Application Callback Event On Screen Message / Reply phaseAppAppHomeScreenBinderHomeScreenBinderHomeScreenGUIHomeScreenGUIset_event_handler()LibHomeScreen::Event_OnScreenMessageset_event_handler()LibHomeScreen::Event_OnScreenReplyonScreenMessage(display_message)event_handler(display_message)onScreenReply(reply_message)event_handler(reply_message) \ No newline at end of file diff --git a/docs/4_APIs_and_Services/4.7_HMI_Framework/parts/request_role.png b/docs/4_APIs_and_Services/4.7_HMI_Framework/parts/request_role.png deleted file mode 100644 index ca20678..0000000 Binary files a/docs/4_APIs_and_Services/4.7_HMI_Framework/parts/request_role.png and /dev/null differ diff --git a/docs/4_APIs_and_Services/4.7_HMI_Framework/parts/seq_changevolume.svg b/docs/4_APIs_and_Services/4.7_HMI_Framework/parts/seq_changevolume.svg deleted file mode 100644 index 9f60795..0000000 --- a/docs/4_APIs_and_Services/4.7_HMI_Framework/parts/seq_changevolume.svg +++ /dev/null @@ -1,117 +0,0 @@ -CommandPlugInAudio Manager DaemonRoutingPlugInApplicationSoundManagerIAmCommandSendIAmCommandReceiverAudioManagerIAmRoutingReceiveIAmRoutingSendAudio DomainSetVolume()SetVolume()SetVolume()asyncSetSinkVolume()SetVolume()ackSetVolume()ackSetVolumeChange()cbVolumeChangedsignal("volumeChanged")event [volumeChanged] \ No newline at end of file diff --git a/docs/4_APIs_and_Services/4.7_HMI_Framework/parts/seq_connectsoundroute.svg b/docs/4_APIs_and_Services/4.7_HMI_Framework/parts/seq_connectsoundroute.svg deleted file mode 100644 index a3c392a..0000000 --- a/docs/4_APIs_and_Services/4.7_HMI_Framework/parts/seq_connectsoundroute.svg +++ /dev/null @@ -1,145 +0,0 @@ -CommandPlugInAudio Manager DaemonRoutingPlugInApplicationSoundManagerIAmCommandSendIAmCommandReceiverAudioManagerIAmRoutingReceiveIAmRoutingSendAudio DomaincbMainConnectionStateChanged(CS_CONNECTING)signal("MmainConnectionChanged (CS_CONECTING)")event [mainConnectionChanged (CS_CONECTING)]Audio Manager Policy decides this mainconnection have to be established.At the beginning of sequence Audio Managershould inform cbMainConnectionStateChanged(CS_CONNECTING) to indicated pre-informationof establishment.asyncConnect()asyncConnect()setAudioMode()ackConnect()ackConnect()asyncConnect()Audio Manager have to know that Applicationcertainly start preparing sound route, and waitproceeding until Application return feedback.Main reason is to make sure that entire sound routeis established before connection state transite tonext phase. Otherwise it is possible for Application toface the problem that ALSA virtual device cannot beopened after connection state is changed.asyncConnect()event [asyncConnect]ackConnect()cbMainConnectionStateChanged(CS_SUSPENDED) \ No newline at end of file diff --git a/docs/4_APIs_and_Services/4.7_HMI_Framework/parts/seq_disconnectsoundroute.svg b/docs/4_APIs_and_Services/4.7_HMI_Framework/parts/seq_disconnectsoundroute.svg deleted file mode 100644 index 9036aca..0000000 --- a/docs/4_APIs_and_Services/4.7_HMI_Framework/parts/seq_disconnectsoundroute.svg +++ /dev/null @@ -1,110 +0,0 @@ -CommandPlugInAudio Manager DaemonRoutingPlugInApplicationSoundManagerIAmCommandSendIAmCommandReceiverAudioManagerIAmRoutingReceiveIAmRoutingSendAudio DomainasyncDisconnect()asyncDisconnect()event [asyncDisconnect]ackDisconnect()ackDisconnect()asyncDisconnect()asyncDisconnect()disconnect()ackDisconnect()cbMainConnectionStateChanged(CS_DISCONNECTED) \ No newline at end of file diff --git a/docs/4_APIs_and_Services/4.7_HMI_Framework/parts/seq_registration.svg b/docs/4_APIs_and_Services/4.7_HMI_Framework/parts/seq_registration.svg deleted file mode 100644 index 9bff665..0000000 --- a/docs/4_APIs_and_Services/4.7_HMI_Framework/parts/seq_registration.svg +++ /dev/null @@ -1,235 +0,0 @@ -CommandPlugInAudio Manager DaemonRoutingPlugInApplicationSoundManagerIAmCommandSendIAmCommandReceiverAudioManagerIAmRoutingReceiveIAmRoutingSendAudio Domainalt[Domain Type = DSP/Amplifier]registerDomain()registerDomain()[Domain Type = SoundManager]registerDomain()registerDomain()alt[Register Type = Dynamic]registerSource()registerSource()registerSource()[Register Type = Static]registerSourcecbNewSource()signal("NewSource")event [newSource]alt[Register Type = Dynamic]registerSink()registerSink()[Register Type = Static]registerSinkcbNewSink()signal("NewSink")event [newSink]alt[Register Type = Dynamic]registerGateway()registerGateway()[Register Type = Static]registerGatewayhookDomainRegistrationCompelte()hookDomainRegistrationCompelte() \ No newline at end of file diff --git a/docs/4_APIs_and_Services/4.7_HMI_Framework/parts/seq_releasesoundmode.svg b/docs/4_APIs_and_Services/4.7_HMI_Framework/parts/seq_releasesoundmode.svg deleted file mode 100644 index cbe1fa0..0000000 --- a/docs/4_APIs_and_Services/4.7_HMI_Framework/parts/seq_releasesoundmode.svg +++ /dev/null @@ -1,119 +0,0 @@ -CommandPlugInAudio Manager DaemonRoutingPlugInApplicationSoundManagerIAmCommandSendIAmCommandReceiverAudioManagerIAmRoutingReceiveIAmRoutingSendAudio Domaindisconnect()disconnect()disconnect()opt[Main connection is existing]alt[MainConnectioState = CS_SUSPENDED]refDisconnect Sound Route[CS_CONNECTED]refStop Sound StreamingrefDisconnect Sound RoutecbMainConnectionStateChanged()signal("MainConnectionStateChanged")event [mainConnectionStateChanged]cbRemoveMainConnection()signal("RemoveMainConnection")event [removeMainConnection] \ No newline at end of file diff --git a/docs/4_APIs_and_Services/4.7_HMI_Framework/parts/seq_requestsoundmode.svg b/docs/4_APIs_and_Services/4.7_HMI_Framework/parts/seq_requestsoundmode.svg deleted file mode 100644 index 5ea9616..0000000 --- a/docs/4_APIs_and_Services/4.7_HMI_Framework/parts/seq_requestsoundmode.svg +++ /dev/null @@ -1,165 +0,0 @@ -CommandPlugInAudio Manager DaemonRoutingPlugInApplicationSoundManagerIAmCommandSendIAmCommandReceiverAudioManagerIAmRoutingReceiveIAmRoutingSendAudio Domainconnect()connect()connect()Please note that if same connection(source and sink are completely same)has bee created already, Audio Managerdoes not notify cbNewMainConnection()opt[main connection is not existing]cbNewMainConnectionsignal("NewMainConnection")event [newMainConnection(mainConnectionID)]cbMainConnectionStateChangesignal("MainConnectionStateChange")event [mainConnectionStateChange(CS_DISCONNECTED)]Once connection is requested andcreated in AudioManager, mainconnection continuously performtransition caused by policy decisionloop[Lifecycle of a main connection]alt[Transition of sound mode = Connect]Policy_Decision()refConnect Sound RouterefStart Sound Streaming[Disconnect]refStop Sound StreamingrefDisconnect Sound Route[Suspend]refStop Sound StreamingcbMainConnectionStatesignal("MainConnectionState")event [mainConnectionStateChange]cbRemoveMainConnectionsignal("RemoveMainConnection")event [removemainConnection] \ No newline at end of file diff --git a/docs/4_APIs_and_Services/4.7_HMI_Framework/parts/seq_setmutestate.svg b/docs/4_APIs_and_Services/4.7_HMI_Framework/parts/seq_setmutestate.svg deleted file mode 100644 index 8d39775..0000000 --- a/docs/4_APIs_and_Services/4.7_HMI_Framework/parts/seq_setmutestate.svg +++ /dev/null @@ -1,115 +0,0 @@ -CommandPlugInAudio Manager DaemonRoutingPlugInApplicationSoundManagerIAmCommandSendIAmCommandReceiverAudioManagerIAmRoutingReceiveIAmRoutingSendAudio DomainSetSinkMuteState()SetSinkMuteState()SetSinkMuteState()asyncSetSinkVolume()SetMute()ackSetMute()ackSetSinkVolumeChange()cbSinkMuteStateChangedsignal("sinkMuteStateChanged")event [sinkMuteStateChanged] \ No newline at end of file diff --git a/docs/4_APIs_and_Services/4.7_HMI_Framework/parts/seq_startsoundstreaming.svg b/docs/4_APIs_and_Services/4.7_HMI_Framework/parts/seq_startsoundstreaming.svg deleted file mode 100644 index 108cfa0..0000000 --- a/docs/4_APIs_and_Services/4.7_HMI_Framework/parts/seq_startsoundstreaming.svg +++ /dev/null @@ -1,129 +0,0 @@ -CommandPlugInAudio Manager DaemonRoutingPlugInApplicationSoundManagerIAmCommandSendIAmCommandReceiverAudioManagerIAmRoutingReceiveIAmRoutingSendAudio DomainasyncSetSourceState (SS_ON)setMute(SS_ON)Mute(UnMute)ackSetSourceState()asyncSetSourceState()signal("asyncSetSourceState(SS_ON)")event [asyncSetSourceState("on")]Prepare audio device.And start audio playingackSetSourceState()ackSetSourceState()ackSetSource()cbMainConnectionStateChanged(CS_CONNECTED)signal("mainConnectionStateChanged (CS_CONNECTED)")event [mainConnectionStateChanged (CS_CONNECTED)] \ No newline at end of file diff --git a/docs/4_APIs_and_Services/4.7_HMI_Framework/parts/seq_startup.svg b/docs/4_APIs_and_Services/4.7_HMI_Framework/parts/seq_startup.svg deleted file mode 100644 index 27f0ab0..0000000 --- a/docs/4_APIs_and_Services/4.7_HMI_Framework/parts/seq_startup.svg +++ /dev/null @@ -1,68 +0,0 @@ - -CommandPlugInAudio Manager DaemonRoutingPlugInApplicationSoundManagerIAmCommandSendIAmCommandReceiverAudioManagerIAmRoutingReceiveIAmRoutingSendAudio DomainStartup()loop[Number of Domains]refRegistrationwait_event() \ No newline at end of file diff --git a/docs/4_APIs_and_Services/4.7_HMI_Framework/parts/seq_stopsoundstreaming.svg b/docs/4_APIs_and_Services/4.7_HMI_Framework/parts/seq_stopsoundstreaming.svg deleted file mode 100644 index 41a2e41..0000000 --- a/docs/4_APIs_and_Services/4.7_HMI_Framework/parts/seq_stopsoundstreaming.svg +++ /dev/null @@ -1,129 +0,0 @@ -CommandPlugInAudio Manager DaemonRoutingPlugInApplicationSoundManagerIAmCommandSendIAmCommandReceiverAudioManagerIAmRoutingReceiveIAmRoutingSendAudio DomainasyncSetSourceState ()asyncSetSourceState(SS_PAUSED)event [asyncSetSourceState("paused")]Stop audio playing.And release audio device.ackSetSourceState()ackSetSourceState()ackSetSourceState()cbMainConnectionStateChanged (CS_SUSPENDED)]signal("MainConnectionStateChanged (CS_SUSPENDED)")event [mainConnectionStateChanged (CS_SUSPENDED)]asyncSetSourceState()SetMute()Mute (MUTE)ackSetSourceState() \ No newline at end of file diff --git a/docs/4_APIs_and_Services/4.7_HMI_Framework/parts/showInformation.svg b/docs/4_APIs_and_Services/4.7_HMI_Framework/parts/showInformation.svg deleted file mode 100644 index c49d734..0000000 --- a/docs/4_APIs_and_Services/4.7_HMI_Framework/parts/showInformation.svg +++ /dev/null @@ -1,30 +0,0 @@ -show information on HomeScreen bottom areahomescreen-servicehomescreen-servicehomescreenhomescreenAppAppshowInformation(){"info":"display information"}push showInformation eventdisplay information message 3s \ No newline at end of file diff --git a/docs/4_APIs_and_Services/4.7_HMI_Framework/parts/showNotification.svg b/docs/4_APIs_and_Services/4.7_HMI_Framework/parts/showNotification.svg deleted file mode 100644 index 7ef1572..0000000 --- a/docs/4_APIs_and_Services/4.7_HMI_Framework/parts/showNotification.svg +++ /dev/null @@ -1,34 +0,0 @@ -show notification on HomeScreen top areahomescreen-servicehomescreen-servicehomescreenhomescreenAppAppshowNotification(){"icon":"display icon", "text":"display text"}push showNotification event{"application_id":"request application id","parameter":{"icon":"display icon", "text":"display text"}}display notification message 3s \ No newline at end of file diff --git a/docs/4_APIs_and_Services/4.7_HMI_Framework/parts/showOnScreen.svg b/docs/4_APIs_and_Services/4.7_HMI_Framework/parts/showOnScreen.svg deleted file mode 100644 index 74fb3a1..0000000 --- a/docs/4_APIs_and_Services/4.7_HMI_Framework/parts/showOnScreen.svg +++ /dev/null @@ -1,72 +0,0 @@ -show/hide onscreen phaseuseruserhomescreen-servicehomescreen-serviceAppApponscreenapponscreenappwindowmanagerwindowmanagershow onscreenthe operation request onscreenshowWindow(){"application_id":"onscreenapp","parameter":{"area":"display area", "file":"qml file path","data":{"the datas to onscreen qml"}}}push showWindow event{"application_id":"onscreenapp","parameter":{"area":"display area", "file":"qml file path","data":{"the datas to onscreen qml"},"replyto":"caller application id"}}get and save parametersactivateWindow("onscreeapp", "display area")alt[can show]push syncDraw eventendDraw("onscreeapp")load and display qml file[can't show]do nothinghide onscreentap onscreen's buttonreplyShowWindow(){"application_id":"the application id who called onscreenapp","parameter": {"buttonName": "VOLUME_UP", "buttonPressMode": "shortPress", "buttonPressState": "release"}}push replyShowWindow eventcall reply functionhideWindow("onscreenapp")push hideWindow event{"application_id":"request hideWindow application id"}deactivateWindow("onscreenapp");hide window \ No newline at end of file diff --git a/docs/4_APIs_and_Services/4.7_HMI_Framework/parts/showWindow.svg b/docs/4_APIs_and_Services/4.7_HMI_Framework/parts/showWindow.svg deleted file mode 100644 index c860a85..0000000 --- a/docs/4_APIs_and_Services/4.7_HMI_Framework/parts/showWindow.svg +++ /dev/null @@ -1,34 +0,0 @@ -Application callback event showWindow phaseuseruserhomescreen-servicehomescreen-servicelauncherlauncherAppAppwindowmanagerwindowmanagertap app's iconshowWindow(){"application_id":"tapped application id", "parameter":{"area":"display area", ...}}push showWindow eventactivateWindow("application_name","display area")push syncDraw eventdisplay \ No newline at end of file diff --git a/docs/4_APIs_and_Services/4.7_HMI_Framework/parts/software-stack.png b/docs/4_APIs_and_Services/4.7_HMI_Framework/parts/software-stack.png deleted file mode 100644 index e449868..0000000 Binary files a/docs/4_APIs_and_Services/4.7_HMI_Framework/parts/software-stack.png and /dev/null differ diff --git a/docs/4_APIs_and_Services/4.7_HMI_Framework/parts/state_change_example.png b/docs/4_APIs_and_Services/4.7_HMI_Framework/parts/state_change_example.png deleted file mode 100644 index 23dada4..0000000 Binary files a/docs/4_APIs_and_Services/4.7_HMI_Framework/parts/state_change_example.png and /dev/null differ diff --git a/docs/4_APIs_and_Services/4.7_HMI_Framework/parts/tap_shortcut.svg b/docs/4_APIs_and_Services/4.7_HMI_Framework/parts/tap_shortcut.svg deleted file mode 100644 index c6be41b..0000000 --- a/docs/4_APIs_and_Services/4.7_HMI_Framework/parts/tap_shortcut.svg +++ /dev/null @@ -1,26 +0,0 @@ -Application Callback Event TapShortcut phaseAppAppHomeScreenBinderHomeScreenBinderHomeScreenGUIHomeScreenGUIset_event_handler()LibHomeScreen::Event_TapShortcuttapShortcut(application_id)event_handler(application_id) \ No newline at end of file diff --git a/docs/4_APIs_and_Services/4.7_HMI_Framework/parts/typical-usecase.png b/docs/4_APIs_and_Services/4.7_HMI_Framework/parts/typical-usecase.png deleted file mode 100644 index 47a2d33..0000000 Binary files a/docs/4_APIs_and_Services/4.7_HMI_Framework/parts/typical-usecase.png and /dev/null differ diff --git a/docs/4_APIs_and_Services/4.7_HMI_Framework/parts/wm_area.png b/docs/4_APIs_and_Services/4.7_HMI_Framework/parts/wm_area.png deleted file mode 100644 index e713782..0000000 Binary files a/docs/4_APIs_and_Services/4.7_HMI_Framework/parts/wm_area.png and /dev/null differ diff --git a/docs/4_APIs_and_Services/4.7_HMI_Framework/parts/wm_change_layout.png b/docs/4_APIs_and_Services/4.7_HMI_Framework/parts/wm_change_layout.png deleted file mode 100644 index 2bc9ef6..0000000 Binary files a/docs/4_APIs_and_Services/4.7_HMI_Framework/parts/wm_change_layout.png and /dev/null differ diff --git a/docs/4_APIs_and_Services/4.7_HMI_Framework/parts/wm_layer_stack.png b/docs/4_APIs_and_Services/4.7_HMI_Framework/parts/wm_layer_stack.png deleted file mode 100644 index 9c99731..0000000 Binary files a/docs/4_APIs_and_Services/4.7_HMI_Framework/parts/wm_layer_stack.png and /dev/null differ diff --git a/docs/4_APIs_and_Services/4.7_HMI_Framework/parts/wm_software_stack.png b/docs/4_APIs_and_Services/4.7_HMI_Framework/parts/wm_software_stack.png deleted file mode 100644 index aa66636..0000000 Binary files a/docs/4_APIs_and_Services/4.7_HMI_Framework/parts/wm_software_stack.png and /dev/null differ diff --git a/docs/4_APIs_and_Services/4.8_HomeScreen_(old)/homescreen_api.md b/docs/4_APIs_and_Services/4.8_HomeScreen_(old)/homescreen_api.md deleted file mode 100644 index 8a2072a..0000000 --- a/docs/4_APIs_and_Services/4.8_HomeScreen_(old)/homescreen_api.md +++ /dev/null @@ -1,195 +0,0 @@ ---- -edit_link: '' -title: HomeScreen API -origin_url: >- - https://git.automotivelinux.org/apps/homescreen/plain/homescreen/docs/homescreen_api.md?h=master ---- - - - -# HomeScreen API -The HomeScreen app provides an own interface for some special use cases concerning the surfaces and user inputs. - -The interface is implemented as D-Bus interface. -This is the introspection, describing the interface: - -``` - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -``` - -These interface will change during further development, so check back frequently. - -## User Input Events API calls - -### hardKeyPressed - -Use hardKeyPressed to inject hard key press events into the HomeScreen app. -This Interface call can be used by applications like the InputEventManager to inject hard keys into the HomeScreen application. - -#### Example - -if someone presses the Hard Key “NAV” on the target, this key may be injected using this interface to make the HomeScreen launch the navigation application. -Right now, only a few keys are defined (in inputevent.hpp): - -``` -namespace InputEvent { - typedef enum HardKey - { - HARDKEY_UNDEFINED, - HARDKEY_NAV, - HARDKEY_MEDIA - } eHardKey; -} -``` - -This will change in the future. - -![hardKeyPressed](pictures/api_hardKeyPressed.png) - -A “normal” application would not need to call this API. - -## Surface control API calls - -The normal use case when starting an application is: -The user presses a hard key or uses the app launcher to start an app. The app is then started and is shown full screen. -The org.agl.homescreen API provides some methods to get information about some status and some methods to show surfaces on the screen. - -### getSurfaceStatus - -A surface can be visible or invisible (please do not confuse “visible” and “visibility”). This function allows to request the current status. - -``` - - - - -``` - -Right now an application has to pull this information. -This is not optimal and will change in the future. There are two options: - - - The homescreen API will provide a signal that is emitted every time the visible status of surfaces changes. This would be way more efficient, because it would save time and avoid a re-occurring API call. __UPDATE:__ There is a D-Bus signal implemented in this API - - For Qt, there is already a patch available that provides this information as a base class property. See https://codereview.qt-project.org/#/c/176211/ This would be optimal for Qt widget applications. But not useful for other languages, e.g. Java. __UPDATE:__ This patch got reverted in AGL! - -#### Current implementation - -![getSurfaceStatus](pictures/api_getSurfaceStatus_1.png) - -#### Option 1 - -![getSurfaceStatus](pictures/api_getSurfaceStatus_2.png) - -#### Option 2 - -![getSurfaceStatus](pictures/api_getSurfaceStatus_3.png) - -### requestSurfaceIdToFullScreen - -This function will set the given surface to full screen. - -``` - - - -``` - -It will hide all other surfaces. - -![requestSurfaceIdToFullScreen](pictures/api_requestSurfaceIdToFullScreen.png) - -### getAllSurfacesOfProcess - -This returns all surfaces that are created by the given process ID. - -``` - - - - - -``` - -A process can create more than one surface. By default, the surface with the lowest surface ID is shown on the screen. If an application wants to know all surfaces that were created by an application, this method will provide them. - -![getAllSurfacesOfProcess](pictures/api_getAllSurfacesOfProcess.png) - -### renderSurfaceToAreaAllowed - -Before calling renderSurfaceToArea, an application can request, if it is allowed to render the surface to this area. This makes sense for an application that would begin to allocate resources to render. But if it is not allowed to render the surface, the application could avoid allocating the resources. - -``` - - - - - -``` - -The call will not affect the current setup, it will only request if it is allowed or not. - -![renderSurfaceToAreaAllowed](pictures/api_renderSurfaceToAreaAllowed.png) - -### renderSurfaceToArea - -By default, the HomeScreen application decides, where to render an applications surface. The concept of Layouts defines this. This API call can override the default behavior. An app can request to render a surface in a specific Layout Area. - -``` - - - - -``` - -The surface that was previously rendered in this Layout are will be hidden. - -![renderSurfaceToArea](pictures/api_renderSurfaceToArea.png) - -The homescreen interface functionality is not fully implemented, but the API is available. For example using the libhomescreen.so. - -### surfaceVisibilityChanged - -Whenever the visibility property of a surface changes, this signal is emitted. - -``` - - - - -``` - -Visibility here means visible. The name of the signal is from the Weston surface property “visibility”. -See here for reference: https://github.com/ntanibata/wayland-ivi-extension/blob/master/ivi-layermanagement-api/ilmCommon/include/ilm_types.h - -![surfaceVisibilityChanged](pictures/api_surfaceVisibilityChanged.png) diff --git a/docs/4_APIs_and_Services/4.8_HomeScreen_(old)/pictures/api_getAllSurfacesOfProcess.png b/docs/4_APIs_and_Services/4.8_HomeScreen_(old)/pictures/api_getAllSurfacesOfProcess.png deleted file mode 100644 index 5c862d7..0000000 Binary files a/docs/4_APIs_and_Services/4.8_HomeScreen_(old)/pictures/api_getAllSurfacesOfProcess.png and /dev/null differ diff --git a/docs/4_APIs_and_Services/4.8_HomeScreen_(old)/pictures/api_getSurfaceStatus_1.png b/docs/4_APIs_and_Services/4.8_HomeScreen_(old)/pictures/api_getSurfaceStatus_1.png deleted file mode 100644 index 1e18fcf..0000000 Binary files a/docs/4_APIs_and_Services/4.8_HomeScreen_(old)/pictures/api_getSurfaceStatus_1.png and /dev/null differ diff --git a/docs/4_APIs_and_Services/4.8_HomeScreen_(old)/pictures/api_getSurfaceStatus_2.png b/docs/4_APIs_and_Services/4.8_HomeScreen_(old)/pictures/api_getSurfaceStatus_2.png deleted file mode 100644 index e66d708..0000000 Binary files a/docs/4_APIs_and_Services/4.8_HomeScreen_(old)/pictures/api_getSurfaceStatus_2.png and /dev/null differ diff --git a/docs/4_APIs_and_Services/4.8_HomeScreen_(old)/pictures/api_getSurfaceStatus_3.png b/docs/4_APIs_and_Services/4.8_HomeScreen_(old)/pictures/api_getSurfaceStatus_3.png deleted file mode 100644 index 50a3b10..0000000 Binary files a/docs/4_APIs_and_Services/4.8_HomeScreen_(old)/pictures/api_getSurfaceStatus_3.png and /dev/null differ diff --git a/docs/4_APIs_and_Services/4.8_HomeScreen_(old)/pictures/api_hardKeyPressed.png b/docs/4_APIs_and_Services/4.8_HomeScreen_(old)/pictures/api_hardKeyPressed.png deleted file mode 100644 index a8a3660..0000000 Binary files a/docs/4_APIs_and_Services/4.8_HomeScreen_(old)/pictures/api_hardKeyPressed.png and /dev/null differ diff --git a/docs/4_APIs_and_Services/4.8_HomeScreen_(old)/pictures/api_renderSurfaceToArea.png b/docs/4_APIs_and_Services/4.8_HomeScreen_(old)/pictures/api_renderSurfaceToArea.png deleted file mode 100644 index a61fc2f..0000000 Binary files a/docs/4_APIs_and_Services/4.8_HomeScreen_(old)/pictures/api_renderSurfaceToArea.png and /dev/null differ diff --git a/docs/4_APIs_and_Services/4.8_HomeScreen_(old)/pictures/api_renderSurfaceToAreaAllowed.png b/docs/4_APIs_and_Services/4.8_HomeScreen_(old)/pictures/api_renderSurfaceToAreaAllowed.png deleted file mode 100644 index 35dbbcf..0000000 Binary files a/docs/4_APIs_and_Services/4.8_HomeScreen_(old)/pictures/api_renderSurfaceToAreaAllowed.png and /dev/null differ diff --git a/docs/4_APIs_and_Services/4.8_HomeScreen_(old)/pictures/api_requestSurfaceIdToFullScreen.png b/docs/4_APIs_and_Services/4.8_HomeScreen_(old)/pictures/api_requestSurfaceIdToFullScreen.png deleted file mode 100644 index 6d2f712..0000000 Binary files a/docs/4_APIs_and_Services/4.8_HomeScreen_(old)/pictures/api_requestSurfaceIdToFullScreen.png and /dev/null differ diff --git a/docs/4_APIs_and_Services/4.8_HomeScreen_(old)/pictures/api_surfaceVisibilityChanged.png b/docs/4_APIs_and_Services/4.8_HomeScreen_(old)/pictures/api_surfaceVisibilityChanged.png deleted file mode 100644 index f519757..0000000 Binary files a/docs/4_APIs_and_Services/4.8_HomeScreen_(old)/pictures/api_surfaceVisibilityChanged.png and /dev/null differ -- cgit 1.2.3-korg