GAN Smart Cubes MAC address FAQ

gan-mac-faq.md

Q: What is the cube MAC address?
A: MAC is the Bluetooth device hardware address, each device instance has it unique. It has 48 bits and typically represented as 6 bytes written in hexadecimal and separated by colons or hyphens, for example AB:12:34:5D:34:12.

Q: Why MAC address is ever needed?
A: The GAN smart cube application-layer protocol encrypts all data using AES cypher. Encryption keys are unique for each cube instance, and generated based on cube's MAC address. So to decrypt any data sent by cube it is required for application to know cube MAC address.

Q: But I used another GAN cube with Cubeast, or different smartcubing software, and it does not ever ask me for the MAC address.
A: For some GAN smart cubes range used for MAC addresses was small enough, so Cubeast try to bruteforce address automatically. This can be done in reasonable amount of time. But this is not an option for newer cubes and MAC can't be guessed. Also some software like platform-native applications has direct access to low-level Bluetooth API and able to read device MAC address automatically. But this is not an easy way for browser-based Progressive Web Applications and Web Bluetooth API, although this is possible but requires the user to properly configure the browser used. So if MAC address can't be determined automatically for any reason, it will be simply asked from user.

Q: Could things be simpler?
A: Yes! Some web applications like csTimer able to read MAC address automatically, you just need to use browser with most complete support for Web Bluetooth, and properly setup it:

• Use Chrome on macOS, Windows and Android.
  You need to enable chrome://flags/#enable-experimental-web-platform-features flag in browser settings.
• Use Bluefy on iOS/iPadOS.
  You need to turn on Enable BLE Advertisements option in browser settings.

Q: How to get my cube MAC address?
A: This task is depends on which platform/device you have, there are lot of options:

• Using Chrome browser Bluetooth debug page:

  Platforms: Windows/Linux/Android
  ⚠️ macOS: Note that although this debug page is available in Chrome on macOS, MAC address shown there is spoofed and not real hardware MAC, and won't work.

  Open debug page using following URL and scan for Bluetooth devices while you cube is on and in the pairing mode:
  chrome://bluetooth-internals/#devices
  You can get MAC address of your cube device from the Address column.

• Using macOS Bluetooth preferences:

  Platforms: macOS

  Firstly you need to connect your cube, simply use Chrome browser Bluetooth debug page chrome://bluetooth-internals/#devices. Scan for devices, find your cube device, then click Inspect button. After your cube is connected, you can simply Alt-Click on the Bluetooth icon in the macOS Menu Bar, there you should see your cube device with MAC address displayed. Also you can open Terminal application and run system_profiler SPBluetoothDataType command. Under connected section you should see your cube device and it's MAC address. Latter is more handy because you can copy-paste MAC address from terminal.

• Using nRF Connect application:

  Platforms: Android

  You can install free nRF Connect application designed for BLE debugging.

  • Google Play: https://play.google.com/store/apps/details?id=no.nordicsemi.android.mcp
  • GitHub: https://github.com/NordicSemiconductor/Android-nRF-Connect/releases

  Using this app you can scan for BLE devices around and obtain their MAC addresses.

• Using Web Bluetooth API:

  Platforms: Windows/Android/macOS/iOS/iPadOS

  Assuming that you already have installed compatible with Cubeast browser (Bluefy on iOS/iPadOS and Chrome on Windows/Android/macOS). Configure your browser to enable Web Bluetooth advertisement API:

  • Chrome: enable chrome://flags/#enable-experimental-web-platform-features flag.
  • Bluefy: turn on Enable BLE Advertisements option in browser settings.

  Restart your browser and go to https://gan-mac-poc.stackblitz.io/
  Run this project, connect to the cube, and if all fine you will get your cube device MAC.