www.beck-ipc.com

BtLib V2.02 - Status / Initialization


Status / Initialization

Functions needed for initialization, status information, or mode changes

  • btIsConnected
  • btGetPort
  • btInit
  • btDeInit
  • btGetMajorDeviceClass
  • btSetMode
  • btReadLocalBDAddr
  • btReadLocalVersionInformation
  • btSendAT
  • btGetATLineWithTimeout
  • btGetATLine
  • btGetVersion
  • btGetModuleID


  • int btIsConnected(void)

    Returns true (1) on established connection, otherwise false (0).
    To use this feature the DTR-pin must be configured to be active only if there's a existing bluetooth connection. (see btWriteDtrDsrSettings).
    Otherwise the function will always return true.

    Return Value

    Returns one of the following

    >0
    On established connection to other bluetooth device, or PIO marked as not used at chip.ini (value -1).

    0
    On no established connection to other bluetooth device

    Comments

    Since version 1.08 this function returns >0, if the DTR pin is not defined. Before it returned 0 in this case.


    Top
    Index page


    int btGetPort(void)

    Returns the port to use for the fossil API for sending and receiving data on a serial port profile (SPP) bluetooth connection.

    Return Value

    Returns fossil port

    Example

    Using an established serial port profile bluetooth connection

    // establish connection
    
    // now send some data
    fossil_putbyte(btGetPort(), byte);
    

    Top
    Index page


    int btInit( void)

    Initializes and opens the serial port of the IPC@CHIP. Reads port, baudrate, stopbits, wordlength, parity, flow control from chip.ini for connecting to the BT0x . Reads also the PIOs and the escape sequence times and escape character for switching to AT mode with btSetMode.
    For chip.ini constants look at chip.ini_entries_and_values.
    This function must be executed, before calling any other API function.

    Parameters

    void

    Return Value

    Returns one of the following

    BT_EXIT_SUCCESS
    Successful reading the variables and opening the serial port.

    BT_EXIT_FAILURE
    On Error

    BT_CHIP_INI_ENTRY_ERROR
    On incorrect entry in chip.ini

    BT_INVALID_MODULE_ERROR
    Module is not a Beck IPC Bluetooth device

    BT_CONNECTION_TO_CHIP_ERROR
    Communication fault

    Comment

    If there's no matching entry, the following values will be set by default

    port          = FOSSIL_SER2 (SC1x3/SC2x) or  FOSSIL_UART6 (SC243)
    baudrate      = 57600
    parity        = FOSSIL_PARITY_NO (0x00)
    wordlength    = 8
    stopbits      = 1
    flowcontrol   = FOSSIL_FLOWCTRL_RTSCTS (0x02)
    escChar       = BT_DEFAULT_ESC_CHAR ('/')
    minBeforeTime = BT_DEFAULT_MIN_BEFORE_TIME (1000)
    minAfterTime  = BT_DEFAULT_MIN_AFTER_TIME (1000)
    connStatusPio = BT_DEFAULT_CONN_STATUS_PIO
    connDSRPio    = BT_DEFAULT_CONN_DSR_PIO
    resetpio      = BT_DEFAULT_RESETPIO
    

    Top
    Index page


    void btDeInit(void)

    Closes the serial port the BT0x is connected to. It holds the BT0x device in the reset state by setting the reset pio to low.

    Return Value

    none


    Top
    Index page


    int btGetMajorDeviceClass(long cod)

    Returns only the bits necessary for determining the major device class (computer, phone, peripheral, ...) of a bluetooth device by a given cod (class of device). The major device class is represented by the bits 8-12 in the cod bit array.

    Parameters

    cod

    Class of device containing the major device class

    Return Value

    Major device class

    Comment

    List of possible values:

    case  0: Miscellaneous
    case  1: Computer (desktop, notebook, PDA, etc)
    case  2: Phone (cellular, cordless, modem, etc)
    case  3: LAN/Network Access point
    case  4: Audio/Video (headset, speaker, stereo, video display, VCR)
    case  5: Peripheral (mouse, joystick, keyboards)
    case  6: Imaging (printing, scanner, camera, etc)
    case 31: Uncategorized, specific device code not specified
    

    Top
    Index page


    int btSetMode(unsigned int mode)

    Switches the BT module to AT MODE or DATA MODE.

    Parameters

    mode

    BT_AT_MODE or BT_DATA_MODE

    Return Value

    Returns one of the following

    BT_EXIT_SUCCESS
    On success

    BT_EXIT_FAILURE
    On Error

    BT_CONNECTION_TO_CHIP_ERROR
    BT0x module not detected or timeout

    BT_CHIP_ERROR
    Bluetooth module returns an error message (no further information available)


    Top
    Index page


    int btReadLocalBDAddr(char* bdAddr)

    Reads the local Bluetooth device address.

    Parameters

    bdAddr

    Output parameter: '\0' terminated BT address of the local BT device. BT address ist always 12 chars long, so bdAddr must be at least 13 byte long.

    Return Value

    Returns one of the following

    BT_EXIT_SUCCESS
    On success

    BT_CONNECTION_TO_CHIP_ERROR
    BT0x module not detected or timeout

    BT_REPLY_PARSE_ERROR
    Invalid reply received from the device

    BT_CHIP_ERROR
    Bluetooth module returns an error message (no further information available)


    Top
    Index page


    int btReadLocalVersionInformation(struct BluetoothVersion * versionData)

    Reads different version information of the local bluetooth module.

    Parameters

    versionData

    Output parameter: Pointer to BluetoothVersion data structure which will be filled by this call.

    Return Value

    Returns one of the following

    BT_EXIT_SUCCESS
    On success

    BT_CONNECTION_TO_CHIP_ERROR
    BT0x module not detected or timeout

    BT_REPLY_PARSE_ERROR
    Invalid reply received from the device

    BT_CHIP_ERROR
    Bluetooth module returns an error message (no further information available)


    Top
    Index page


    int btSendAT(const char * input)

    This function sends AT commands to the BT0x.

    Parameters

    input

    AT command to execute

    Return Value

    Returns one of the following

    BT_EXIT_SUCCESS
    On success

    BT_CONNECTION_TO_CHIP_ERROR
    BT0x module not detected or timeout

    Comments

    Remember to read the output of the BT0x by calling btGetATLine or btGetATLineWithTimeout otherwise the output will be deleted on another call (see example).

    Example

    send "AT" and receive answers

    // sending simple "AT"
    retval = btSendAT("AT");
    if (retval == BT_EXIT_SUCCESS)
    {
      // receive echo of the command
      retval = btGetATLine(btATLineBuf);
      if (retval == BT_EXIT_SUCCESS)
      {
        retval = btGetATLine(btATLineBuf);
        if (retval == BT_EXIT_SUCCESS)
        {
          if (strcmp(btATLineBuf, ok) == 0)
          {
    	// command sucessful
    	return BT_EXIT_SUCCESS;
          }
          // otherwise return error code
          return BT_CHIP_ERROR;
        }
      }
    }
    return retval;
    

    Top
    Index page


    int btGetATLineWithTimeout(char * ATLINE, const unsigned long timeout)

    This function returns the next line of the answer of the BT0x.

    Parameters

    ATLINE

    Output parameter: array of char with size BT_MAX_LINE_LENGTH

    timeout

    Time to wait (in ms) for an output line before sending a BT_CONNECTION_TO_CHIP_ERROR.

    Return Value

    Returns one of the following

    BT_EXIT_SUCCESS
    On success

    BT_OUT_OF_MEMORY_ERROR
    Insufficient internal storage

    BT_CHIP_ERROR
    Bluetooth module returns an error message (no further information available)

    BT_CONNECTION_TO_CHIP_ERROR
    BT0x module not detected or timeout

    Comments

    See btSendAT for example
    It is strongly required to use this function as described at the provided btSendAT example.


    Top
    Index page


    int btGetATLine(char * ATLINE)

    This function returns the next line of the answer of the BT0x waiting for it for the default timeout time (BT_DEFAULT_TIMEOUT).

    Parameters

    ATLINE

    Output parameter: array of char with size BT_MAX_LINE_LENGTH

    Return Value

    Returns one of the following

    BT_EXIT_SUCCESS
    On success

    BT_CHIP_ERROR
    Bluetooth module returns an error message (no further information available)

    BT_CONNECTION_TO_CHIP_ERROR
    BT0x module not detected or timeout

    Comments

    see btSendAT for example


    Top
    Index page


    unsigned short btGetVersion(void)

    This function returns the version number of the BtLib

    Return Value

    Returns a 16 Bit version number

    Comments

    A return value of 0x103 means version 1.03.


    Top
    Index page


    int btGetModuleID(void)

    This returns device ID, if available.

    Return Value

    -1: ID not detected (function not supported by BT firmware)
    1: Module is BT01 or BT02
    2: BT03/4
    4: BT05/6


    Top
    Index page


    End of document