Document how to collect Bluetooth air logs

Support/Help_Articles/Collecting_Logs/Collect_Bluetooth_Logs/README.md

@@ -0,0 +1,97 @@
+---
+title: Collect Bluetooth Logs
+permalink: Support/Help_Articles/Collecting_Logs/Collect_Bluetooth_Logs/
+grand_parent: Help Articles
+parent: Collecting Logs
+layout: default
+nav_order: 600
+---
+
+_This article explains how to collect logs about the air traffic between a Sailfish and another Bluetooth device. The test scripts needed are attached to this article._
+
+
+
+# Preparations
+
+## Developer mode
+
+Enable the [**Developer mode**](/Support/Help_Articles/Enabling_Developer_Mode/).
+
+## Scripts to enable effective debugging
+
+Please find two script files attached to this message. Save them to your computer:
+* **[upf-start-test.sh](upf-start-test.sh)**
+* **[upf-stop-test.sh](upf-stop-test.sh)**
+
+The first script is to restart Bluetooth, Obex and some other processes and start collecting Bluetooth air traffic. The second script stops the logging.
+
+Copy the two script files to your Sailfish device (folder /home/defaultuser).
+
+Make sure that the scripts have the execution rights by issuing the commands below:
+
+```
+cd /home/defaultuser
+chmod a+x upf*.sh
+```
+
+Get the super-user permissions by giving the command "devel-su" at the Terminal. Next, install two code packages to enable the Bluetooth HCI dumps and tracing:
+
+```
+devel-su
+pkcon refresh
+pkcon install bluez5-hcidump
+pkcon install bluez5-tracing
+systemctl restart bluetooth.service
+```
+
+You have completed the preparations.
+
+# Bluetooth logging
+
+## Start logging
+
+Start collecting the logs with the command below. In this example, we use the word **CAR** as the name of this logging session (as if we were monitoring the Bluetooth traffic between a phone and a car).
+
+Choose the name that is appropriate for your case.
+
+The command below must be run with super-user permissions, as 'root'. If needed, use "devel-su" to get the permissions.
+
+The logs will be collected in the folder `/var/log/upf/session-CAR/`:
+
+```
+devel-su        # if not 'root' already
+./upf-start-test.sh CAR
+```
+
+The display will turn black momentarily but the normal UI should return in 10-20 seconds. You will have to open the Terminal app again. Bluetooth logs are now being collected in the background.
+
+## Force the device to the problem situation
+
+You should **run your Bluetooth test scenarios** next. That is, use the Sailfish device with the peripheral Bluetooth device. Do the steps that cause the error situation. If possible, make a note of the time when the problem occurs (the time of the phone) - this will help find the correct point in the log file.
+
+## Stop logging
+
+```
+devel-su          # if not 'root' already
+./upf-stop-test.sh CAR
+```
+
+This script collects the logs from your device and compresses them to file **CAR.tar** on your Sailfish device.
+
+# Send the results
+
+File a ticket at **[Jolla customer care](https://jolla.zendesk.com/hc/en-us/requests/new)**. Attach the log file to it, please: CAR.tar.
+
+# Cleaning up
+
+1) Remove the packages you installed:
+
+```
+devel-su             # if not 'root' already
+pkcon remove bluez5-hcidump
+pkcon remove bluez5-tracing
+```
+
+2) Switch off "Developer mode" in "Settings > System > Developer tools".
+3) Restart your device to ensure that it really exits the debugging mode.
+

Support/Help_Articles/Collecting_Logs/Collect_Bluetooth_Logs/upf-start-test.sh

@@ -0,0 +1,86 @@
+#!/bin/sh
+#
+# upf-start-test.sh -- start logging BT 
+#
+# usage: upf-start-test.sh test-session-name
+
+
+panic()
+{
+    echo "error: $*" 1>&2
+    exit 1
+}
+
+log()
+{
+    echo "$*"
+}
+
+debug_restart_daemon()
+{
+    DAEMON=$1
+    log "Restarting ${DAEMON}"
+    if [ "${DAEMON}" = "obex-client" ]; then
+	killall ${DAEMON}
+	sleep 1
+	su -c "/usr/libexec/obex-client -d" defaultuser &
+	echo "${DAEMON} restarted with debugging."
+    elif [ "${DAEMON}" = "obexd" ]; then
+	OUTPUT=$2
+	killall ${DAEMON}
+	sleep 1
+	su -c "/usr/libexec/obexd-wrapper" defaultuser >${OUTPUT} 2>&1 &
+	sleep 2
+	killall -USR2 ${DAEMON} || panic "Cannot enable debug for ${DAEMON}"
+	echo "${DAEMON} restarted with debugging."
+    else
+	SERVICE=$2
+	systemctl restart ${SERVICE} || panic "Cannot restart ${DAEMON}"
+        # cut some slack before enabling debug
+	sleep 2
+	killall -USR2 ${DAEMON} || panic "Cannot enable debug for ${DAEMON}"
+	echo "${DAEMON} restarted with debugging."
+    fi
+}
+
+start_hcidump()
+{
+    DIR=$1
+    OUTPUT=$2
+    hcidump -w ${DIR}/hcidump.pcap >${OUTPUT} 2>&1 &
+    HCIDUMPPID=$!
+    echo ${HCIDUMPPID} > ${DIR}/hcidump.pid || echo "Cannot record hcidump pid"
+    sleep 1
+}
+
+PREFIX=/var/log/upf
+DATETIME=`date +%Y-%m-%d_%H:%M:%S`
+
+NAME=$1
+if [ -z ${NAME} ]; then
+    echo "usage: $0 test-session-name"
+    exit 1
+fi
+
+
+DATADIR=${PREFIX}/session-${NAME}
+
+mkdir -p ${DATADIR} || panic "Cannot create directory ${DATADIR}"
+echo ${DATETIME} > ${DATADIR}/datetime || panic "Cannot record start timestamp"
+
+start_hcidump ${DATADIR} ${DATADIR}/hcidump.output
+debug_restart_daemon bluetoothd bluetooth.service
+debug_restart_daemon obexd ${DATADIR}/obexd.output
+debug_restart_daemon obex-client
+
+
+# Crude way to re-register user agents for the new daemons
+sleep 3
+echo ""
+echo "The display will turn black for a moment..."
+sleep 3
+killall lipstick
+
+echo "Test startup done, directory ${DATADIR}"
+
+exit 0

Support/Help_Articles/Collecting_Logs/Collect_Bluetooth_Logs/upf-stop-test.sh

@@ -0,0 +1,79 @@
+#!/bin/sh
+#
+# upf-stop-test.sh -- stop logging BT 
+#
+# usage: upf-stop-test.sh test-session-name
+
+
+panic()
+{
+    echo "error: $*" 1>&2
+    exit 1
+}
+
+error()
+{
+    echo "error: $*"
+}
+
+log()
+{
+    echo "$*"
+}
+
+stop_daemon()
+{
+    DAEMON=$1
+    if [ "${DAEMON}" = "obex-client" -o "${DAEMON}" = "obexd" ]; then
+	killall "${DAEMON}" || error "Cannot stop ${DAEMON}"
+    else
+	SERVICE=$2
+	log "Stopping ${DAEMON}"
+	systemctl stop ${SERVICE} || error "Cannot stop ${DAEMON}"
+    fi
+}
+
+stop_hcidump()
+{
+    DIR=$1
+    HCIDUMPPID=`cat ${DIR}/hcidump.pid` || error "Cannot read hcidump pid"
+    if [ ! -z "${HCIDUMPPID}" ]; then
+	kill ${HCIDUMPPID} || error "Cannot kill hcidump"
+    fi
+}
+
+PREFIX=/var/log/upf
+NAME=$1
+
+if [ -z ${NAME} ]; then
+    echo "usage: $0 test-session-name"
+    exit 1
+fi
+DATADIR=${PREFIX}/session-${NAME}
+
+if [ ! -d ${DATADIR} ]; then
+    panic "Directory ${DATADIR} does not exist."
+fi
+
+TIME=`cat ${DATADIR}/datetime | cut -f 2 -d _` || error "Cannot read start timestamp"
+if [ ! -z "${TIME}" ]; then
+    journalctl --since=${TIME} > ${DATADIR}/journal.log || error "Cannot record journal"
+else
+    journalctl > ${DATADIR}/journal.log || error "Cannot record journal"
+fi
+
+stop_daemon obex-client
+stop_daemon obexd
+stop_daemon bluetoothd bluetooth.service
+stop_hcidump ${DATADIR}
+
+tar -cf $NAME.tar $DATADIR  2> /dev/null
+chown 100000:100000 $NAME.tar   ## handles both nemo and defaultuser
+echo "" 
+HOME=$(pwd)
+echo "---------------------------------------------"
+echo "Get the file '$NAME.tar'"
+echo "from $HOME"
+echo "---------------------------------------------"
+echo ""
+exit 0