#include "NebulaWiFiConfig.h"
#include "NebulaError.h"
#include "TUTKGlobalAPIs.h"

Data Structures
struct	NebulaBLEDeviceCallbackGroup1

Macros
#define	NEBULA_BLE_API

#define	BLE_PROPERTY_BROADCAST (0x01)

#define	BLE_PROPERTY_READ (0x02)

#define	BLE_PROPERTY_WRITE_WITHOUT_RESPONSE (0x04)

#define	BLE_PROPERTY_WRITE (0x08)

#define	BLE_PROPERTY_NOTIFY (0x10)

#define	BLE_PROPERTY_INDICATE (0x20)

#define	BLE_PROPERTY_AUTH_WRITE (0x40)

#define	BLE_PROPERTY_EXTS (0x80)

Typedefs
typedef NebulaIOCtrlMsgUDIDResp	NebulaUDIDPinInfo_t

typedef NebulaIOCtrlMsgSSIDList2Resp	NebulaSSIDInfo_t

typedef NebulaIOCtrlMsgSetWifiResp	NebulaNetInfo_t

typedef void	NebulaGetCentralConnectCountFn (int *connected_count)

typedef void	NebulaGetNetStatusFn (NebulaNetInfo_t *connected_net_info)

typedef void	NebulaGetUDIDPinFn (NebulaUDIDPinInfo_t *udid_pin_info)

typedef void	NebulaGetSSIDListFn (int max_array_length, NebulaSSIDInfo_t ssid_info_array, int array_count)

typedef void	NebulaConnectWifiApFn (const char ssid, const char password, NebulaAPEncTypeEnum enctype)

typedef void	NebulaSetRegionFn (TUTKRegion region, NebulaSetConfigResult *result)

typedef void	NebulaGetBindMsgFn (char **nebula_bind_message_string)

typedef void	NebulaGetSecretIdFn (char **nebula_secret_id_string)

typedef void	NebulaSetTimeZoneFn (const char timezone_str, NebulaSetConfigResult result)

typedef void	NebulaGetFWVersionMsgFn (char **fw_version_string)

typedef void	NebulaSendMessageFn (const char characteristic_uuid, int ble_operate_type, const char message, int message_length)

typedef void	NebulaSetReadDataFn (const char characteristic_uuid, const char data, int data_length)

typedef void	NebulaHandleIOCtrlFn (NebulaIOCtrlType type, const char *ioctrl_buf, int ioctrl_len)

typedef const NebulaBLEDeviceCallbackGroup1 *	NebulaBLEDeviceInitializeConfig

Functions
NEBULA_BLE_API int	Nebula_BLE_Get_Service_Info (char *uuid_buff, int buff_length)
	Get Nebula BLE Service UUID.

NEBULA_BLE_API int	Nebula_BLE_Get_Characteristic_IOCtrl_Info (char uuid_buff, int buff_length, uint8_t property)
	Get Nebula BLE Characteristic UUID and property of IOCtrl message.

NEBULA_BLE_API int	Nebula_BLE_Client_Generate_IOCtrl_Message (NebulaIOCtrlType type, const char ioctrl_struct_ptr, uint16_t ioctrl_struct_length, char message_buf, uint16_t message_buf_size)
	Generate IOCtrl message for BLE client send function.

NEBULA_BLE_API int	Nebula_BLE_Client_Restore_IOCtrl_Message (const char characteristic_uuid, const char recv_buf, uint16_t data_len, NebulaHandleIOCtrlFn HandleIOCtrl)
	Handle IOCtrl message from BLE client receive function.

NEBULA_BLE_API int	Nebula_BLE_Device_Initialize (NebulaBLEDeviceInitializeConfig device_init_config)
	Initialize callback function for Nebula Device.

NEBULA_BLE_API int	Nebula_BLE_Device_DeInitialize ()
	DeInitialize callback function.

NEBULA_BLE_API int	Nebula_BLE_Device_Service_Start ()
	Nebula Device Start BLE service.

NEBULA_BLE_API int	Nebula_BLE_Device_Service_Stop ()
	Nebula Device Stop BLE service.

NEBULA_BLE_API int	Nebula_BLE_Device_Send_User_IOCtrl_Message (NebulaIOCtrlType user_define_type, const char *user_data, uint16_t user_data_len)
	Nebula Device send user define IOCtrl message.

NEBULA_BLE_API int	Nebula_BLE_Device_Receive_IOCtrl_Message (const char *recv_buf, uint16_t data_len)
	Nebula Device handle IOCtrl message from Nebula Client.

Detailed Description

This file describes all the APIs of the IOTC module in IOTC platform. IOTC module is a kind of data communication modules to provide basic data transfer among devices and clients.

Copyright: Copyright (c) 2010 by Throughtek Co., Ltd. All Rights Reserved.

Revision Table

Version	Name	Date	Description
4.0.0.0	Terry Liu	2019-08-07	+ Add Nebula_BLE_Get_Service_Info, Nebula_BLE_Get_Characteristic_Net_Status_Info
4.0.0.0	Terry Liu	2019-08-07	+ Add Nebula_BLE_Get_Characteristic_IOCtrl_Info, Nebula_BLE_Client_Restore_IOCtrl_Message
4.0.0.0	Terry Liu	2019-08-07	+ Add Nebula_BLE_Client_Generate_IOCtrl_Message, Nebula_BLE_Device_Initialize
4.0.0.0	Terry Liu	2019-08-07	+ Add Nebula_BLE_Device_DeInitialize, Nebula_BLE_Device_Service_Start
4.0.0.0	Terry Liu	2019-08-07	+ Add Nebula_BLE_Device_Service_Stop, Nebula_BLE_Device_Send_User_IOCtrl_Message
4.0.0.0	Terry Liu	2019-08-07	+ Add Nebula_BLE_Device_Receive_IOCtrl_Message

Macro Definition Documentation

#define BLE_PROPERTY_AUTH_WRITE (0x40)

#define BLE_PROPERTY_BROADCAST (0x01)

#define BLE_PROPERTY_EXTS (0x80)

#define BLE_PROPERTY_INDICATE (0x20)

#define BLE_PROPERTY_NOTIFY (0x10)

#define BLE_PROPERTY_READ (0x02)

#define BLE_PROPERTY_WRITE (0x08)

#define BLE_PROPERTY_WRITE_WITHOUT_RESPONSE (0x04)

#define NEBULA_BLE_API

Typedef Documentation

typedef const NebulaBLEDeviceCallbackGroup1* NebulaBLEDeviceInitializeConfig

typedef void NebulaConnectWifiApFn(const char *ssid, const char *password, NebulaAPEncTypeEnum enctype)

The prototype of connect assigned Wifi AP function. This function will be call when Peripheral get IOCTRL_SETWIFI_REQ.

Parameters

ssid	[in] SSID to connect
password	[in] Password of this Wifi AP
enctype	[in] Encode type of NebulaAPEncTypeEnum

typedef void NebulaGetBindMsgFn(char **nebula_bind_message_string)

The prototype of get Nebula local bind information function. This function will be call when Peripheral get IOCTRL_NEBULA_BIND_REQ.

Parameters

nebula_bind_message_string [out] Nebula local bind message

See Also: Nebula_Device_New_Credential()

typedef void NebulaGetCentralConnectCountFn(int *connected_count)

The prototype of get Central connect count function. This function will be call when Nebula check Central connect count.

Parameters

connected_count [out] Count of Central

typedef void NebulaGetFWVersionMsgFn(char **fw_version_string)

The prototype of get firmware version function. This function will be call when Peripheral get IOTYPE_GETFWVERSION_REQ.

Parameters

fw_version_string [out] firmware version

typedef void NebulaGetNetStatusFn(NebulaNetInfo_t *connected_net_info)

The prototype of get Wifi connect status function. This function will be call when Nebula check Wifi connect status.

Parameters

connected_net_info [out] SSID and connect result

typedef void NebulaGetSecretIdFn(char **nebula_secret_id_string)

The prototype of get Nebula secret id. This function will be call when Peripheral get IOCTRL_NEBULA_SCRET_ID_REQ.

Parameters

nebula_secret_id_string [out] Nebula local bind message

See Also: Nebula_Device_New_Credential()

typedef void NebulaGetSSIDListFn(int max_array_length, NebulaSSIDInfo_t *ssid_info_array, int *array_count)

The prototype of get current scanned Wifi AP list function. This function will be call when Peripheral get IOCTRL_SSIDLIST_REQ or IOCTRL_SSIDLIST2_REQ.

Parameters

max_array_length	[in] Max element number of ssid_info_array
ssid_info_array	[out] Array of SSID & encode type info
array_count	[out] Actual length of ssid_info_array

Attention: ssid_info_array will free by SDK

typedef void NebulaGetUDIDPinFn(NebulaUDIDPinInfo_t *udid_pin_info)

The prototype of get UDID and pair PIN code function. This function will be call when Peripheral get IOCTRL_UDID_REQ.

Parameters

udid_pin_info [out] UDID and PIN code

typedef void NebulaHandleIOCtrlFn(NebulaIOCtrlType type, const char *ioctrl_buf, int ioctrl_len)

The prototype of IOCtrl handle function. This function will be call after RestoreIOCtrlFromBLE() restore IOCtrl message or Nebula_BLE_Device_Receive_IOCtrl_Message() restore user defined message.

Parameters

type	[in] Type of NebulaIOCtrlType
ioctrl_buf	[in] Pointer of IOCtrl struct
ioctrl_len	[in] Length of ioctrl_buf

typedef NebulaIOCtrlMsgSetWifiResp NebulaNetInfo_t

typedef void NebulaSendMessageFn(const char *characteristic_uuid, int ble_operate_type, const char *message, int message_length)

The prototype of Nebula BLE send function. This function will be call when Peripheral need to send response to Central.

Parameters

characteristic_uuid	[in] Which characteristic to send message
ble_operate_type	[in] Send by BLE_PROPERTY_NOTIFY or BLE_PROPERTY_INDICATE
message	[in] Part of IOCtrl message message [in] Length of message

typedef void NebulaSetReadDataFn(const char *characteristic_uuid, const char *data, int data_length)

Nebula will set 4 Bytes data ( 2 Bytes NebulaIOCtrlType + 2 Bytes IOCtrl message length) in BLE READ buffer. This function will be call when Peripheral need to send response to Central.

Parameters

characteristic_uuid	[in] Which characteristic to keep data
data	[in] Type & actual message length of IOCtrl message
data_length	[in] Length of data_length

typedef void NebulaSetRegionFn(TUTKRegion region, NebulaSetConfigResult *result)

The prototype of set region function. This function will be call when Peripheral get IOCTRL_SETREGION_REQ.

Parameters

region	[in] region number of TUTKRegion
result	[out] set result of NebulaSetConfigResult

See Also: TUTK_SDK_Set_Master_Region()

typedef void NebulaSetTimeZoneFn(const char *timezone_str, NebulaSetConfigResult *result)

The prototype of set timezone function. This function will be call when Peripheral get IOTYPE_SETTIMEZONE_REQ.

Parameters

timezone_str	[in] Timezone string
result	[out] set result of NebulaSetConfigResult

typedef NebulaIOCtrlMsgSSIDList2Resp NebulaSSIDInfo_t

typedef NebulaIOCtrlMsgUDIDResp NebulaUDIDPinInfo_t

Function Documentation

NEBULA_BLE_API int Nebula_BLE_Client_Generate_IOCtrl_Message	(	NebulaIOCtrlType	type,
		const char *	ioctrl_struct_ptr,
		uint16_t	ioctrl_struct_length,
		char *	message_buf,
		uint16_t	message_buf_size
	)

Generate IOCtrl message for BLE client send function.

This function for generate IOCtrl message. Nebula BLE Central feed IOCtrl struct data , this function will generate IOCtrl message for WRITE.

Parameters

type	[in] Type of IOCtrl
ioctrl_struct_ptr	[in] Poniter of IOCtrl struct
ioctrl_struct_length	[in] Length of ioctrl_struct_ptr
message_buf	[out] IOCtrl message for BLE send function
message_buf_size	[in] send_buf size

Returns

> 0 for actual data size when generate message suucess.

Error code if return value < 0

NEBULA_ER_INVALID_ARG type is invalid or buffer pointer is NULL
NEBULA_ER_EXCEED_BUFFER_SIZE send_buf is too small
NEBULA_ER_MESSAGE_CHECK_FAIL input wrong struct of type

NEBULA_BLE_API int Nebula_BLE_Client_Restore_IOCtrl_Message	(	const char *	characteristic_uuid,
		const char *	recv_buf,
		uint16_t	data_len,
		NebulaHandleIOCtrlFn	HandleIOCtrl
	)

Handle IOCtrl message from BLE client receive function.

This function for Nebula BLE Central to handle IOCtrl message from Nebula BLE Peripheral and recovery to IOCtrl struct.

Parameters

characteristic_uuid	[in] UUID of Characteristic
recv_buf	[in] Pointer of receive buffer
data_len	[in] Actual data length
HandleIOCtrl	[in] IOCtrl callback function

Returns

> 0 for NebulaIOCtrlType and IOCtrl message receive completely.

= NEBULA_ER_NoERROR is message NOT receive completely.

Error code if return value < 0

NEBULA_ER_INVALID_ARG buffer pointer is NULL or callback is NULL
NEBULA_ER_EXCEED_BUFFER_SIZE send_buf is too small
NEBULA_ER_UNKNOW_MESSAGE unknow IOCtrl message or unknow ble_uuid

NEBULA_BLE_API int Nebula_BLE_Device_DeInitialize ( )

DeInitialize callback function.

This function for Nebula BLE Peripheral to deregister callback function .

Returns

NEBULA_ER_NoERROR for deInitialize success

Error code if return value < 0

NEBULA_ER_BLE_SERVICE_NOT_STOP Service is not stop

NEBULA_BLE_API int Nebula_BLE_Device_Initialize ( NebulaBLEDeviceInitializeConfig device_init_config )

Initialize callback function for Nebula Device.

This function for Nebula BLE Peripheral to register callback function .

Parameters

device_init_config [in] a pointer to structure which store all input parameters

Returns

NEBULA_ER_NoERROR for initialize success

Error code if return value < 0

NEBULA_ER_INVALID_ARG for pointer is NULL

See Also: NebulaGetCentralConnectCountFn(), NebulaGetNetStatusFn(), NebulaGetUDIDPinFn(), NebulaGetSSIDListFn(), NebulaConnectWifiApFn(), NebulaSendMessageFn(), NebulaSetReadDataFn(), NebulaHandleIOCtrlFn()

NEBULA_BLE_API int Nebula_BLE_Device_Receive_IOCtrl_Message	(	const char *	recv_buf,
		uint16_t	data_len
	)

Nebula Device handle IOCtrl message from Nebula Client.

This function for Nebula BLE Peripheral to handle IOCtrl message from Nebula BLE Central.

Parameters

recv_buf	[in] Data buffer
data_len	[in] Actual data length of recv_buf

Returns

NEBULA_ER_NoERROR for send message success

Error code if return value < 0

NEBULA_ER_NOT_INITIALIZE Service is not initialize
NEBULA_ER_BLE_DEVICE_NOT_READY Service is not start
NEBULA_ER_INVALID_ARG buffer pointer is NULL
NEBULA_ER_UNKNOW_MESSAGE IOCtrl message length is invalid

NEBULA_BLE_API int Nebula_BLE_Device_Send_User_IOCtrl_Message	(	NebulaIOCtrlType	user_define_type,
		const char *	user_data,
		uint16_t	user_data_len
	)

Nebula Device send user define IOCtrl message.

This function for Nebula BLE Peripheral to response user define IOCtrl request from Nebula BLE Central.

Parameters

user_define_type	[in] User defined type of NebulaIOCtrlType (257~65534)
user_data	[in] Data
user_data_len	[in] Length of user_data

Returns

NEBULA_ER_NoERROR for send message success

Error code if return value < 0

NEBULA_ER_NOT_INITIALIZE Service is not initialize
NEBULA_ER_BLE_DEVICE_NOT_READY Service is not start
NEBULA_ER_INVALID_ARG user_define_type is invalid
NEBULA_ER_BLE_CALLBACK_IS_NULL Callback function is invalid
#NEBULA_ER_BLE_UNKNOW_STATUTS Central number is invalid

NEBULA_BLE_API int Nebula_BLE_Device_Service_Start ( )

Nebula Device Start BLE service.

This function for Nebula BLE Peripheral to start Nebula BLE service and Characteristic .

Returns

NEBULA_ER_NoERROR for start service success

Error code if return value < 0

NEBULA_ER_NOT_INITIALIZE Service is not initialize
NEBULA_ER_FAIL_CREATE_THREAD Create thread fail

NEBULA_BLE_API int Nebula_BLE_Device_Service_Stop ( )

Nebula Device Stop BLE service.

This function for Nebula BLE Peripheral to stop Nebula BLE service and Characteristic.

Returns

NEBULA_ER_NoERROR for stop service success

Error code if return value < 0

NEBULA_ER_NOT_INITIALIZE Service is not initialize
NEBULA_ER_BLE_DEVICE_NOT_READY Service is not start

NEBULA_BLE_API int Nebula_BLE_Get_Characteristic_IOCtrl_Info	(	char *	uuid_buff,
		int	buff_length,
		uint8_t *	property
	)

Get Nebula BLE Characteristic UUID and property of IOCtrl message.

This function for Central and Peripheral to get Nebula IOCtrl message UUID.

Parameters

uuid_buff	[out] UUID of Characteristic
buff_length	[in] buffer length
property	[out] Bit field of property.

Returns

= NEBULA_ER_NoERROR for return UUID and property success

Error code if return value < 0

NEBULA_ER_INVALID_ARG for pointer is NULL

See Also: BLE_PROPERTY_BROADCAST, BLE_PROPERTY_READ, BLE_PROPERTY_WRITE_WITHOUT_RESPONSE, BLE_PROPERTY_WRITE, BLE_PROPERTY_NOTIFY, BLE_PROPERTY_INDICATE, BLE_PROPERTY_AUTH_WRITE, BLE_PROPERTY_EXTS

NEBULA_BLE_API int Nebula_BLE_Get_Service_Info	(	char *	uuid_buff,
		int	buff_length
	)

Get Nebula BLE Service UUID.

This function for Central and Peripheral to get Nebula service UUID.

Parameters

uuid_buff	[out] UUID of Service
buff_length	[in] buffer length

Returns

= NEBULA_ER_NoERROR for return UID success

Error code if return value < 0

NEBULA_ER_INVALID_ARG for pointer is NULL

Data Structures

Macros

Typedefs

Functions

Detailed Description

Macro Definition Documentation

Typedef Documentation

Function Documentation