blesh

README

blesh -h

NAME:
   blesh - A CLI tool for ble

USAGE:
   blesh [global options] command [command options] [arguments...]

VERSION:
   0.0.1

COMMANDS:
     status, st     Display current status
     adv, a         Advertise name, UUIDs, iBeacon (TODO)
     serve, sv      Start the GATT Server
     scan, s        Scan surrounding with specified filter
     connect, c     Connect to a peripheral device
     disconnect, x  Disconnect a connected peripheral device
     discover, d    Discover profile on connected device
     explore, e     Display discovered profile
     read, r        Read value from a characteristic or descriptor
     write, w       Write value to a characteristic or descriptor
     sub            Subscribe to notification (or indication)
     unsub          Unsubscribe to notification (or indication)
     shell, sh      Enter interactive mode
     help, h        Shows a list of commands or help for one command

GLOBAL OPTIONS:
   --help, -h      show help
   --version, -v   print the version

*** Quick Tutorial ***

We will start two instances of blesh; one as a peripheral running a simple GATT server while another one acting as client connecting to the server, and explore it's profile.

** Build **

blesh supports both OS X and Linux, and can be cross-compiled easily. Let's build two binaries and have them running on different platforms. (Or you can run two instances on a Linux if you have more than one ble devices.)

GOOS=darwin go build -o blesh_osx *.go
GOOS=linux go build -o blesh_lnx *.go

Start a GATT server on the Linux platform (with a usb ble dongle) for 1 hour. (We'll leave it sit there for the rest of tutoruial)

sudo ./blesh_lnx sv -tmo 1h

Initializing device ...
Serving GATT Server for 1h0m0s...

Start another instance on the OS X, or Linux with another ble device. Use the shell subcommand to enter interactive mode.

./blesh_osx shell

Initializing device ...
blesh >

Scan for surrounding devices

blesh > scan -tmo 2s
Scanning for 2s...
[41a2e12c9265407a82e25379df839e0d] C -47: Name: Gopher, Svcs: [0001000000011000800000805F9B34FB]
[41a2e12c9265407a82e25379df839e0d] C -47: Name: Gopher
[41a2e12c9265407a82e25379df839e0d] C -47: Name: Gopher, Svcs: [0001000000011000800000805F9B34FB]
[41a2e12c9265407a82e25379df839e0d] C -48: Name: Gopher
[1a7026ac7be8402680926d95ef2f0661] C  86: Name: Bose QuietComfort 35, Svcs: [FEBE], MD: 1001400C0141ACBC32794E58
[1a7026ac7be8402680926d95ef2f0661] C  86: Name: Bose QuietComfort 35
[41a2e12c9265407a82e25379df839e0d] C -48: Name: Gopher, Svcs: [0001000000011000800000805F9B34FB]
[41a2e12c9265407a82e25379df839e0d] C -48: Name: Gopher
...

The peripheral instance is advertising with "Gopher" as its name, and a service with UUID "0001000000011000800000805F9B34FB".

Now, let's scan only for device that has name of "Gopher" for 1 second. And don't show duplicate.

blesh > scan -name Gopher -dup=false -tmo 1s
Scanning for 1s...
[41a2e12c9265407a82e25379df839e0d] C -48: Name: Gopher, Svcs: [0001000000011000800000805F9B34FB]
[41a2e12c9265407a82e25379df839e0d] C -58: Name: Gopher

The result is much cleaner now.

blesh > status
Current status:
  Initialized: yes
  Address:     41a2e12c9265407a82e25379df839e0d
  Connected:
  Profile:
  UUID:

Status shows some cached values, which can serve as default values in some commands. For example, now we can issue "connect" command without explicitly specifying which device to connect.

blesh > connect
Connecting ...

Or we can still connect to device with specified condition.

blesh > disconnect
Disconnecting [ 41A2E12C9265407A82E25379DF839E0D ]... (this might take up to few seconds on OS X)

blesh > connect -addr 41A2E12C9265407A82E25379DF839E0D
Connecting ...

blesh > status
Current status:
  Initialized: yes
  Address:     41A2E12C9265407A82E25379DF839E0D
  Connected:   41A2E12C9265407A82E25379DF839E0D
  Profile:
  UUID:

Now we're connected, and let's discover the profile (service/char/...) on the server.

blesh > discover
Discovering profile...

blesh > status
Current status:
  Initialized: yes
  Address:     41A2E12C9265407A82E25379DF839E0D
  Connected:   41A2E12C9265407A82E25379DF839E0D
  Profile:

    Service: 0001000000011000800000805F9B34FB , Handle (0x10)
      Characteristic: 0001000000021000800000805F9B34FB , Property: 0x3E (wWNIR), Handle(0x11), VHandle(0x12)
        Value         636f756e743a20526561642030 | "count: Read 0"
        Descriptor: 2902 Client Characteristic Configuration, Handle(0x13)
        Value         0000 | "\x00\x00"
      Characteristic: 0002000000021000800000805F9B34FB , Property: 0x3C (IwWN), Handle(0x14), VHandle(0x15)
        Descriptor: 2902 Client Characteristic Configuration, Handle(0x16)
        Value         0000 | "\x00\x00"

  UUID:

To display the profile only, use the explore command.

blesh > explore
Discovering profile...
    Service: 0001000000011000800000805F9B34FB , Handle (0x10)
      Characteristic: 0001000000021000800000805F9B34FB , Property: 0x3E (IRwWN), Handle(0x11), VHandle(0x12)
        Value         636f756e743a20526561642031 | "count: Read 1"
        Descriptor: 2902 Client Characteristic Configuration, Handle(0x13)
        Value         0000 | "\x00\x00"
      Characteristic: 0002000000021000800000805F9B34FB , Property: 0x3C (wWNI), Handle(0x14), VHandle(0x15)
        Descriptor: 2902 Client Characteristic Configuration, Handle(0x16)
        Value         0000 | "\x00\x00"

Notice that the value read from characteristic is changed (our sample characteristic simply increment the counter when it is read).

Use the "read" command to read the characteristic value again.

blesh > read -uuid 0001000000021000800000805F9B34FB
    Value         636f756e743a20526561642032 | "count: Read 2"

blesh > st
Current status:
  Initialized: yes
  Address:     41A2E12C9265407A82E25379DF839E0D
  Connected:   41A2E12C9265407A82E25379DF839E0D
  Profile:

    Service: 0001000000011000800000805F9B34FB , Handle (0x10)
      Characteristic: 0001000000021000800000805F9B34FB , Property: 0x3E (RwWNI), Handle(0x11), VHandle(0x12)
        Value         636f756e743a20526561642033 | "count: Read 3"
        Descriptor: 2902 Client Characteristic Configuration, Handle(0x13)
        Value         0000 | "\x00\x00"
      Characteristic: 0002000000021000800000805F9B34FB , Property: 0x3C (wWNI), Handle(0x14), VHandle(0x15)
        Descriptor: 2902 Client Characteristic Configuration, Handle(0x16)
        Value         0000 | "\x00\x00"

  UUID:       0001000000021000800000805F9B34FB

Notice now the UUID has been cached, too. So, we can "subscribe" (or unsubscribe) to the characteristic without explicitly specifying it.

blesh > sub
blesh >
notified: 436f756e743a2030 | "Count: 0"
notified: 436f756e743a2031 | "Count: 1"
notified: 436f756e743a2032 | "Count: 2"
notified: 436f756e743a2033 | "Count: 3"
notified: 436f756e743a2034 | "Count: 4"
unsub
blesh >

Disconnect, and quit the shell.

blesh > disconnect
Disconnecting [ 41A2E12C9265407A82E25379DF839E0D ]... (this might take up to few seconds on OS X)

blesh > quit

Given that we've know what filter to use for connecting, and which UUID to manipulate, we can use the one-liner to read the value directly.

./blesh_osx read -name Gopher -uuid 0001000000021000800000805F9B34FB
Initializing device ...
Connecting...
Discovering profile...
    Value         636f756e743a20526561642034 | "count: Read 4"