Usage and Integration of Broadcom Linux Debian SDK

[updated on 2013.11.27]

1. Overview

This page discusses about how-to usage and integration of Broadcom Linux Debian SDK using EVK (ex. BCM4752 Sardine) on Debian-based (Ubuntu) Linux machine. When you finish reading, you will be able to

  • use AGPS SUPL/LBS with your Linux machine and Broadcom GNSS EVK,
  • tweak the GNSS XML config setting to your convenience,
  • tweak the GNSS client C/C++ code to your convenience,
  • and eventually SW integrate Broadcom GNSS chip within Linux system. (of course, antenna, TCXO, and HW setting are different issue.)

NOTE: LinuxDebian SDK is based on the latest GNSS software and it has almost all the features of well-known Android GNSS phone system. Please refer to Appendix C. TODOs for exceptions. NOTE: If you are not interested about Assisted GPS, you may ignore any comment about SUPL and LBS (Broadcom proprietary AGPS protocol) in this documentation. NOTE: We have not yet tested other Linux distros (ex. Fedora) besides Debian. However, we are quite sure that it might work well. Even if other Linux distro fails the code change required would be minimal.

2. Setup

Step 1: Prepare following

  • Broadcom GNSS EVK.
  • Linux machine (currently tested Ubuntu 11.10 Server)
  • RS232 cable and USB cable.
  • Broadcom LinuxDebian GNSS SDK of 9.19.10.149106 (or higher)
  • If you do not have an EVK or a SDK, please ask your local FAE/AE about the support.

Step 2: Hardware Setup

  • Connect the EVK and Linux machine with RS232 cable (for data) and USB cable (for power).
  • The RS232 cable end should go to Linux machine's COM port.
  • Put the EVK in GNSS signal available area or connect external antenna.

Step 3: Dependent Software Setup

  • Please install following packages for 32 bit system.
    • # sudo apt-get install gcc g++ openssl libssl libssl-dev libxml2 libxml2-dev libglib2.0-dev ccache cmake gawk ant
  • Please install following additional packages for 64 bit system.
    • # sudo apt-get install libc6-dev-i386 libssl-dev:i386 gcc-multilib g++-multilib

Step 4: SDK Software Setup

  • Unzip the LinuxDebian SDK.
  • Open Makefile.config file
  • Set the target directory by changing this path.
          export DELIVERY_INSTALL_DIR=/opt/gnss
    
  • Install the package with this command.
          $ make install
    
  • The install command will daemonize the daemon binary in your system.
  • You can uninstall the package with this command.
          $ make uninstall
    

Step 5: Text-based GNSS client, GpsClient

  • Go to directory gpsclient
  • Run CMake
          $ cmake .
    
  • Build the GpsClient
          $ make
    
  • Run the client
          $ GpsClient
    
  • The usage is straight-forward and follow the instructions to run Standalone or AGPS. The sample capture of text-based client usage is following for your review.
    $ ./GpsClient
    [main]:Simple Text-based Client of BRCM GNSS System.
    [main]:GpsInterface::init returned (0).
    
    Delete Aiding? [y/N] y
    
    Set GNSS recurrence
    [0] Periodic
    [1] Singleshot
    Choose the GNSS mode to run [1] 1
    
    Set AGPS mode
    [0] Standalone
    [1] SUPL 1.0 MS-Based
    [2] SUPL 1.0 MS-Assisted
    Choose the GNSS mode to run [1] 1
    Set timeout in seconds [180]
    Set preferred accuracy in meters [50]
    
    Change the default SUPL server address? [bcmslpqa1.glpals.com]
    Change the default set id of User Equipment (UE)? [0000000000000] [y/N]
    Change the default cell id for reference location? [GSM:MCC(450):MNC(5):LAC(8609):CID(3105)] [y/N]
    Apply Wifi MAC address for reference location? [y/N]
    [main]GpsInterface::set_position_mode returned (0).
    [main]:GpsInterface::start returned (0).
    
    Response to following query will send stop command to the GNSS service.
    In order to monitor current GNSS activity, try "tail -f /var/log/syslog"
    Start another session? [y/N]
    
  • NOTE: This GpsClient code, main.cpp serves as a sample code on how to control GNSS system. That's why it's very simple and we want to keep it that way.
  • If you observe LED lights blinking in EVK, you are in the right track. Otherwise, consult your FAE/AEs with the NVRAM directory files zipped.
  • Please note that pressing any key when "Start another session? [Y/n]" appeared will stop GNSS system
  • In order to monitor the current action, you may want to do following.
          tail -f /var/log/syslog
    

3. Logs

The GpsClient will put all the result to Linux syslog. For example, if you run AGPS MS-BASED GNSS session, the result of latitude and longitude will be stored in syslog like this.

Nov  6 18:06:37 geoid GpsClient[10922]: [BRCM GNSS]:[local_nmea_cb]: UTC[1352192797762]: NMEA[$IMGSA,A,3,,,,,,,,,,,,,3.3,1.5,2.9*2E]
Nov  6 18:06:37 geoid GpsClient[10922]: [BRCM GNSS]:[local_nmea_cb]: UTC[1352192797762]: NMEA[$PGLOR,1,FIX,21.7,19.1*2D]
Nov  6 18:06:37 geoid GpsClient[10922]: [BRCM GNSS]:[local_nmea_cb]: UTC[1352192797762]: NMEA[$GPRMC,090659.92,A,3730.340611,N,12703.294218,E,000.1,169.5,061112,,,A*5C]
Nov  6 18:06:37 geoid GpsClient[10922]: [BRCM GNSS]:[local_location_cb]: lat(37.505677), lon(127.054904), alt(156.291690), speed(0.043601), bearing(169.528152), accuracy(16.000000)
Nov  6 18:06:37 geoid GpsClient[10922]: [BRCM GNSS]:[local_sv_status_cb]: NumSVs[8]
Nov  6 18:06:37 geoid GpsClient[10922]: [BRCM GNSS]:#011[ ]:PRN[2]:SNR[20.000000]:Elev[68.000000]:AZ[125.000000]
...
Nov  6 18:06:37 geoid GpsClient[10922]: [BRCM GNSS]:#011[ ]:PRN[84]:SNR[20.000000]:Elev[27.000000]:AZ[182.000000]

NOTE: The most important is "$PLGOR,1,FIX", the value next to it is TTFF (Time to First Fix). You can find latitude and longitude next to "local_location_cb".

Extra to this log, we have Broadcom GNSS log, called SLOG, as directed in the XML file.

 acLogDirectory="/opt/gnss/log/"

4. XML configuration

Our GNSS system runs as a service daemon and it has XML configuration. The default XML config file is given in gpsconfig.xml file in the top directory. For more information please refer to GL XML Config file description.

NOTE: XML configuration for customer should be also managed by SW FAE/AEs. Please notify your project detail to your FAE/AEs so that they can create different SDK suited for your project. NOTE: Above SUPL/LBS servers are development servers which need separate registration for each devices. In order to use Broadcom SUPL or LBS server in your mass production for AGPS feature, we need B2B contract. Please discuss about this with local Broadcom FAE/Sales team.

5. C-based API

The API to control Broadcom Linux GNSS system is based on Android's GNSS API, GpsInterface. The header file that enclose all the API is located in include/gps.h. (NOTE: Android is under Apache Software Licence 2.0)

The single major difference between Android's GpsInterface and Linux's GpsInterface is this code part.

#ifdef ANDROID
struct gps_device_t {
    struct hw_device_t common;

    const GpsInterface* (*get_gps_interface)(struct gps_device_t* dev);
};
#else
    // Non-Android user will directly call get_gps_interface_direct().
    const GpsInterface* get_gps_interface_direct();
#endif

You can acquire GpsInterface pointer directly with get_gps_interface_direct(). This code usage is open-code available in gpsclient/main.cpp file.

The rest of init/cleanup/start/stop usage is same with Android.

Appendix A. Tool Chain

Most of the times, the customer will only review broadcom/LinuxDebian as a reference SDK. The real SDK suited for the target system will require some proprietary tool chain to be used so that different cores are used. In this case, the customer should provide the zipped tool chain file to BRCM GPS FAE/AE so that they can build the GNSS engine library and prepare a different SDK. The key of this process lies in the Makefile.config file. The responsible AE should make a separate cloned project with following modification in the Makefile.config file.

export LIBEXT         = a
export MAKE           = $(TOOL_CHAIN_PATH)/make
export CC             = $(TOOL_CHAIN_PATH)/gcc
export CXX            = $(TOOL_CHAIN_PATH)/g++
export AR             = $(TOOL_CHAIN_PATH)/ar crsP
export LD             = $(TOOL_CHAIN_PATH)/g++
export LINK           = $(TOOL_CHAIN_PATH)/$(LD)
export STRIP          = $(TOOL_CHAIN_PATH)/strip

You can change the TOOL_CHAIN_PATH, include path, library path and so on from Makefile.config file.

Appendix B. Reference

There is a troubleshooting and similar Linux system guide in How to run SDK on (Windows or Linux) PC.

Appendix C. TODOs

There were some TODOs that we failed to achieve until the time of the last document update.

  • The known missing features compare to Android phone system.
    • CNTIN. This can be enabled if you add modem chip to your system. Please refer to Frequency Synchronization for more information.
    • HULA positioning. Please refer Sensor Description for more information.
    • Android property. (can be implemented differently)
 All Classes Files Functions Variables Typedefs Enumerations Enumerator Defines