_äìéi~ä» Implementing Streams in BlueLab User Guide November 2006 CSR Cambridge Science Park Milton Road Cambridge CB4 0WH United Kingdom Registered in England 4187346 Tel: +44 (0)1223 692000 Fax: +44 (0)1223 692001 www.csr.com
Contents Contents 1 Introduction... 3 1.1 General... 3 1.1.1 Sinks and Sources... 3 1.1.2 Connecting Sinks and Sources...4 2 Obtaining Sources and Sinks... 5 2.1 Introduction... 5 2.1.1 General... 5 2.1.2 RFCOMM... 6 2.1.3 L2CAP... 6 2.1.4 PCM... 6 2.1.5 SCO... 7 2.1.6 Host... 7 2.1.7 UART... 7 2.1.8 Kalimba... 8 2.1.9 USB... 9 2.1.10 HID... 10 2.1.11 Audio... 10 2.1.12 Region... 11 2.1.13 File... 11 2.1.14 Bluetooth address... 12 2.1.15 Source... 12 2.1.16 Sink... 13 3 Direct Connections... 14 3.1 General... 14 3.2 Use of StreamConnect... 14 3.2.1 StreamConnect... 14 3.2.2 StreamConnectDispose... 15 3.2.3 StreamConnectAndDispose... 15 3.2.4 StreamDisconnect... 16 4 Managed Connections... 17 4.1 Functions... 17 4.1.1 Sinks... 17 4.1.2 Sources... 20 4.1.3 Example Code... 22 4.2 StreamMove... 23 5 Configuring Sources, Sinks and Streams... 24 5.1 General... 24 5.1.1 SinkConfigure... 24 5.1.2 SourceConfigure... 24 5.1.3 StreamConfigure... 25 5.1.4 HID Configuration... 25 6 Technical Support... 27 7 Document References... 28 Appendix A Stream Sink/Source Compatibility... 29 Terms and Definitions... 30 Document History... 31 Page 2 of 31
Introduction 1 Introduction This document describes the use of streams in BlueLab applications. Note: Read this document in conjunction with the Reference documentation in the xide on-line help, which documents the full range of BlueLab library functions. Streams provide an efficient method of transferring data in BlueLab applications. They can be used to transfer data across the air between connected Bluetooth devices, along a wire between processors in the device or internally on the chip. The BlueLab libraries provide functions for efficiently handling 8-bit data streams. 1.1 General BlueLab distinguishes the following stream types: RFCOMM - Serial Cable Emulation Protocol L2CAP - Logical Link Control and Adaptation Protocol SCO - Synchronous Connection Oriented link Host (BCSP - BlueCore Serial Protocol) PCM - Pulse Code Modulation hardware port Serial port (raw UART) Kalimba port - Digital Signal Processor (DSP) USB - Universal Serial Bus HID - Human Interface Device Audio (source only) Region (source only) Files (source only) 1.1.1 Sinks and Sources Each stream is normally associated with both a sink and a source. Data can be written to a sink and read from a source. When a sink and source are connected, data streams form the source to the sink. With some exceptions (see Appendix A Table A.1), the sink associated with one stream can be connected to the source associated with another and data can be streamed between them, i.e. data will stream from a source to the connected sink. BlueLab provides developers with functions to obtain, configure and connect sinks and sources. Page 3 of 31
Introduction 1.1.2 Connecting Sinks and Sources For data to flow between a sink and a source the two must be connected. BlueLab allows for two basic methods of connecting sinks and sources: 1. A direct connection: no data control is provided. i.e. data flows consistently and is not visible to the application. See chapter 3. 2. A managed connection: the application calls a sequence of functions to handle the streaming of data. See chapter 4. This method gives the application visibility of the data held in sinks and sources, allowing the stream to be controlled by the application. For example if the data arriving at the source is not being flushed, the sink is eventually unable to stream more data as the sink s buffer becomes full. In managed connections the application is aware of this and can stop writing to the sink until more space is available. Page 4 of 31
Obtaining Sources and Sinks 2 Obtaining Sources and Sinks 2.1 Introduction This section describes the functions declared in the sink.h and source.h header files that are used to obtain sinks and sources that can then be connected to stream data. 2.1.1 General Functions that return sources and sinks such as StreamUartSource()and StreamRfcommSink() use the special return value of zero to indicate failure. This is possible because both the source and sink types are actually opaque pointers, i.e. the pointer can be used to manipulate the source or sink without needing to know its structure. The importance of returning zero on failure is that it allows the code to check for failure using the PanicFalse function. This technique can also be used for function calls that return a Boolean flag such as StreamConnect(). This allows engineers to check for success using PanicFalse, in the application code, for example: (void) PanicFalse(StreamConnect(StreamUartSource(),StreamRfcommSink())); In this example if the sink and source are valid and connected successfully the application continues to run. If the connection is unsuccessful the application panics. The functions to obtain sinks and sources can be considered in pairs, one of which obtains the sink and one the source. In most cases, streams are implemented as bi-directional and so the StreamConnect function is called twice when setting up a stream: For example: /* Make sure we have a valid source/ sink */ if (!SinkIsValid(sco_sink)!SourceIsValid(StreamSourceFromSink(sco_sink))) return FALSE; /* Set up the PCM rate and routing*/ (void) PanicFalse(PcmRateAndRoute(0, PCM_NO_SYNC, (uint32) 8000, (uint32) 8000, VM_PCM_INTERNAL_A_AND_B)); /* Connect the SCO to the PCM */ (void) PanicFalse(StreamConnect(StreamSourceFromSink(sco_sink), StreamPcmSink(0))); (void) PanicFalse(StreamConnect(StreamPcmSource(0), sco_sink)); Sections 2.1.2 to 2.1.16 describe the functions available in BlueLab to obtain sinks and sources: Page 5 of 31
Obtaining Sources and Sinks 2.1.2 RFCOMM s Source StreamRfcommSource (uint8 mux_id, uint8 server_chan) Sink StreamRfcommSink (uint8 mux_id, uint8 server_chan) mux_id: multiplexer id server_chan: server channel (See the Bluetooth Specification Part F:1 RFCOMM with TS 07.10 for further information. This can be downloaded from www.bluetooth.org.) These functions return the source and sink associated with the RFCOMM channel specified, if available. They return zero if the channel is unknown or has not been established, or if stream-based RFCOMM is not enabled. Note: These functions are not frequently used in BlueLab applications because the Connection library, which handles creating connections between devices, generates CFM messages that return the sink associated with the connection. 2.1.3 L2CAP s Source StreamL2capSource (uint16 cid) Sink StreamL2capSink (uint16 cid) cid: the connection id for the L2CAP connection whose source or sink is returned. These functions return the source and sink associated with an L2CAP connection. 2.1.4 PCM s Note: These functions are not frequently used in BlueLab applications because the Connection library, which handles connections between devices, generates CFM messages that return the sink associated with the connection. Source StreamPcmSource (uint16 port) Sink StreamPcmSink (uint16 port) port: the PCM port number for the PCM stream whose source or sink is returned. This must be in the range 0 to 3. These functions return the source and sink associated with a PCM stream. Page 6 of 31
Obtaining Sources and Sinks 2.1.5 SCO s Source StreamScoSource (uint16 handle) Sink StreamScoSink (uint16 handle) handle: the SCO handle (identifying the audio connection) whose source or sink is returned. These functions return the source and sink associated with a SCO stream. In practice these functions are rarely used in BlueLab applications because the sink is passed to the application task in _CFM messages and can be used directly and to find the source using StreamSourceFromSink(). 2.1.6 Host s Source StreamHostSource (uint16 channel) Sink StreamHostSink (uint16 channel) channel: the channel identifying the Host stream whose source or sink is returned. This must be in the range 0 to 256. These functions return the source and sink for the specified stream-based BCSP on channel 13. 2.1.7 UART s Source StreamUartSource (void) Sink StreamUartSink (void) These functions return the source and sink associated with the (raw) serial port, if available. For these calls to be successful Host transport must be selected as raw UART. If it is not these functions return zero. Note: The setting in the xide Project Properties Transport field configures the Host transport on boot up and must be set to raw to use these functions. Page 7 of 31
Obtaining Sources and Sinks 2.1.8 Kalimba s Source StreamKalimbaSource (uint16 port) Sink StreamKalimbaSink (uint16 port) port: the port number for the Kalimba stream whose source or sink is returned. This must be in the range 0 to 3. These functions return the source and sink for a Kalimba stream on the specified port. Page 8 of 31
Obtaining Sources and Sinks 2.1.9 USB Access to the on-chip USB interface occurs through channels known as endpoints and must comply with the device enumeration procedures detailed in the USB specification. It is therefore, not as simple to implement USB streams and a reasonable understanding of the enumeration process is required. Note: Functions connected with the enumeration of USB endpoints are described in the usb.h documentation in the xide on-line Reference documentation. As a result of the nature of USB communication and control there are three types of source and sink associated with USB streams: UsbClass s Source StreamUsbClassSource (UsbInterface interface) Sink StreamUsbClassSink (UsbInterface interface) interface: the USB interface whose source or sink is returned. These functions return the USB Class Request source and sink associated with corresponding USB interface. This communication channel passes commands defined in the USB class specification. Generally, these are involved in configuration procedures. UsbEndPoint s Source StreamUsbEndPointSource (EndPoint end_point) Sink StreamUsbEndPointSink(EndPoint end_point) end_point: the USB endpoint of the source or sink to be returned. These functions return the source and sink for the USB endpoint. These are used for the general flow of data across the USB connection. UsbVendor s Source StreamUsbVendorSource (void) Sink StreamUsbVendorSink (void) These functions return the USB Vendor source and sink. These pass vendor-specific commands not defined in the USB class specification. Page 9 of 31
Obtaining Sources and Sinks 2.1.10 HID HID s Source StreamHidSource (void) Sink StreamHidSink (void) These functions obtain the primary source and sink for HID. These are generally used to handle sensor data that is specified in the Bluetooth HID specifications. Before the source or sink can be used, the source has to be configured for the correct sensor type. See section 5.1.4 for the prototypes available to do this. HidAux s Source StreamHidAuxSource (void) Sink StreamHidAuxSink (void) These functions obtain the source and sink to handle auxiliary sensor data. In general, this data is connected via the VM rather than the firmware. One example of usage is to handle media keys on a keyboard matrix. 2.1.11 Audio Source StreamAudioSource (const audio_note *audio) audio: pointer to an array of audio notes whose source will be returned. This function returns the source with the contents of the memory pointed to by audio_note. Code Example The following code snippet describes a typical usage of this function: /* Set up the PCM routing */ (void) PanicFalse(PcmRateAndRoute(0, PCM_NO_SYNC, (uint32) 8000, (uint32) 8000, VM_PCM_INTERNAL_A_AND_B)); /* Create an audio source */ Source stream_source = StreamAudioSource(tone); /* Connect the source to the PCM */ StreamConnectAndDispose(stream_source, StreamPcmSink(0)); /* When the PCM finishes playing the tone send a message to the task below */ MessageSinkTask ( StreamPcmSink(0), &app->thesoundtask ); Page 10 of 31
Obtaining Sources and Sinks 2.1.12 Region Source StreamRegionSource (const uint8 *data uint16 length) data: the memory location that the source is created from. length: the size of the memory region. This function allows a region of memory to be treated as a source. This is useful when there is a requirement to handle data (held in a known region of memory) using functions that expect a source e.g StreamConnect in order to efficiently transfer the data without having to copy it. Note: It is important that the memory being treated as a source persists long enough for the stream to complete, i.e. long enough for the source to be read. The source created using this function only exists while the data is being read. However, the memory block being treated as a source is not freed by the stream sub system once the data has been read. It is therefore the engineer s responsibility to manage the memory and free it when it is appropriate to do so. If the length parameter is passed as zero then the return value will be zero. 2.1.13 File Source StreamFileSource (FILE_INDEX index) Parameter index: the file index identifier for the file whose contents are required. This function returns a source with the contents of a specified file stored in the read-only file system of BlueCore s VM (Virtual Machine). It returns zero if the index is FILE_NONE or does not correspond to a narrow file i.e. a file with 8-bit data. Further information on access to the read-only file system is found in the file.h documentation in the xide online Reference documentation. Page 11 of 31
Obtaining Sources and Sinks 2.1.14 Bluetooth address bool StreamSinksFromBdAddr (uint16 *max, Sink *sinks Const bdaddr *bt_address) max: stores up to max sinks in the array specified and updates the pointer. sinks: pointer to the array that stores the sinks returned. bt_address: pointer to the Bluetooth address of the remote device. This function returns all the sinks associated with an ACL connection to a remote device, identified by a specified Bluetooth address. Code Example The following code snippet describes a typical usage of this function: uint16 max_sinks = 6; /* Allocate a block to hold a list of sinks */ Sink* sink_list = (Sink*)PanicNull(calloc(max_sinks, sizeof(sink))); /* Get a list of all the Sinks active on this ACL */ if(streamsinksfrombdaddr(&max_sinks, sink_list, bd_addr)) { /*Do something with sinks in the list, e.g. send message to each one*/ } /* Free the allocated array of sinks. */ free(sink_list); 2.1.15 Source Sink StreamSinkFromSource (Source source) source: the source whose sink is to be returned. This function returns the sink associated with a known source. Page 12 of 31
Obtaining Sources and Sinks 2.1.16 Sink Source StreamSourceFromSink (Sink sink) sink: the sink whose source is to be returned. This function returns the source associated with a known sink. By convention BlueLab connections are identified by the sink. This function enables the associated source to be identified. Page 13 of 31
Direct Connections 3 Direct Connections The StreamConnect functions implement direct connections between sinks and sources. 3.1 General StreamConnect provides a simple way of connecting streams between various types of sources and sinks in order to transfer data. Streams connected using StreamConnect have the advantage that the firmware handles much of the data transfer making the process more efficient and data transfer faster. However, the data being streamed is not visible to the application (unless the stream is first disconnected) and cannot be readily monitored by the application. It is therefore not suitable if the application needs to be able to carry out additional processing on the data being streamed. 3.2 Use of StreamConnect This section describes StreamConnect and related functions declared in the header file to the stream library. Note: Sources and sinks can be obtained using the functions described in chapter 2. 3.2.1 StreamConnect uint16 StreamConnect (Source source, Sink sink) source: the source to be connected. sink: the sink to be connected. StreamConnect establishes an automatic connection between the specified source and sink. Data arriving at the source is automatically copied to the sink when space permits. This is the most efficient but least flexible option available for connecting streams. Unlike managed implementations, sources and sinks connected using StreamConnect do not generate MORE_SPACE or MORE_DATA messages so the application does not have visibility of the sink/source buffers or the data flowing between them. The function returns a non-zero value if the connection was successfully established, zero if the operation failed. To use this function the source and sink must be valid and cannot be involved in an existing connection. The connection is broken if either source or sink become invalid. When a source and sink are connected using StreamConnect operations such as SinkClaim, SourceClaim, SinkMap etc. are refused unless the stream has been disconnected first. Therefore, to insert data into a connected sink it is necessary to disconnect the stream, claim the sink, write and flush the data being inserted and then reconnect the stream using StreamConnect. Page 14 of 31
Direct Connections Connection Example The following call illustrates how a Stream can be connected using the PanicFalse function to check that the source and sink being connected are valid and successfully connected: (void) PanicFalse(StreamConnect(StreamKalimbaSource(0),StreamPcmSink(0))); This function call attempts to connect the specified PCM sink to the DSP kalimba port. If either the source or the sink is not valid, or if the connection fails, the application panics. 3.2.2 StreamConnectDispose uint16 StreamConnectDispose (Source source) source: the source the function is to act on. This function disposes of all the data arriving on the specified source by throwing it away. It returns zero if the operation fails and non-zero if the operation succeeds. On success the source is effectively connected using StreamConnect. Therefore, you can stop discarding data arriving on the source by calling StreamDisconnect (source, 0). 3.2.3 StreamConnectAndDispose bool StreamConnectAndDispose (Source source, Sink sink) source: the source data is read from. sink: the sink data is written to. This function is similar to StreamConnect, but if the connection fails then the source is passed to StreamConnectDispose. Similarly, if the connection is subsequently broken (either from a call to StreamDisconnect or by the sink being closed) the source is passed to StreamConnectDispose. The result of this is that, if the connection fails or is subsequently broken, the source is tidied up correctly. Page 15 of 31
Direct Connections 3.2.4 StreamDisconnect uint16 StreamDisconnect (Source source, Sink sink) source: the source to be disconnected. sink: the sink to be disconnected. The StreamDisconnect function breaks any existing connection between the specified source and/or sink. Either parameter argument may be zero, e.g: StreamDisconnect (0, StreamUartSink ()) breaks any existing connection to the UART sink specified. Page 16 of 31
Managed Connections 4 Managed Connections In simplistic terms the sequence of events involved in transferring data (using functions provided in BlueLab) between sources and sinks is: 1. The application handling the sink, i.e. transferring data: Obtains the amount of space available in a sink Claims the sink Maps the sink Copies data in Flushes the sink (data streams to specified source) The application receives a MORE_SPACE message, and if there is still data to be streamed, the process is repeated to write more data to the sink. 2. The application handling the source: receives a MORE_DATA message Gets the size of the data in the source Maps the source Processes the data received Drops processed data If more data arrives at the source the process is repeated. The process continues until all the data has been transferred. Note: Section 4.1 describes the functions provided to facilitate the above. 4.1 Functions This section describes the functions provided in BlueLab that can transfer data between streams, when implementing a managed connection. 4.1.1 Sinks The following functions are declared in the sink.h header file. 1. SinkSlack uint16 SinkSlack (Sink sink) sink: the sink being checked. This function returns the number of bytes that can be successfully claimed in the specified sink. It returns zero if the sink is not valid. Page 17 of 31
Managed Connections 2. SinkClaim uint16 SinkClaim (Sink sink, uint16 extra) sink: the sink to claim. extra: the number of bytes the function will attempt to claim. 3. SinkMap If the claim is successful, this function returns the offset of the claimed region. A return value of 0xFFFF indicates the claim was unsuccessful. This is generally because the sink was invalid or the number of bytes the function is attempting to claim is more than the number of bytes available (as returned by SinkSlack) in the sink. uint8 *SinkMap (Sink sink) sink: the sink to map into the address map. This function maps the specified sink into the address map and returns a pointer to the first byte of the sink. Only the total number of bytes claimed (by SinkClaim) are accessible. Only one sink can be mapped into the address map at any time. Pointers obtained by previous calls to SinkMap become invalid when another call to SinkMap is made. 4. SinkFlush If the sink passed as a parameter is not valid the function returns NULL. bool SinkFlush (Sink sink, uint16 amount) sink: the sink to be flushed. amount: the number of bytes to be flushed when the function is called. This function flushes the number of bytes specified by the amount parameter passed to the function, i.e. the specified number of bytes of data are passed to the corresponding byte stream. The function returns zero if the operation failed either because the sink was invalid or if the amount parameter exceeded the size of the sink returned by SinkClaim. It returns a non-zero value if the operation is successful. Page 18 of 31
Managed Connections 5. SinkFlushHeader This function is similar to SinkFlush but adds a header to the number of bytes being flushed. bool SinkFlushHeader (Sink sink, uint16 amount, const uint16 *header, uint16 length) sink: the sink to flush data from. amount: the number of bytes to flush. header: a pointer to the header to be added to the message. length: the size of the header. This function flushes the number of bytes specified by the amount parameter passed to the function, i.e. it passes the specified number of bytes to the corresponding byte stream. The function returns zero if the operation failed either because the sink was invalid or if the amount parameter exceeded the size of the sink returned by SinkClaim. It returns a non-zero value if the operation is successful. The header pointed to by the header parameter is added to the message. This is generally used when additional information is required to correctly process the data, e.g. when streaming to a USB source (end point). 6. SinkGetBdAddr bool SinkGetBdAddr (Sink sink, bdaddr *bt_address) sink: the sink to fetch the Bluetooth address from. bt_address: the location to return the Bluetooth address if the operation is successful. This function returns TRUE if the address is found, FALSE if the operation is unsuccessful. If successful the Bluetooth address associated with a particular sink is copied to the location specified by the bt_address parameter. 7. SinkIsValid bool SinkIsValid (Sink sink) Parameter sink: the sink whose validity is to be checked. This function is used to verify the validity of the specified sink. It returns non-zero if the sink is valid and zero if the sink is not valid. Page 19 of 31
Managed Connections 4.1.2 Sources The following functions are declared in the source.h header file. 1. SourceSize uint16 SourceSize (Source source) source: the source being checked. This function returns the number of bytes available in the specified source or zero if the source is invalid. 2. SourceBoundary uint16 SourceBoundary (Source source) source: the source being checked. This function returns the number of bytes in the specified source before the next packet boundary, in packet-based streams e.g. L2CAP streams. For non packet-based sources this returns the same result as SourceSize. 3. SourceMap const uint8 *SourceMap (Source source) source: the source to map into the address map. This function maps the specified source into the address map and returns a pointer to the first byte of the source. Only the number of bytes given by SourceSize are accessible. Only one source can be mapped into the address map at any time. Pointers obtained by previous calls to SourceMap become invalid when another call to SourceMap is made. Note: A sink and source can be mapped into the address map at the same time to facilitate efficient implementation of the streaming process. If the source passed as a parameter is not valid the function returns NULL. Page 20 of 31
Managed Connections 4. SourceMapHeader Const uint16* SourceMapHeader (Source source) source: the source the operation is performed on. This function maps the first header associated with the specified source into the address map and returns a pointer to the first word in the header. Note: This function is most commonly used to facilitate responses to USB Class Requests. The number of accessible words is that given by SourceSizeHeader. Only one header source can be mapped into the address map at any one time. Pointers obtained by previous calls to SourceMapHeader become invalid when another call to SourceMapHeader is made. This function returns NULL if the source is not valid or has no headers. 5. SourceSizeHeader uint SourceSizeHeader (Source source) source: the source whose header size is being found. This function returns the number of words available in the first header associated with the specified source. The function returns zero if the source is not valid. 6. SourceDrop void SourceDrop (Source source, uint16 amount) source: the source from which the data is to be dropped. amount: the number of bytes to drop. This function discards the specified amount of bytes from the front of the specified source. Page 21 of 31
Managed Connections 7. SourceIsValid bool SourceIsValid (Source source) Parameter source: the source whose validity is to be checked. This function is used to verify the validity of the specified source. It returns non-zero if the source is valid and zero if the source is not valid. 4.1.3 Example Code This section includes some example code to illustrate the use of the functions described in this chapter. The example shows how a simple string can be streamed to the UART. const char *string = "Hello world"; uint16 length = strlen(string); /* Get the sink for the uart, panic if not available */ SourceSink sink = StreamUartSink(); PanicNull(sink); /* Claim space in the sink, getting the offset to it */ uint16 offset = SinkClaim(sink, length); if(offset == 0xFFFF) Panic(); /* Space not available */ /* Map the sink into memory space */ uint8 *dest = SinkMap(sink); (void) PanicNull(dest); /* Copy the string into the claimed space */ memcpy(dest+offset, string, length); /* Flush the data out to the uart */ PanicZero(SinkFlush(sink, length)); Page 22 of 31
Managed Connections 4.2 StreamMove uint16 StreamMove (Sink sink, Source source, uint16 count) sink: the sink to stream data to. source: the source to stream data from. count: the number of bytes to be moved. This function moves the specified number of bytes from the start of the specified source to the end of the specified sink. The value passed as the count parameter must be no more than the size of the data in the source and the available space in the sink, which are reported by SourceBoundary and SinkSlack. This call wraps the functionality of SinkClaim(), memcpy() and sourcedrop() into a single function. A call to sinkflush() must still be made to actually transmit the data written to the sink. StreamMove returns zero if the operation fails and the count if the operation succeeds. Code Example Note: A call to StreamMove does not invalidate any active SinkMap or SourceMap. /* Claim space in the sink */ uint16 claim_result = SinkClaim(sink, number_bytes); /* If claim failed return error */ if (claim_result == 0xffff) return 0; /* Move data from source to sink */ StreamMove(sink, source, number_bytes); /* Flush the data */ (void)sinkflush(sink, number_bytes); Page 23 of 31
Configuring Sources, Sinks and Streams 5 Configuring Sources, Sinks and Streams This chapter describes the functions available for configuring sources, sinks and streams. 5.1 General Three functions are available: SinkConfigure declared in the sink.h header file. SourceConfigure declared in the source.h header file. StreamConfigure declared in the stream.h header file. 5.1.1 SinkConfigure void SinkConfigure (Sink sink, vm_sink_config_key key, uint16 value) sink: the sink to configure. key: the key to configure. value: the value to write to the key. Purpose This function sets configuration values for the sink. See the on-line Reference documentation for the vm_if.h header file in xide for further details about the configurable parameters enumerated as vm_sink_config_key. Note: Some key configurations only apply to specific types of sink. 5.1.2 SourceConfigure void SourceConfigure (Sink sink, vm_source_config_key key, uint16 value) source: the source to configure. key: the key to configure. value: the value to write to the key. This function sets configuration values for the source. It is particularly applicable to HID streams. See the on-line Reference documentation for the vm_if.h header file in xide for further details about the configurable parameters enumerated as vm_source_config_key. Note: Some key configurations only apply to specific types of source. Page 24 of 31
Configuring Sources, Sinks and Streams 5.1.3 StreamConfigure void StreamConfigure (vm_stream_config_key key, uint16 value) key: the key to configure. value: the value to write to the key. This function is used to set configuration values for the stream subsystem. It is particularly applicable to HID streams. See the xide on-line Reference documentation on the vm_if.h header file, for further details about the configurable parameters enumerated as vm_stream_config_key. 5.1.4 HID Configuration The following prototypes configure HID sources for the correct type of sensor: bool SourceConfigureHidSensorAgilentADNS3030 (Source source, const HID_AGILENT_ADNS3030_CONFIG *config) source: the source to configure. config: a pointer to the configuration data. This function configures the source for an Agilent 3030/3040 optical sensor. The configuration parameters are specified in the HID_AGILENT_ADNS3030_CONFIG structure. See the xide on-line Reference documentation on the hid.h library, for further details about the configurable parameters enumerated as HID_AGILENT_ADNS3030_CONFIG. The function returns TRUE if the configuration was valid and successful or FALSE if the configuration failed. bool SourceConfigureHidSensorUart (Source source) source: the source to configure. This function configures the source for a external sensor connected to the Bluecore UART. The function returns TRUE if the configuration was valid and successful or FALSE if the configuration failed. Page 25 of 31
Configuring Sources, Sinks and Streams bool SourceConfigureHidSensorMatrix (Source source, const HID_MATRIX_CONFIG *config) source: the source to configure. config: a pointer to the configuration data. This function configures the source for a keyboard matrix. The configuration parameters are specified in the HID_MATRIX_CONFIG structure. See the xide on-line Reference documentation on the hid.h header file, for further details about the configurable parameters enumerated as HID_MATRIX_CONFIG. The function returns TRUE if the configuration was valid and successful or FALSE if the configuration failed. Page 26 of 31
Technical Support 6 Technical Support Further information on all CSR products can be found on the technical support website (http://www.csrsupport.com). Developers are also recommended to view the public newsgroups hosted by CSR on the Internet news (NTTP) server news.csr.com. The newsgroups are a convenient forum for the Bluetooth community to exchange knowledge and are a valuable source of information. Set up instructions and guidelines for the use of newsgroups can be found by following the Technical newsgroups links on the CSR support website. Page 27 of 31
Document References 7 Document References Document On-line xide Reference Documentation Reference n/a Page 28 of 31
Stream Sink/Source Compatibility Appendix A Stream Sink/Source Compatibility Table A.1 shows the types of source and sink that can be successfully connected together to stream data between them. Sinks Sources Kalimba PCM SCO RFCOMM Kalimba PCM SCO RFCOMM L2CAP UART Host USB (1) HID (2) Region File Audio Notes L2CAP Table A.1: Compatible Sinks and Sources Notes: (1) There are three Usb sink/source types; UsbClass, UsbEndPoint and UsbVendor, the entries apply to all three types. (2) There are two Hid sink/source types; Hid and HidAuxillary, the entries apply to both types. Where an application requires a connection between a sink and source that cannot be connected directly, Kalimba can be used to facilitate the connection e.g. SCO source -> Kalimba sink, Kalimba source -> SCO sink. UART Host USB (1) HID (2) Page 29 of 31
Terms and Definitions Terms and Definitions BCSP BlueCore Bluetooth SIG Bluetooth CSR HID L2CAP PCM RFCOMM SCO UART USB xide BlueCore Serial Protocol Group term for CSR s range of Bluetooth wireless technology chips Bluetooth Special Interest Group Set of technologies providing audio and data transfer over short-range radio connections Cambridge Silicon Radio Human Interface Device Logical Link Control and Adaptation Protocol Post Code Modulation Serial cable emulation protocol Synchronous Connection-Oriented link Universal Asynchronous Receiver Transmitter Universal Serial Bus CSR s Integrated Development Environment Page 30 of 31
Document History Document History Revision Date History ISSUE 1 01 NOV 06 Original publication of this document. (CSR reference: ) _äìéi~ä»= Implementing Streams in BlueLab User Guide November 2006 Unless otherwise stated, words and logos marked with or are trademarks registered or owned by CSR plc or its affiliates. Bluetooth and the Bluetooth logos are trademarks owned by Bluetooth SIG, Inc. and licensed to CSR. Other products, services and names used in this document may have been trademarked by their respective owners. The publication of this information does not imply that any licence is granted under any patent or other rights owned by CSR plc. CSR reserves the right to make technical changes to its products as part of its development programme. While every care has been taken to ensure the accuracy of the contents of this document, CSR cannot accept responsibility for any errors. CSR s products are not authorised for use in life-support or safety-critical applications. Page 31 of 31