docs(epicardium): Make it abundantly clear that the BLE epic-calls are unstable

epicardium/epicardium.h

@@ -2660,44 +2660,77 @@ API(API_BLE_HID_SEND_REPORT, int epic_ble_hid_send_report(uint8_t report_id, uin
 
 
 /**
- * MicroPython BLE support API
+ * MicroPython BLE Support API
+ * ---------------------------
+ * The following API calls are to be used for MicroPython BLE support.
  *
- * Please do not use this API outside the MicroPython Bluetooth module. The API designed to work
- * specifically with that module.
+ * .. warning::
+ *
+ *    The following epic-calls are **not** part of the stable public API and
+ *    thus **no** guarantee about stability or behavior is made.  Do not use
+ *    these outside of Pycardium unless you can live with sudden breakage!!
  *
- * The MicroPython Bluetooth module is still in flux so this API will continue to change as well.
+ *    They are only documented here for completeness and as a reference for
+ *    firmware hackers, not for common usage.
  */
+
+/** Private API call for Pycardium BLE support. */
 API(API_BLE_INIT, int epic_ble_init(void));
+/** Private API call for Pycardium BLE support. */
 API(API_BLE_DEINIT, int epic_ble_deinit(void));
+/** Private API call for Pycardium BLE support. */
 API(API_BLE_ATTS_DYN_CREATE_GROUP, int epic_atts_dyn_create_service(const uint8_t *uuid, uint8_t uuid_len, uint16_t group_size, void **pSvcHandle));
 //API(API_BLE_ATTS_DYN_DELETE_GROUP, void AttsDynDeleteGroup(void *pSvcHandle));
+/** Private API call for Pycardium BLE support. */
 API(API_BLE_ATTS_DYN_DELETE_GROUPS, int epic_ble_atts_dyn_delete_groups(void));
 
+/** Private API call for Pycardium BLE support. */
 API(API_BLE_ATTS_DYN_ADD_CHARACTERISTIC, int epic_atts_dyn_add_characteristic(void *pSvcHandle, const uint8_t *uuid, uint8_t uuid_len, uint8_t flags, uint16_t maxLen, uint16_t *value_handle));
+/** Private API call for Pycardium BLE support. */
 API(API_BLE_ATTS_DYN_ADD_DESCRIPTOR, int epic_ble_atts_dyn_add_descriptor(void *pSvcHandle, const uint8_t *uuid, uint8_t uuid_len, uint8_t flags, const uint8_t *value, uint16_t value_len, uint16_t maxLen, uint16_t *descriptor_handle));
 
+/** Private API call for Pycardium BLE support. */
 API(API_BLE_ATTS_SEND_SERVICE_CHANGED_IND, int epic_atts_dyn_send_service_changed_ind(void));
 
+/** Private API call for Pycardium BLE support. */
 API(API_BLE_ATTS_SET_ATTR, int epic_ble_atts_set_attr(uint16_t handle, const uint8_t *value, uint16_t value_len));
+/** Private API call for Pycardium BLE support. */
 API(API_BLE_ATTS_HANDLE_VALUE_NTF, int epic_ble_atts_handle_value_ntf(uint8_t connId, uint16_t handle, uint16_t valueLen, uint8_t *pValue));
+/** Private API call for Pycardium BLE support. */
 API(API_BLE_ATTS_HANDLE_VALUE_IND, int epic_ble_atts_handle_value_ind(uint8_t connId, uint16_t handle, uint16_t valueLen, uint8_t *pValue));
+/** Private API call for Pycardium BLE support. */
 API(API_BLE_ATTS_SET_BUFFER, int epic_ble_atts_set_buffer(uint16_t value_handle, size_t len, bool append));
 
+/** Private API call for Pycardium BLE support. */
 API(API_BLE_FREE_EVENT, int epic_ble_free_event(struct epic_ble_event *e));
+/** Private API call for Pycardium BLE support. */
 API(API_BLE_CLOSE_CONNECTION, void epic_ble_close_connection(uint8_t connId));
+/** Private API call for Pycardium BLE support. */
 API(API_BLE_IS_CONNECTION_OPEN, int epic_ble_is_connection_open(void));
+/** Private API call for Pycardium BLE support. */
 API(API_BLE_SET_DEVICE_NAME, int epic_ble_set_device_name(const uint8_t *buf, uint16_t len));
+/** Private API call for Pycardium BLE support. */
 API(API_BLE_GET_DEVICE_NAME, int epic_ble_get_device_name(uint8_t **buf, uint16_t *len));
+/** Private API call for Pycardium BLE support. */
 API(API_BLE_GET_ADDRESS, void epic_ble_get_address(uint8_t *addr));
 
+/** Private API call for Pycardium BLE support. */
 API(API_BLE_ADVERTISE, int epic_ble_advertise(int interval_us, const uint8_t *adv_data, size_t adv_data_len, const uint8_t *sr_data, size_t sr_data_len, bool connectable));
+/** Private API call for Pycardium BLE support. */
 API(API_BLE_ADVERTISE_STOP, int epic_ble_advertise_stop(void));
 
+/** Private API call for Pycardium BLE support. */
 API(API_BLE_DISCOVER_PRIMARY_SERVICES, int epic_ble_attc_discover_primary_services(uint8_t connId, const uint8_t *uuid, uint8_t uuid_len));
+/** Private API call for Pycardium BLE support. */
 API(API_BLE_DISCOVER_CHARACTERISTICS, int epic_ble_attc_discover_characteristics(uint8_t connId, uint16_t start_handle, uint16_t end_handle));
+/** Private API call for Pycardium BLE support. */
 API(API_BLE_DISCOVER_DESCRIPTORS, int epic_ble_attc_discover_descriptors(uint8_t connId, uint16_t start_handle, uint16_t end_handle));
+/** Private API call for Pycardium BLE support. */
 API(API_BLE_ATTC_READ, int epic_ble_attc_read(uint8_t connId, uint16_t value_handle));
+/** Private API call for Pycardium BLE support. */
 API(API_BLE_ATTC_WRITE_NO_RSP, int epic_ble_attc_write_no_rsp(uint8_t connId, uint16_t value_handle, const uint8_t *value, uint16_t value_len));
+/** Private API call for Pycardium BLE support. */
 API(API_BLE_ATTC_WRITE, int epic_ble_attc_write(uint8_t connId, uint16_t value_handle, const uint8_t *value, uint16_t value_len));
+
 #endif /* _EPICARDIUM_H */