Skip to main content


Registers a callback to be executed when another Bluetooth device attempts to connect to the imp004m


Device (from impOS™ 38)


Name Type Description
callback Function A function triggered when a connection attempt is made




This method allows other Bluetooth devices to connect to the imp004m, and registers a function that will be called when a device attempts to connect. When it is called, it also updates the type of the advertisement broadcast by the imp004m to ADV_IND (see bluetooth.startadvertise()).

To prevent any remote devices connecting to the imp004m, pass null into bluetooth.onconnect(). This is the default state.

The function passed into the parameter callback takes one parameter of its own: a btconnection object. This provides a set of methods with which to manage the connection between the imp004m and the remote device:

  • address() — Returns the Bluetooth MAC of the remote device as a 12-character hexadecimal string
  • close() — The application’s means to close the connection. This will not trigger the onclose() callback.
  • onclose() — Registers a function that will be called when the connection is closed by any means outside of the application’s (or impOS’) control. Note that the connection may be closed before the onclose() function is registered.
  • security() — Returns an integer indicating the level of security to which the Bluetooth LE sub-system is currently set: 1, 3 or 4, respectively corresponding to the standard bluetooth LE security Mode 1 Level 1, Level 3 and Level 4.

When close() is called on the btconnection object, the connection can no longer be used. This will also occur if the btconnection object goes out of scope. In neither case will any function registered with onclose() be called.

Example Code

This simple snippet simply logs connections from remote devices as they are attempted, and signals if they were closed by the remote device

bt.onconnect(function (conn) {
  server.log("Connection attempt made from " + conn.address());

  // Register the remote closure notifier function
  conn.onclose(function () {
    server.log("Connection closed by " + conn.address());

  // Does the connection meet the required level of security?
  if ( < 4) {
    // No, it doesn't so close the connection immediately
    // Note this will NOT trigger the onclose() callback

  // Is the device attempting to connect a known one?
  if (!macOnWhitelist(conn.address()) {
    // Unknown device - close the connection
    // Note this will NOT trigger the onclose() callback

function macOnWhitelist(mac) {
  // Assume a global variable ‘permittedMACs` is an array of MAC addresses
  for (aMAC in permittedMACs) {
    if (aMAC == mac) return true;

  return false;