diff --git a/app_api/src/app_main.c b/app_api/src/app_main.c index 3c333c676e..eb7912bd4f 100644 --- a/app_api/src/app_main.c +++ b/app_api/src/app_main.c @@ -131,12 +131,12 @@ void appMain() { // App-channel { char buffer[APPCHANNEL_MTU]; - appchannelSendPacket("hello", 5); // Deprecated + appchannelSendPacket("hello", 5); // Deprecated (removed after August 2023) appchannelSendDataPacketBlock("hello", 5); appchannelSendDataPacket("hello", 5); - appchannelReceivePacket(buffer, APPCHANNEL_MTU, APPCHANNEL_WAIT_FOREVER); // Deprecated + appchannelReceivePacket(buffer, APPCHANNEL_MTU, APPCHANNEL_WAIT_FOREVER); // Deprecated (removed after August 2023) appchannelReceiveDataPacket(buffer, APPCHANNEL_MTU, APPCHANNEL_WAIT_FOREVER); - appchannelHasOverflowOccured(); // Deprecated + appchannelHasOverflowOccured(); // Deprecated (removed after August 2023) appchannelHasOverflowOccurred(); } diff --git a/docs/development/apis_versions_deprecation.md b/docs/development/apis_versions_deprecation.md new file mode 100644 index 0000000000..63cc7cbd6d --- /dev/null +++ b/docs/development/apis_versions_deprecation.md @@ -0,0 +1,55 @@ +--- +title: APIs, versions and deprecations +page_id: api-deprecation +--- + +There are a number of APIs in the Crazyflie eco system on multiple levels, some might be obvious while others are a bit +more subtle. Some of the APIs are documented and versioned while there is room for improvement in other cases. + +Since all code can be used by a programmer, one point of view would be that all functions and protocols are APIs, and +should not change without some form of version change. To +make it possible for us to manage the code base, we have chosen a few areas (APIs) that we will update in a structured way +(see below). Code that does not belong to these APIs can be changed at any time, which we believe is necessary to keep +the system dynamic and evolve over time. + +The purpose of managing APIs in a structured way is to help a developer to understand if a protocol or a set of +functions is likely to change over time and if it will break the application. It should also be possible to detect if +(and how) the API has changed and what changes that are required to the code to make the application work. + +## The update process and deprecations + +Areas that can be versioned using a version number, for instance protocols, should update the version number when +something (of instance the protocol) is changed. Check the documentation for the specific area/protocol to see if there +is a specific update policy for this area. An example would be [CRTP](/docs/functional-areas/crtp/index.md#protocol-version-and-stability-guarantee). + +For functions in the code base, there is not really a version number tied to the function (except the release version) that +clearly tells the programmer if there has been an API break or not. The approach we use is to mark functions that we +want to remove as 'deprecated`. The deprecated function will continue to exist and work for a minimum of 6 months before +being removed. Deprecated functions are documented in the release notes to give a heads up that they will be removed in +a future release. The deprecation marking is usually done by adding the word `deprecated` to the function documentation. +Also add a date when the function will be removed (at the earliest) and, if applicable, a replacement function to use +instead. + +Example: + +``` C +/** + * @brief Deprecated (removed after August 2023). Use the "deck.bcLoco" parameter instead. + * + * Nonzero if [Loco positioning deck](%https://store.bitcraze.io/products/loco-positioning-deck) is attached + */ +PARAM_ADD_CORE(PARAM_UINT8 | PARAM_RONLY, bcDWM1000, &isInit) +``` + +## Current APIs with structured updates + +The following areas and protocols are updated with a structured process: + +* [CRTP](/docs/functional-areas/crtp) +* App API - the functions called from `app_api/src/app_main.c` +* [Parameters](/docs/api/params.md) - parameters marked as `CORE` +* [Logs](/docs/api/logs.md) - logs marked as `CORE` +* [Trajectory formats](/docs/functional-areas/trajectory_formats.md) +* [Loco TWR protocol](https://www.bitcraze.io/documentation/repository/lps-node-firmware/master/protocols/twr-protocol/) +* [Loco TDoA2 protocol](https://www.bitcraze.io/documentation/repository/lps-node-firmware/master/protocols/tdoa2_protocol/) +* [Loco TDoA3 protocol](https://www.bitcraze.io/documentation/repository/lps-node-firmware/master/protocols/tdoa3_protocol/) diff --git a/src/deck/drivers/src/locodeck.c b/src/deck/drivers/src/locodeck.c index 811075538b..a025c87c61 100644 --- a/src/deck/drivers/src/locodeck.c +++ b/src/deck/drivers/src/locodeck.c @@ -601,7 +601,8 @@ DECK_DRIVER(dwm1000_deck); PARAM_GROUP_START(deck) /** - * @brief Deprecated, replaced with the "deck.bcLoco" parameter. + * @brief Deprecated (removed after August 2023). Use the "deck.bcLoco" parameter instead. + * * Nonzero if [Loco positioning deck](%https://store.bitcraze.io/products/loco-positioning-deck) is attached */ PARAM_ADD_CORE(PARAM_UINT8 | PARAM_RONLY, bcDWM1000, &isInit) diff --git a/src/modules/interface/app_channel.h b/src/modules/interface/app_channel.h index cc9f49de9c..70b16f03c6 100644 --- a/src/modules/interface/app_channel.h +++ b/src/modules/interface/app_channel.h @@ -34,7 +34,7 @@ #define APPCHANNEL_MTU (31) /** - * Send an app-channel packet - deprecated, use appchannelSendDataPacketBlock() instead + * Send an app-channel packet - deprecated (removed after August 2023). Use appchannelSendDataPacketBlock() instead. * * The maximum buffer size that can be sent is define in APPCHANNEL_MTU. * If the length of the buffer is longer than that, the packet will be cropped @@ -90,7 +90,7 @@ void appchannelSendDataPacketBlock(void* data, size_t length); int appchannelSendDataPacket(void* data, size_t length); /** - * Receive an app-channel packet - deprecated, use appchannelReceiveDataPacket() instead + * Receive an app-channel packet - deprecated (removed after August 2023). Use appchannelReceiveDataPacket() instead * * If the data received is longer than max_length, the data will be silently cropped and only * the fist "max_length" bytes of the packet will be copied in the buffer. @@ -138,7 +138,7 @@ size_t appchannelReceiveDataPacket(void* buffer, size_t max_length, int timeout_ bool appchannelHasOverflowOccurred(); /** - * Returns if an overflow has occurred in the receive queue - deprecated, use appchannelHasOverflowOccurred() instead + * Returns if an overflow has occurred in the receive queue - deprecated (removed after August 2023). Use appchannelHasOverflowOccurred() instead * * The app-channel received packets are put in a queue. It is expected that the app is * regularly calling appchannelReceiveDataPacket() to get the packets from the receive queue. diff --git a/src/modules/interface/sitaw.h b/src/modules/interface/sitaw.h index a1c0f76bde..e43aa329ed 100644 --- a/src/modules/interface/sitaw.h +++ b/src/modules/interface/sitaw.h @@ -26,7 +26,7 @@ #pragma once -#pragma message "sitAwTuDetected is deprecated, consider switching to supervisorIsTumbled!" +#pragma message "sitAwTuDetected is deprecated (removed after August 2023), consider switching to supervisorIsTumbled!" #include "supervisor.h" #define sitAwTuDetected supervisorIsTumbled diff --git a/src/modules/src/app_channel.c b/src/modules/src/app_channel.c index 476987038d..9d2f41a85f 100644 --- a/src/modules/src/app_channel.c +++ b/src/modules/src/app_channel.c @@ -43,7 +43,7 @@ static bool overflow; static int sendDataPacket(void* data, size_t length, const bool doBlock); -// Deprecated +// Deprecated (removed after August 2023) void appchannelSendPacket(void* data, size_t length) { appchannelSendDataPacketBlock(data, length); @@ -59,7 +59,7 @@ void appchannelSendDataPacketBlock(void* data, size_t length) sendDataPacket(data, length, true); } -// Deprecated +// Deprecated (removed after August 2023) size_t appchannelReceivePacket(void* buffer, size_t max_length, int timeout_ms) { return appchannelReceiveDataPacket(buffer, max_length, timeout_ms); } diff --git a/src/modules/src/crtp_commander_high_level.c b/src/modules/src/crtp_commander_high_level.c index eff53dbe72..5f653287b4 100644 --- a/src/modules/src/crtp_commander_high_level.c +++ b/src/modules/src/crtp_commander_high_level.c @@ -129,8 +129,8 @@ STATIC_MEM_TASK_ALLOC(crtpCommanderHighLevelTask, CMD_HIGH_LEVEL_TASK_STACKSIZE) // trajectory command (first byte of crtp packet) enum TrajectoryCommand_e { COMMAND_SET_GROUP_MASK = 0, - COMMAND_TAKEOFF = 1, // Deprecated, use COMMAND_TAKEOFF_2 - COMMAND_LAND = 2, // Deprecated, use COMMAND_LAND_2 + COMMAND_TAKEOFF = 1, // Deprecated (removed after August 2023), use COMMAND_TAKEOFF_2 + COMMAND_LAND = 2, // Deprecated (removed after August 2023), use COMMAND_LAND_2 COMMAND_STOP = 3, COMMAND_GO_TO = 4, COMMAND_START_TRAJECTORY = 5, @@ -146,7 +146,7 @@ struct data_set_group_mask { } __attribute__((packed)); // vertical takeoff from current x-y position to given height -// Deprecated +// Deprecated (removed after August 2023) struct data_takeoff { uint8_t groupMask; // mask for which CFs this should apply to float height; // m (absolute) @@ -174,7 +174,7 @@ struct data_takeoff_with_velocity { } __attribute__((packed)); // vertical land from current x-y position to given height -// Deprecated +// Deprecated (removed after August 2023) struct data_land { uint8_t groupMask; // mask for which CFs this should apply to float height; // m (absolute) @@ -433,6 +433,7 @@ int set_group_mask(const struct data_set_group_mask* data) return 0; } +// Deprecated (removed after August 2023) int takeoff(const struct data_takeoff* data) { int result = 0; @@ -488,6 +489,7 @@ int takeoff_with_velocity(const struct data_takeoff_with_velocity* data) return result; } +// Deprecated (removed after August 2023) int land(const struct data_land* data) { int result = 0; diff --git a/src/modules/src/crtp_localization_service.c b/src/modules/src/crtp_localization_service.c index 88fab9b48e..54461c19e1 100644 --- a/src/modules/src/crtp_localization_service.c +++ b/src/modules/src/crtp_localization_service.c @@ -390,7 +390,7 @@ void locSrvSendLighthouseAngle(int baseStation, pulseProcessorResult_t* angles) } #endif -// This logging group is deprecated +// This logging group is deprecated (removed after August 2023) LOG_GROUP_START(ext_pos) LOG_ADD(LOG_FLOAT, X, &ext_pos.x) LOG_ADD(LOG_FLOAT, Y, &ext_pos.y) diff --git a/src/modules/src/lighthouse/lighthouse_core.c b/src/modules/src/lighthouse/lighthouse_core.c index c44efc018d..31dccc4fd8 100644 --- a/src/modules/src/lighthouse/lighthouse_core.c +++ b/src/modules/src/lighthouse/lighthouse_core.c @@ -913,11 +913,9 @@ PARAM_ADD_CORE(PARAM_UINT8, bsCalibReset, &calibStatusReset) PARAM_ADD_CORE(PARAM_UINT8, systemType, &systemType) /** - * @brief Bit field that indicates which base stations that are supported by the system + * @brief Bit field that indicates which base stations that are supported by the system - deprecated (removed after August 2023) * * The lowest bit maps to base station channel 1 and the highest to channel 16. - * - * Deprecated since 2022-08-15 */ PARAM_ADD_CORE(PARAM_UINT16 | PARAM_RONLY, bsAvailable, &baseStationAvailabledMap)