This is the mibanda API reference.
Service to discover Mi Band devices nearby using Bluetooth LE.
device is the name of your Bluetooth hardware (could be get using hciconfig). If not given, the first device is used: hci0.
>>> sd = mibanda.DiscoveryService()
Note
It may require superuser privileges (run as root, or using sudo).
Launch the discovery process. It runs a LE scan to discover new devices, up to timeout seconds. It returns a list with newly created mibanda.BandDevice objects, one for each discovered Mi Band.
>>> sd.discover()
[<mibanda.BandDevice at 0x7f03fcd54c50>]
This is the main object of mibanda library. It represents a Mi Band device, and has those methods needed to read its state, and control/change its behaviour.
address is its MAC address, in the form of a string like: 00:11:22:33:44:55. Name is the advertised Bluetooth name. It could be empty.
>>> device = mibanda.BandDevice("88:0f:10:00:01:02", "MI")
Used to create a connection with the Mi Band. It may take some time, depending on many factors as LE params, channel usage, etc.
>>> device.connect()
Note
This method needs to be called before almost any other command. Also note that the connection will be closed after some period of inactivity. See Bluetooth LE params for more info.
Get device’s MAC address. Is the same value given at construction time. It’s a fixed param.
>>> device.getAddress()
'88:0F:10:00:01:02'
Get device’s Bluetooth name. Usually the string ‘MI’, but it may be changed. It will return the name given at construction time, or read the device’s name. This name will be cached, but you can force the read passing False on cached argument.
>>> device.getName()
'MI'
Get information about device battery. Returns a mibanda.BatteryInfo instance.
>>> info = device.getBatteryInfo()
>>> info.status
'not charging'
>>> info.level
86
>>> info.charge_counter
6
>>> info.last_charged
datetime.datetime(2015, 1, 11, 22, 36)
Get device information: firmware version, etc.
>>> info = device.getDeviceInfo()
>>> info.firmware_version
'1.0.6.2'
Get current step counter value. This is the device counter, as shown in the official application. Returns an integer.
>>> device.getSteps()
4730
Get Bluetooth LE connection parameters. This parameters are negotiated at connection stablishment, and can be updated later through a connection update. Returns a new mibanda.LEParams instance.
>>> le = device.getLEParams()
>>> le.minimum_connection_interval
460
>>> le.maximum_connection_interval
500
>>> le.latency
0
>>> le.timeout
500
>>> le.connection_interval
500
>>> le.advertisement_interval
2400
Set current device date and time, dt is a datetime.datetime object.
Note
This method requires the device to be configured with UserInfo. Otherwise, it will raise an Application error: I/O. See mibanda.BandDevice.setUserInfo() for more info.
>>> from datetime import datetime
>>> now = datetime.now()
>>> device.setDateTime(now)
Get current device date and time. This characteristic could not be read directly; it need to be writen first, and then read. This process adds a bit of lag: the time of traveling packets. It returns a datetime.datetime object.
Note
This method requires the device to be configured with UserInfo. Otherwise, it will raise an Application error: I/O. See mibanda.BandDevice.setUserInfo() for more info.
>>> device.getDateTime()
datetime.datetime(2015, 1, 20, 21, 28, 30, 0)
Perform an internat test: it will vibrate and flash leds.
Warning
This action will erase status information on your device.
>>> device.selfTest()
Make a bluetooth pair between this host’s hardware and the Mi Band device.
>>> device.pair()
Set user information on device. This params as a whole are needed to avoid a status reset on the Mi Band. If you change any of this params, the Mi Band will erase all previous capture data, and initiate a new pairing process.
uid is a number that identifies the relationship between this host and this Mi Band. It may be any number, but it must have 10 or less digits.
male is a boolean param to set the user gender.
age is your age in years.
height is your height in centimeters.
weight is your weight in kilograms.
type_ is a binary int (0 or 1) that specify if this relationship should be rebuilt (1) or not (0). If 1, all saved data will be lost.
alias this is a stringfied version of the uid. You can safely left it blank, as it will be computed from the given uid.
>>> device.setUserInfo(1563037356, True, 25, 180, 80, 0)
Toggle LED status for a few seconds, using values for red (r), green (g) and blue (b), levels range from 0 (LED off) to 6 (max bright). You can use the mibanda.Colors predefined colors.
Note
This method requires the device to be configured with UserInfo. Otherwise, it will raise an Application error: I/O. See mibanda.BandDevice.setUserInfo() for more info.
>>> # set red color
>>> device.flashLeds(6, 0, 0)
>>> # set orange
>>> device.flashLeds(*miband.Colors.ORANGE)
Put the band in vibration mode up to 10 seconds, or until you tap the band.
Note
This method requires the device to be configured with UserInfo. Otherwise, it will raise an Application error: I/O. See mibanda.BandDevice.setUserInfo() for more info.
>>> device.startVibration()
Stop the vibration mode, if running.
Note
This method requires the device to be configured with UserInfo. Otherwise, it will raise an Application error: I/O. See mibanda.BandDevice.setUserInfo() for more info.
>>> device.stopVibration()
Vibrate times times. Each iteration will start vibrator on_time milliseconds (up to 500, will be truncated if larger), and then stop it off_time milliseconds (no limit here).
Note
This method requires the device to be configured with UserInfo. Otherwise, it will raise an Application error: I/O. See mibanda.BandDevice.setUserInfo() for more info.
>>> # faster vibration (10 times)
>>> device.customVibration(10, 25, 10)
>>> # water drop vibration (5 times)
>>> device.customVibration(5, 25, 1200)
>>> # longer vibrations, no 'off time' (5 times)
>>> device.customVibration(5, 500, 0)
Set the number of steps to steps to what will be considered your daily goal.
Note
This method requires the device to be configured with UserInfo. Otherwise, it will raise an Application error: I/O. See mibanda.BandDevice.setUserInfo() for more info.
>>> device.setGoal(8000)
Set the current step counter value to steps. It may be used to reset the counter.
Note
This method requires the device to be configured with UserInfo. Otherwise, it will raise an Application error: I/O. See mibanda.BandDevice.setUserInfo() for more info.
>>> setCurrentSteps(0)
Set the alarm 1 to ‘when’, see mibanda.BandDevice.setAlarm() for more info.
Set the alarm 2 to ‘when’, see mibanda.BandDevice.setAlarm() for more info.
Set the alarm 3 to ‘when’, see mibanda.BandDevice.setAlarm() for more info.
Clear the alarm 1, see mibanda.BandDevice.setAlarm() for more info.
Clear the alarm 2, see mibanda.BandDevice.setAlarm() for more info.
Clear the alarm 3, see mibanda.BandDevice.setAlarm() for more info.
Enable or disable the alarm number to when (a datetime.datetime object in the future). If you want a ‘smart’ wake up, then set smart to 1. repeat could be mibanda.Calendar.EVERYDAY, or a combination of days (i.e: SATURDAY | SUNDAY).
Note
This method requires the device to be configured with UserInfo. Otherwise, it will raise an Application error: I/O. See mibanda.BandDevice.setUserInfo() for more info.
>>> when = datetime.now() + timedelta(hours=8)
>>> device.setAlarm(1, 0, when, 0, mibanda.Calendar.MONDAY)
Holds the battery information for the Mi Band.
Battery level (in percentage), ranges from 0 (discharged) to 100 (full).
Date of last charge.
Counter of number of charges.
Current battery status, one of low, medium, full or not charging.
Minimum connection internal, in ms.
Maximum connection internal, in ms.
Connection latency.
Connection timeout, in hundredths of a second.
Connection interval.
Advertisement interval.
Mi Band characteristic UUIDs constants.
Holds the device related information: firmware version, hardware revision, etc.
Holds the Bluetooth LE device name.
Holds the user related information: uuid, gender, age, height and weight. Used to make a permanent bond with the device.
Special characteristic to do multiple tasks: LED/motor control, alarms, set current steps, step goal, etc.
Used to read current step count.
Configuration of Bluetooth LE conection parameters.
Used to get/set the date/time information on the device. Could not be read directly, first must be writen.
Holds battery information: status, level, charge counter and last charge date.
Warning
These may change after a new firmware release, please use UUIDs instead (when possible).
Mi Band characteristic handlers.
Handle for UUID USER_INFO.
Handle for UUID CONTROL_POINT.
Handle for UUID DATE_TIME.
Handle to do an automatic hardware test.
Handle for pairing device.
Constants used on alarm repeat pattern.
Common colors of Mi Band LEDs. You can create new ones: a combination of three integers that range from 0 to 6 (both included). The higher the number the brighter the LED, 0 is LED off.
Converts a string of hex numbers separated by a colon (:) to a string with the actual byte sequence. This is useful when sending commands to PyGattlib, because they can be expressed in the same way as wireshark dumps them; in example: 03:1b:05.
>>> data = mibanda.h2s("68:65:6c:6c:6f")
>>> print data
hello