Skip to content

8.1 Vendor Specific HCI Command Reference Tables

Jump to bottom Edit New page
hedy edited this page Mar 30, 2017 · 5 revisions

These tables are cross-references between the Vendor-Specific HCI Command and cc-bnp Command APIs. Here is the description of each column in the table:

  • BLE Vendor-Cmd
  • Cmd-API
    • The API name, in cc-bnp, according to a vendor-specific HCI command
  • Arguments
    • Required parameters of a Cmd-API
  • Result
    • Resulted data object passing to the Cmd-API callback.
    • For hci subgroup, this data object is with keys: { status, cmdOpcode, [other keys] }
    • For other subgroups, i.e. l2cap, att, gatt, gap, util, this data object is with keys: { status, opcode, dataLen, payload, collector }
  • Generated Event(s)
    • Events generated by the remote device will be collected as an object to collector property in the resulted data object. It is that the value of collector property is an object as well.
    • Each key in collector object represents the event type. The Generated Event(s) column will tell you of how many kinds of event types may be generated from the remote device.
    • Each value in collector object is an array of event-dependent data. (Since the same type of event may be generated more than one time from the remote device, an array is used to gather them up.)

Example

Let's take ccbnp.gap.deviceDiscReq() as an example. Here, I only take out something that we need from ccbnp.gap APIs table. The table down here tells that

BLE Vendor-Cmd Cmd-API Arguments Generated Event(s) - collector
GAP_DeviceDiscoveryRequest deviceDiscReq mode, activeScan, whiteList { [GapDeviceInfo], GapDeviceDiscovery }

  • This command is named as GAP_DeviceDiscoveryRequest in TI's HCI guide and is named as deviceDiscReq under the namespace gap in cc-bnp.

  • The required arguments to this Cmd-API are mode, activeScan, and whiteList listed in order.

  • The returned result is an object with keys { status, opcode, dataLen, payload, collector }, the table will tell you of what may appear in collector object by Generated Event(s).

  • collector is an object that may has a field GapDeviceInfo and will has a field GapDeviceDiscovery. The embraced [GapDeviceInfo] event type tells that such an event may not be generated from the remote device.

  • Here is an example of result object that passes to gap.deviceDiscReq API callback:

    {
    status: 0,  
    opcode: 65028,  
    dataLen: 0,
    payload: <Buffer >
    collector: {
        GapDeviceInfo: [        // collects the event-depenedent data of 'GapDeviceInfo' event type
            { 
                status: 0,
                eventType: 0,
                addrType: 0,
                addr: '0xd03972c3d10a',
                rssi: 216,
                dataLen: 31,
                dataField: <Buffer 02 01 05 03 02 10 ... > 
            },
            { 
                status: 0,
                eventType: 0,
                addrType: 0,
                addr: '0x9059af0b8159',
                rssi: 167,
                dataLen: 3,
                dataField: <Buffer 02 01 05> 
            }
        ],
        GapDeviceDiscovery: [   // collects the event-depenedent data of 'GapDeviceDiscovery' event type
            { 
                status: 0, 
                numDevs: 2, 
                devs: [ 
                    { evtType: 0, addrType: 0, addr: '0xd03972c3d10a' }, 
                    { evtType: 0, addrType: 0, addr: '0x9059af0b8159' } 
                ]
            }
        ]
    }
}


8.1.1 ccbnp.hci APIs

  • Result object: { status, cmdOpcode, [other keys] }
  • hci commands mainly interact with the local ble network processor(BNP). There is no event from remote devices and hence there will be no collector property in the result object.
BLE Vendor-Cmd Cmd-API Arguments Result Object
HCI_EXT_SetRxGainCmd setRxGain rxGain { status, cmdOpcode }
HCI_EXT_SetTxPowerCmd setTxPower txPower { status, cmdOpcode }
HCI_EXT_OnePacketPerEventCmd onePktPerEvt control {status, cmdOpcode }
HCI_EXT_ClkDivOnHaltCmd clkDivideOnHalt control { status, cmdOpcode }
HCI_EXT_DeclareNvUsageCmd declareNvUsage mode { status, cmdOpcode }
HCI_EXT_DecryptCmd decrypt key, encText { status, cmdOpcode, plainTextData }
HCI_EXT_SetLocalSupportedFeaturesCmd setLocalSupportedFeatures localFeatures { status, cmdOpcode }
HCI_EXT_SetFastTxResponseTimeCmd setFastTxRespTime control { status, cmdOpcode }
HCI_EXT_ModemTestTxCmd modemTestTx cwMode, txFreq { status, cmdOpcode }
HCI_EXT_ModemHopTestTxCmd modemHopTestTx none { status, cmdOpcode }
HCI_EXT_ModemTestRxCmd modemTestRx rxFreq { status, cmdOpcode }
HCI_EXT_EndModemTestCmd endModemTest none { status, cmdOpcode }
HCI_EXT_SetBDADDRCmd setBdaddr bdAddr { status, cmdOpcode }
HCI_EXT_SetSCACmd setSca scalnPPM { status, cmdOpcode }
HCI_EXT_EnablePTMCmd enablePtm none { status, cmdOpcode }
HCI_EXT_SetFreqTuneCmd setFreqTune step { status, cmdOpcode }
HCI_EXT_SaveFreqTuneCmd saveFreqTune none { status, cmdOpcode }
HCI_EXT_SetMaxDtmTxPowerCmd setMaxDtmTxPower txPower { status, cmdOpcode }
HCI_EXT_MapPmInOutPortCmd mapPmIoPort ioPort, ioPin { status, cmdOpcode }
HCI_EXT_DisconnectImmedCmd disconnectImmed connHandle { status, cmdOpcode }
HCI_EXT_PacketErrorRateCmd per connHandle, cmd { status, cmdOpcode, cmdVal, numPkts, numCrcErr, numEvents, numMissedEvents }
HCI_EXT_PERbyChanCmd perByChan connHandle, perByChan { status, cmdOpcode }
HCI_EXT_ExtendRfRangeCmd extendRfRange none { status, cmdOpcode }
HCI_EXT_AdvEventNoticeCmd advEventNotice taskId, cmd { status, cmdOpcode }
HCI_EXT_ConnEventNoticeCmd connEventNotice taskId, taskEvt { status, cmdOpcode }
HCI_EXT_HaltDuringRfCmd haltDuringRf mode { status, cmdOpcode }
HCI_EXT_SetSlaveLatencyOverrideCmd overrideSl taskId { status, cmdOpcode }
HCI_EXT_BuildRevisionCmd buildRevision mode, userRevNum { status, cmdOpcode, userRevNum, buildRevNum }
HCI_EXT_DelaySleepCmd delaySleep delay { status, cmdOpcode }
HCI_EXT_ResetSystemCmd resetSystem mode { status, cmdOpcode }
HCI_EXT_OverlappedProcessingCmd overlappedProcessing mode { status, cmdOpcode }
HCI_EXT_NumComplPktsLimitCmd numCompletedPktsLimit limit, flushOnEvt { status, cmdOpcode }


8.1.2 ccbnp.l2cap APIs

  • Result object: { status, opcode, dataLen, payload, collector }
  • Generated Event(s) will be collected as key-value pairs within the collector object.
BLE Vendor-Cmd Cmd-API Arguments Generated Event(s)
L2CAP_ConnParamUpdateReq paramUpdateReq connHandle, intervalMin, intervalMax, slaveLatency, timeoutMultiplier { L2capParamUpdateRsp }


8.1.3 ccbnp.att APIs

  • Result object: { status, opcode, dataLen, payload, collector }
  • Generated Event(s) will be collected as key-value pairs within the collector object.

Note: The embraced [uuid] argument is to help ccbnp with building the packet. If uuid is not provided and is not registered by regUuidHdlTable() to a Characteristic handle-to-UUID mapping table, ccbnp will automatically initiate a remote request for the characteristic uuid.

BLE Vendor-Cmd Cmd-API Arguments Generated Event(s)
ATT_ErrorRsp errorRsp connHandle, reqOpcode, handle, errCode none
ATT_ExchangeMtuReq exchangeMtuReq connHandle, clientRxMTU { AttExchangeMtuRsp }
ATT_ExchangeMtuRsp exchangeMtuRsp connHandle, serverRxMTU none
ATT_FindInfoReq findInfoReq connHandle, startHandle, endHandle { AttFindInfoRsp }
ATT_FindInfoRsp findInfoRsp connHandle, format, info none
ATT_FindByTypeValueReq findByTypeValueReq connHandle, startHandle, endHandle, type, value { AttFindByTypeValueRsp }
ATT_FindByTypeValueRsp findByTypeValueRsp connHandle, handlesInfo none
ATT_ReadByTypeReq readByTypeReq connHandle, startHandle, endHandle, type { AttReadByTypeRsp }
ATT_ReadByTypeRsp readByTypeRsp connHandle, length, data, [uuid] none
ATT_ReadReq readReq connHandle, handle, [uuid] { AttReadRsp }
ATT_ReadRsp readRsp connHandle, value, [uuid] none
ATT_ReadBlobReq readBlobReq connHandle, handle, offset { AttReadBlobRsp }
ATT_ReadBlobRsp readBlobRsp connHandle, value none
ATT_ReadMultiReq readMultiReq connHandle, handles, [uuid] { AttReadMultiRsp }
ATT_ReadMultiRsp readMultiRsp connHandle, value, [uuid] none
ATT_ReadByGrpTypeReq readByGrpTypeReq connHandle, startHandle, endHandle, type { AttReadByGrpTypeRsp }
ATT_ReadByGrpTypeRsp readByGrpTypeRsp connHandle, length, data none
ATT_WriteReq writeReq connHandle, signature, command, handle, value, [uuid] { AttWriteRsp }
ATT_WriteRsp writeRsp connHandle none
ATT_PrepareWriteReq prepareWriteReq connHandle, handle, offset, value { AttPrepareWriteRsp }
ATT_PrepareWriteRsp prepareWriteRsp connHandle, handle, offset, value none
ATT_ExecuteWriteReq executeWriteReq connHandle, flags { AttExecuteWriteRsp }
ATT_ExecuteWriteRsp executeWriteRsp connHandle none
ATT_HandleValueNoti handleValueNoti connHandle, authenticated, handle, value, [uuid] none
ATT_HandleValueInd handleValueInd connHandle, authenticated, handle, value, [uuid] { AttHandleValueCfm }
ATT_HandleValueCfm handleValueCfm connHandle none


8.1.4 ccbnp.gatt APIs

  • Result object: { status, opcode, dataLen, payload, collector }
  • Generated Event(s) will be collected as key-value pairs within the collector object.

Note: The embraced [uuid] argument is to help ccbnp with building the packet. If uuid is not provided and is not registered by regUuidHdlTable() to a Characteristic handle-to-UUID mapping table, ccbnp will automatically initiate a remote request for the characteristic uuid.

BLE Vendor-Cmd Cmd-API Arguments Generated Event(s)
GATT_ExchangeMtu exchangeMtu connHandle, clientRxMTU { AttExchangeMtuRsp }
GATT_DiscAllPrimaryServices discAllPrimaryServices connHandle { AttReadByGrpTypeRsp }
GATT_DiscPrimaryServiceByUuid discPrimaryServiceByUuid connHandle, value, [uuid] { AttFindByTypeValueRsp }
GATT_FindIncludedServices findIncludedServices connHandle, startHandle, endHandle { AttReadByTypeRsp }
GATT_DiscAllChars discAllChars connHandle, startHandle, endHandle { AttReadByTypeRsp }
GATT_DiscCharsByUuid discCharsByUuid connHandle, startHandle, endHandle, type { AttReadByTypeRsp }
GATT_DiscAllCharDescs discAllCharDescs connHandle, startHandle, endHandle { AttFindInfoRsp }
GATT_ReadCharValue readCharValue connHandle, handle, [uuid] { AttReadRsp }
GATT_ReadUsingCharUuid readUsingCharUuid connHandle, startHandle, endHandle, type { AttReadByTypeRsp }
GATT_ReadLongCharValue readLongCharValue connHandle, handle, offset { AttReadBlobRsp }
GATT_ReadMultiCharValues readMultiCharValues connHandle, handles { AttReadMultiRsp }
GATT_WriteNoRsp writeNoRsp connHandle, handle, value, [uuid] none
GATT_SignedWriteNoRsp signedWriteNoRsp connHandle, handle, value, [uuid] none
GATT_WriteCharValue writeCharValue connHandle, handle, value, [uuid] { AttWriteRsp }
GATT_WriteLongCharValue writeLongCharValue connHandle, handle, offset, value { [AttPrepareWriteRsp], AttExecuteWriteRsp }
GATT_ReliableWrites reliableWrites connHandle, numberRequests, requests { [AttPrepareWriteRsp], AttExecuteWriteRsp }
GATT_ReadCharDesc readCharDesc connHandle, handle { AttReadRsp }
GATT_ReadLongCharDesc readLongCharDesc connHandle, handle, offset { AttReadBlobRsp }
GATT_WriteCharDesc writeCharDesc connHandle, handle, value, [uuid] { AttWriteRsp }
GATT_WriteLongCharDesc writeLongCharDesc connHandle, handle, offset, value { [AttPrepareWriteRsp], AttExecuteWriteRsp }
GATT_Notification notification connHandle, authenticated, handle, value, [uuid] none
GATT_Indication indication connHandle, authenticated, handle, value, [uuid] { AttHandleValueCfm }
GATT_AddService addService uuid, numAttrs none
GATT_DelService delService handle none
GATT_AddAttribute addAttribute uuid, permissions none


8.1.5 ccbnp.gap APIs

  • Result object: { status, opcode, dataLen, payload, collector }
  • Generated Event(s) will be collected as key-value pairs within the collector object.
BLE Vendor-Cmd Cmd-API Arguments Generated Event(s)
GAP_DeviceInit deviceInit profileRole, maxScanResponses, irk, csrk, signCounter { GapDeviceInitDone }
GAP_ConfigDeviceAddr configDeviceAddr bitMask, addr { GapRandomAddrChanged }
GAP_DeviceDiscoveryRequest deviceDiscReq mode, activeScan, whiteList { [GapDeviceInfo], GapDeviceDiscovery }
GAP_DeviceDiscoveryCancel deviceDiscCancel none { GapDeviceDiscovery }
GAP_MakeDiscoverable makeDiscoverable eventType, initiatorAddrType, initiatorAddr, channelMap, filterPolicy { GapMakeDiscoverableDone, GapEndDiscoverableDone }
GAP_UpdateAdvertisingData updateAdvData adType, daraLen, advertData { GapAdvDataUpdateDone }
GAP_EndDiscoverable endDisc none { GapEndDiscoverableDone }
GAP_EstablishLinkRequest estLinkReq highDutyCycle, whiteList, addrtypePeer, peerAddr { GapLinkEstablished }
GAP_TerminateLinkRequest terminateLink connHandle, reason { GapLinkTerminated }
GAP_Authenticate authenticate connHandle, secReq_ioCaps, secReq_oobAvailable, secReq_oob, secReq_authReq, secReq_maxEncKeySize, secReq_keyDist, pairReq_Enable, pairReq_ioCaps, pairReq_oobDataFlag, pairReq_authReq, pairReq_maxEncKeySize, pairReq_keyDist { GapAuthenticationComplete }
GAP_UpdateLinkParamReq updateLinkParamReq connHandle, intervalMin, intervalMax, connLatency, connTimeout { GapLinkParamUpdate }
GAP_PasskeyUpdate passkeyUpdate connHandle, passkey none
GAP_SlaveSecurityRequest slaveSecurityReqUpdate connHandle, authReq none
GAP_Signable signable connHandle, authenticated, csrk, signCounter none
GAP_Bond bond connHandle, authenticated, ltk, div, rand, ltkSize { GapBondComplete }
GAP_TerminateAuth terminateAuth connHandle, reason { GapAuthenticationComplete }
GAP_SetParam setParam paramID, paramValue none
GAP_GetParam getParam paramID none
GAP_ResolvePrivateAddr resolvePrivateAddr irk, addr none
GAP_SetAdvToken setAdvToken adType, advDataLen, advData none
GAP_RemoveAdvToken removeAdvToken adType none
GAP_UpdateAdvToken updateAdvTokens none none
GAP_BondSetParam bondSetParam paramID, paramDataLan, paramData none
GAP_BondGetParam bondGetParam paramID none


8.1.6 ccbnp.util APIs

  • Result object: { status, opcode, dataLen, payload, collector }
  • Generated Event(s) will be collected as key-value pairs within the collector object.
BLE Vendor-Cmd Cmd-API Arguments Generated Event(s)
UTIL_NVRead nvRead nvID, nvDataLen none
UTIL_NVWrite nvWrite nvID, nvDataLen, nvData none
UTIL_ForceBoot forceBoot none none


8.1.7 Vendor-Specific HCI Events (Generated Event Types)

Subgroup BLE Vendor-Evt Generated Event Type Data Object
l2cap L2CAP_ConnParamUpdateRsp L2capParamUpdateRsp { status, connHandle, reason }
att ATT_ExchangeMtuRsp AttExchangeMtuRsp { status, connHandle, pduLen, serverRxMTU }
ATT_FindInfoRsp AttFindInfoRsp { status, connHandle, pduLen, format, info }
ATT_FindByTypeValueRsp AttFindByTypeValueRsp { status, connHandle, pduLen, handlesInfo }
ATT_ReadByTypeRsp AttReadByTypeRsp { status, connHandle, pduLen, length, data }
ATT_ReadRsp AttReadRsp { status, connHandle, pduLen, value }
ATT_ReadBlobRsp AttReadBlobRsp { status, connHandle, pduLen, value }
ATT_ReadMultiRsp AttReadMultiRsp { status, connHandle, pduLen, value }
ATT_ReadByGrpTypeRsp AttReadByGrpTypeRsp { status, connHandle, pduLen, length, data }
ATT_WriteRsp AttWriteRsp { status, connHandle, pduLen }
ATT_PrepareWriteRsp AttPrepareWriteRsp { status, connHandle, pduLen, handle, offset, value }
ATT_ExecuteWriteRsp AttExecuteWriteRsp { status, connHandle, pduLen }
ATT_HandleValueCfm AttHandleValueCfm { status, connHandle, pduLen }
gap GAP_DeviceInitDone GapDeviceInitDone { status, devAddr, dataPktLen, numDataPkts, IRK, CSRK }
GAP_DeviceDiscovery GapDeviceDiscovery { status, numDevs, devs }
GAP_AdvertDataUpdateDone GapAdvDataUpdateDone { status, adType }
GAP_MakeDiscoverableDone GapMakeDiscoverableDone { status, interval }
GAP_EndDiscoverableDone GapEndDiscoverableDone { status }
GAP_LinkEstablished GapLinkEstablished { status, addrType, addr, connHandle, connRole, connInterval, connLatency, connTimeout, clockAccuracy }
GAP_LinkTerminated GapLinkTerminated { status, connHandle, reason }
GAP_LinkParamUpdate GapLinkParamUpdate { status, connHandle, connInterval, connLatency, connTimeout }
GAP_RandomAddrChanged GapRandomAddrChanged { status, addrType, newRandomAddr }
GAP_AuthenticationComplete GapAuthenticationComplete { status, connHandle, authState, secInfo, sec_ltkSize, sec_ltk, sec_div, sec_rand, devSecInfo, dev_ltkSize, dev_ltk, dev_div, dev_rand, identityInfo, identity_irk, identity_bd_addr, signingInfo, signing_irk, signing_signCounter }
GAP_DeviceInformation GapDeviceInfo { status, eventType, addrType, addr, rssi, dataLen, dataField }
GAP_BondComplete GapBondComplete { status, connHandle }
Add a custom footer

1. Overview
2. BLE Network Processor
3. Installation
4. Usage
5. Basic APIs

6. TI's BLE Vendor-Specific HCI Command APIs
7. Events

8. Appendix

Clone this wiki locally