Getting started

Last update: June 29th, 2023

Lab overview and setup

Requirements

The Bluetooth Low Energy (BLE) protocol is wildly used by smart devices, because of its low power consumption and its simplicity. For this lab, we will use a very popular IoT-oriented System-on-Chip (SoC) providing WiFi and Bluetooth connectivity: ESP32 SoC from Espressif Systems.

For this lab, we provide:

  • 1x ESP32 development kit (ESP-WROOM-32)
  • 1x USB 2.0 A Male To Micro USB Male Cable

You will also need to bring your own laptop with Bluetooth LE support (HCI).

Software environment

To facilitate the labs, we provide a virtual machine running an Ubuntu 22.04 operating system, preinstalled with:

  • Espressif IoT Development Framework
  • BlueZ and command-line tools
  • Wireshark

You can download the virtual machine here: CyberInSophia.ova

Virtual Machine credentials

Login: cyberinsophia
Password: cyberinsophia

Importing the Virtual Machine

To run this virtual machine, download and install VirtualBox for your operating system. Then, select File > Import Appliance:

It will open VirtualBox Import Appliance Manager. Click on the folder button, select the file CyberInSophia.ova, and click on Finish to start the import process.

The import process may take several minutes. Once imported, a new virtual machine named "CyberInSophia" should be listed in VirtualBox interface:

Configuring the Virtual Machine

Run the virtual machine, and make sure your Bluetooth adapter and the ESP32 are forwarded to the Virtual Machine as USB peripherals. You can select them in Devices > USB. ESP32 should appear as Silicon Labs CP210x USB to UART bridge, Bluetooth adapter will be dependent of your latop (contact us if you don't manage to identify it !).

Warning

You may have to install VirtualBox Guest additions to allow your Bluetooth adapter to be forwarded to the Virtual Machine: click on Devices, then Install Guest additions.
It may also be necessary to disable the Bluetooth adapter before running the machine on your Host operating system before running the machine. On Linux, it can be done from a terminal using sudo hciconfig hci0 down. On Windows, go to Devices Manager (right-click on Windows icon at left bottom corner, then select Device Manager). Then, find your Bluetooth adapter in the list, right click on it and click on Disable device. Once disabled, start the Virtual Machine, re-enable the adapter from Windows (right click > Enable device) and forward the USB device (in VirtualBox, Devices > USB)

One the Virtual Machine is running, login using cyberinsophia user (login: cyberinsophia / password: cyberinsophia), then open a terminal and run hciconfig. If your Bluetooth adapter is successfully forwarded, you should see an output similar to the screenshot below:

You can also check if the ESP32 is successfully detected by typing the command lsusb:

The corresponding serial port should appear as /dev/ttyUSB0 or /dev/ttyACM0:

You are now ready to start the lab !