Skip navigation

Moto Mods

9 posts

Install JDK and Android Studio


This tutorial will show you how to Install JDK, Android Studio, and the Moto Mods SDK on Ubuntu 16.04


Android Studio requires the Java Development Kit (JDK) so we will install that first. In terminal, type “sudo apt-add-repository ppa:webupd8team/java”. Follow the terminal commands shown




Once the installer is done, type “javac -version” and “java -version” to check if the JDK was installed.


Now that JDK is installed, we can now install Android Studio in Ubuntu VM, open firefox and download Android Studio 


Save the file and extract it



Create a folder called Apps in the /home/<username> directory. Move the extracted folder in the /home/<username>/Apps, using right click->Move To...


In terminal, navigate to the directory and execute “./”. Shown above. If you get a permissions error then, Navigate to Android Studio’s directory bin folder, give yourself permission for the .sh file and execute it



This is a new copy, Select the second option


Android Studio will launch



The Android Studio Welcome will show, click Next



Choose Standard Installation



Click Next



Hit Finish



Android Studio is now installed


Setup Moto Mods Project in Android Studio


Start a new Android Studio Project and configure your application name

Set Android API version to 6.0 (API level 23), Moto Mods only supports API level 23+ (Android 6.0+). It does not support earlier versions of Android.



It will install API23: Android 6.0 SDK



Create an empty activity



For beginning Moto Mods Development we will start with a Blinky application



Click Finish



Finally, the Android Studio Blinky application is setup, ready for development.



Install Moto Mods SDK


Now that Android Studio is installed and a project is created we need to add the Moto Mods SDK to the newly created project so that we can make API calls to the Reference Moto Mod


Download the Mod Mods SDK Library. Provided at:

Save the ZIP file.


Moto Mods Developer Steps 2.jpg


In your downloads folder, Right click on the “” and hit “Extract Here”


Once the ZIP is extracted, Right click and “Move To….”


Navigate to ‘/home/<username>’ and hit select



Once moved, open the “ModLib-01.00.000” folder and Move or Copy To…



Now we will put the SDK into our Android Studio Project. Move the .jar file into the /libs folder of our created project. ‘/home/<username>/AndroidStudioProjects/MotoModsDevelopment-Blinky/app/libs’



In the /res folder of /ModLib-01.00.000 there is a version.xml file that we need to move as well. Hit Move or Copy To...



Move or Copy “version.xml” to ‘/home/<username>/AndroidStudioProjects/MotoModsDevelopment-Blinky/app/src/main/res/values’



Shown below is how the “modlib-01.00.000.jar” and “version.xml” should look in the project explorer tree.

















The SDK is now added to the project and we can start using it to develop.


The Moto Mods expansion for the Moto Z phones is not for the average tinkerer.


I set out to do the "hello world" of hardware design, blink an LED. Once you can do that, sky's the limit.


So, let's start from the beginning, part 1, getting set up:



To setup everything you need to develop with Moto Mods i’ve split this setup tutorial into 2 articles. The first one showing you how to setup Android studio and the Moto Mods SDK in Linux, which requires the setup of a virtual machine if using any other OS. The second article, showing you how to install all the firmware tools you will need for development. 


Two software tools are required for developing on Moto Mods platform: Android Studio 2.0+ and the Moto Mods SDK Library. Your application can be made on any Android Studio platform. Firmware development at this point requires Linux. To develop the firmware using windows, we will setup a Virtual Machine (VM) using VirtualBox and version 16.04 of Ubuntu


A little background about what we're about to do. In order to develop with Moto Mods, we need to install and configure:

  • Android Studio - To develop android applications to control the Moto Mods MDK functionality
  • Moto Mods SDK - To access hardware through API calls in your application
  • Flashing and Debugging tools for Firmware - OpenOCD, GDB, USB and FTDI libraries
  • Firmware runs Nuttx OS (RTOS) on the MuC - We need to build and Compile Nuttx in Ubuntu
  • Nuttx to be configured with the standard Linux menuconfig utility
  • Compile the MuC bootloader, muc-loader is a bootloader for Nuttx on STM32L4 devices
  • Flash the MuC with either the MDK Utility Android App on the Moto Z Droid or via SWD using OpenOCD

These tools are all provided from the github repository:


The Mod Mods MDK comes with a backplate pictured below that attaches to the back of the Moto Z Droid via magnets and pogo pins. This Adapter, they call a reference Moto Mod, pictured on the right, that attaches directly to the phone and has a slot and connector for prototyping with anyone of the personality cards. The Perforated Board is then plugged into the connector on the reference Moto Mod, then the cover over that, pictured on the left. The Reference Board is where we will load the firmware. Built in is an Cortex-M4 based STML476, it provides onboard control of the GPIO and various standard interfaces.


From Moto Mods Developer Website:

“The example Personality Cards require custom firmware on the Reference Moto Mod to run. Each Personality Card includes an onboard EEPROM queried by the MuC (STML476) bootloader on attach. If needed, the MuC bootloader will request the Moto Z to download and install the latest firmware needed for the attached personality card.


When using the Perforated Board, or Pi HAT Adapter Board, don’t forget to create a custom bootloader for your MuC that includes your unique VID/PID, or the prototype VID 0x42. If you don’t you’ll end up overwriting your custom firmware with the default MuC firmware each time you boot!”



Install Ubuntu on a Virtual Machine

Download VirtualBox from the link above, since we are using Windows, download from the “Windows hosts” link
























Once VirtualBox is installed, open VirtualBox Manager

























Create a name for you Virtual Machine and select Linux as the Type of OS and the Version as Ubuntu (64-bit)






















Hit Next, Ubuntu recommends at least 2 GB of Virtual RAM.





















Ubuntu recommends at least 25GB of HD space and a minimum of 10GB but we are going to install programs so we don’t run out of space during the setup process. Ignore that 8GB






















Create a Virtual HD, choose VDI (Virtual Disk Image)























Dynamically allocate the disk so you save space on your real drive.























I created a disk with 30GB of space.























Once you hit create, the VM is done being set up. We now have to install Linux on it, We do this the same as a fresh copy of Windows. Boot from disk, but it's a virtual disk image.






















Go back to your browser... Since we are using 64-bit Windows, we will run 64-bit Ubuntu on our VM, download the “Ubuntu 16.04.2 LTS Desktop Image”. At this time, it will download an ISO file called “ubuntu-16.04.2-desktop-amd64.iso”





















Back in your VM manager settings, Click on the Small CD symbol to the right of the Optical Drive: selection and in the dropdown select “Choose Virtual Optical Disk File...”


































Open “ubuntu-16.04.2-desktop-amd64.iso”

























It will load the ISO file into the VM IDE Storage Controller. Click Ok. This will allow us to boot from the Ubuntu disk image



















Start the VM, and the GUI screen will pop up.






















When the GUI pops up it will go to the Ubuntu install screen.






















Hit “Install Ubuntu” and Continue, we don’t install updates because we are going to install all the tools and we want make sure versions stay the same.
























Choose “Erase Disk and Install Ubuntu”, and hit “Install Now”

























This will partition the VDI drive, Install Ubuntu on the “VirtualBox Disk Image” file that has the name Moto Mods Development.vdi ,and it is about 8GB in size. Click Continue.



Select English


Fill out fields and choose, “Log in automatically”, click continue 


Ubuntu will Install….



After installation is complete, hit “Restart Now”


The VM will reboot and Ubuntu will show Desktop, Firefox and terminal are pre-installed. We will use these to install Android Studio, Moto Mods SDK, and the Firmware tools using installer code copied from the Moto Mods Developer website.



Launch Terminal from the search (Purple Ubuntu symbol button) 



This details the steps to use the usb2 sample project with your Moto Mods Development Kit.  Hat tip to Screen mirroring a Moto Z to HDMI, with the Moto Mod Development Kit (MDK) for the structure (and the great details).


  1. Moto Z, Moto Z Force, or Moto Z Play phone
  2. Moto Mods Development Kit
  3. USB OTG cable (MicroUSB)
  4. USB 2.0 Thumb Drive (or other USB 2.0 device)
  5. MDK Utility app (from the Play Store)



Building your Firmware

The firmware used is the unmodified MDK-USB2 example.  This is the usb2 project in nuttx/configs/muc.

  1. Setup your build environment as per Embedded Firmware Development
  2. Download the source, stopping after build/install kconfig-mconf as per Developer Tools: Build from Source: Build Firmware
    1. Create a BUILD_TOP environment variable with the path to the cloned repositories
  3. Build the usb2 firmware with the following commands

    $ export PATH=$PATH:$BUILD_TOP/manifesto:$BUILD_TOP/bootrom-tools

    $ cd $BUILD_TOP/nuttx/nuttx

    $ make distclean

    $ cd $BUILD_TOP/nuttx/nuttx/tools

    $ ./ hdk/muc/usb2

    $ cd $BUILD_TOP/nuttx/nuttx

    $ make

  4. The compiled firmware is in the nuttx.tftf file.  Transfer this file to your Moto Z with adb, an SD Card, or a file sharing service such as Dropbox or Drive.

Configure the MDK

  1. Detach the MDK from the Moto Z and remove any board or personality card.
  2. On the MDK, set dip switch A3 to ON
  3. Set the remaining dip switches to OFF.
  4. Reattach the MDK to the Moto Z.

Flash the Firmware

  1. Install MDK Utility on your Moto Z.
  2. Set the Mode to Developer Mode (if not there already)
  3. Tap Select File(s) and choose your nuttx.tftf file you built earlier
  4. Tap Perform Update
  5. When prompted whether to update unsecure firmware, select CONTINUE
  6. A Toast message will appear reading Firmware update successful
  7. In the MDK Utility, the Moto Mods Status should now read:
    Package NameDefault

Attach your USB 2.0 Device

  1. Plug your USB device into the OTG adapter
  2. Plug the OTG adapter into USB #3 (the bottom and only microUSB port on the MDK)


Note: USB 2.0 devices can also be used through the USB #2 (TypeC middle port on the MDK).  You will need a TypeC OTG cable.  When using the TypeC port for USB 2.0, set A4 to ON and all other dip switches OFF.

Really Note: The TypeC port does not auto-swap.  If things should be working but aren't, try flipping the cable over.

After much messing around I've achieved my initial goal: getting the Moto Z to display on an HDTV.



  1. Moto Z, Moto Z Force, or Moto Z Play phone
  2. Moto Mods Developer Kit (MDK)
  3. SlimPort Micro-USB to HDMI adapter
  4. HDMI cable
  5. HDTV
  6. MDK Utility app (from the Play Store)
  7. MDK-COMPUTE firmware for the MDK (nuttx.tftf)
  8. Bent paperclip



  1. Install MDK Utility on your phone
  2. Download the MDK-COMPUTE firmware (nuttx.tftf)

    I assert this firmware was built by me from Motorola sources. However I've not tested beyond a single trial, which seemed to work. It could brick your MDK, or your phone, or your TV, kill your dog and burn your house to the ground.

  3. Detach the MDK from your phone, remove any board or personality card
  4. Set dip switches A1 & A3 to ON (i.e. closest to the camera cutout).
  5. Set the remaining dip switches to OFF.
  6. Reattach the MDK to your phone.
  7. Launch MDK Utility.
  8. Set the Mode to Developer Mode (if it's not already so).
  9. Click Select FIle(s) and choose the MDK-COMPUTE firmware (nuttx.tftf) that you downloaded.
  10. Click Perform Update.
  11. MDK Utility will ask you to confirm you wish to install this unsecure (i.e. unsigned) firmware. If you are sure then click continue.

    If you are in any way uncertain about this procedure, or the firmware then click Cancel.

  12. In a few seconds you should get a pop up saying Firmware update succeeded.
  13. Check that the Moto Mods Status at the top of the screen reads
    Package NameDefault
  14. Plug the Slimport adapter into USB-3 (micro USB) port on the MDK
  15. Plug the HDMI lead into the Slimport adapter and your TV
  16. On your TV select the appropriate HDMI input
  17. Unlock your phone, the screen should now be mirrored on your TV



How do I build the firmware myself?

It is the unmodified MDK COMPUTE example.

  1. Setup your build environment as per Embedded Firmware Development
  2. Download the source, stopping at build/install kconfig-mconf as per Developer Tools: Build from source: Build Firmware.
  3. Build NuttX with the following commands

    $ export PATH=$PATH:$BUILD_TOP/manifesto:$BUILD_TOP/bootrom-tools
    $ cd $BUILD_TOP/nuttx/nuttx
    $ make distclean
    $ cd $BUILD_TOP/nuttx/nuttx/tools
    $ ./ hdk/muc/compute
    $ cd $BUILD_TOP/nuttx/nuttx
    $ make

  4. You're done, the firmware is built as nuttx.tftf

For all Moto Mods enthusiasts in Europe and China, you can now buy the Moto Mods Development Kit (MDK) and associated accessories from element14.

Find out more about the MDK here:

At the end of July, a couple of Motorola software engineers formed a Hackathon team to bring up the PaPiRus E-Ink display on a MotoZ phone using the new Mods Development Kit.  Most of the work consisted of porting the existing open-source display driver (epd.c) from the Raspberry Pi running Linux to the MDK running NuttX.  Although our team didn't have much prior hardware experience, we expected the porting effort should be relatively straight-forward since the MDK environment is designed to facilitate porting hardware and software from other platforms by making use of common hardware interfaces such as I2C, SPI and GPIO, and through it's RPi HAT Adapter card which aligns pins from RPi's GPIO to the MDK.


During the 2.5 day event (working late nights), the team was just able to bring up the display and draw an image.  After completing the work, the team artificially diced up the code changes into a series of 8 commits posted to this MDK epd Github link which roughly align to milestones described in subsequent posts below.  But I want to emphasize that this project was a learning experience for us, and was just done to the level of quality of a rushed hackathon project


We hope this example demonstrates that without much experience, any software developer should be able to select a random hardware project from Raspberry Pi or other platforms and get them working on Motorola phones with relatively low effort.  And also hopefully inspire someone to continue work on this MDK PaPiRus driver.


-Jason Freund

Motorola Mobility




Moto Mods Development Basics

Posted by payam Aug 7, 2016

Moto Mods are hardware enhancements

  • Snap seamlessly to the rear of the Moto Z
    • Magnets provide a strong attraction
    • Hotplug, no reboot needed
  • Provide a wide variety of interfaces to enable 3rd party creativity
    • Enhance existing functionality, like battery life
    • Introduce entirely new features
  • Tight integration into Android OS
    • Utilize standard behaviors and interfaces
    • SDK to allow for unique experiences


Fixed dimensions for future generations ensure compatibility.


  • X/Y dimensions of Moto Z
  • Size, placement, and layout of the Moto Mods Connector
  • Size, placement, and cone angle for the Moto Z camera
  • Placement of the magnets for connection
  • Antenna keep-out areas to ensure performance.







1 Mbit/s


15 Mbit/s


10 Mbit/s


6MP raw10 @ 60fps, 13MP raw10 @ 24fps


24-bit stereo @ 192kHz


1080p @ 60fps


Video: 4K @ 30fps, Audio: 8 channels @ 192kHz


480 Mbit/s


5 Gbit/s


General Purpose Input and Output

Brains and Brawn

Moto Mods Micro Controller (MuC)

Motorola High Speed Bridge (Moto Bridge)

  • Contained in every Moto Mod
  • Provides command and control
    • Enumeration
    • Greybus Protocols
    • Moto Bridge management
  • Power Management
  • Firmware Upgrades
  • Low Speed Interfaces
    • I2C, SPI, UART, GPIO
  • Analog to Digital Converters
  • ARM7 Cortex-M4F
  • Provides high speed interfaces at low power
  • Simultaneous support of DSI, CSI, I2S, and HSIC
  • Powered on and off as required
  • Firmware is upgraded by MuC
  • MHB protocol allows MuC to control Moto Bridge functionality without modifying firmware
  • UART connection to MuC
  • Not required in all Moto Mods

Greybus Protocols



Configuring and controlling a DSI or MyDP video device


Display Backlight Control


Battery Metering

Power Transfer

Charge/Discharge to Moto Z


Configuring and controlling I2S audio streams (raw or over Moto Bridge)


Human Interface Device input


USB 2.0 (device) or USB 3.1 (host/device)


Application specific data pipe


Moto Z Behavior



Integrated as Android Secondary Display.  Mirroring by default, or use Presentation


No default integration


Integrated battery metering

Power Transfer

Moto Mod reports current capabilities, Moto Z controls state transitions


Audio device types mirror Android.  Default routing rules based on current device(s).


Keyboard input provided to the frontmost app, normal mouse integration


USB devices available through Android USBManager (if they don’t just work)


No default integration, but Permissions required for ‘Unrestricted Mod Access’


Moto Mods Development Kit (MDK)

  • Contains MuC and Moto Bridge
  • Integrated battery and charging circuit
  • Perforated Boards enable flywired projects
  • Personality Cards provide hardware to go with the examples, including released schematics
  • 80pin interface allows easy swapping
  • USB Ports for Serial Wire Debug/Console, power, data, and MyDP


MDK Users Guide



Perforated Board

Perforated Board


HAT Adapter Board

HAT Adapter Board


Moto Mods Quick Start Guide

Posted by payam Aug 7, 2016

Setup and Tools

What you need:

  • Moto Z
  • Computer running Linux (including as a virtual machine)
  • Moto Mods Development Kit
  • USB Type-C cable

Tools Setup

Clone and Build

Flash Bootloader and Firmware


Example and Developer Modes

Example Mode simplifies switching between Personality Cards

  • VID = 0x312
  • Custom bootloader that reads the PID from an EEPROM in the Personality Card.
  • The Moto Z will download and update the firmware
  • Example firmwares monitor switches at the 80pin header to detect insertion/removal.  The MuC resets on transition.

Always detach the Reference Moto Mod from the Moto Z before inserting/removing a Personality Card.


Developer Mode lets you hack without system interference

  • VID = 0x42
  • Bypass Moto Z’s firmware update check
  • Flash firmware using the MDK Utility
  • “developer” config in the muc-loader repository

The MDK Utility requires Personality Cards removed from the Reference Moto Mod before allowing the switch to Developer mode.



Blinky is the “Hello, World!” of Moto Mods.

  • Raw protocol used for simple on/off switch
  • Uses hdk_powered as the base project with battery and charging support


Firmware Reference Paths




Project Definition






Source Files






version-major = 0

version-minor = 1

Version of the Manifest file


vendor-string-id = 1

product-string-id = 2

; Interface vendor string (id can't be 0)

[string-descriptor 1]

string = Motorola Mobility, LLC

; Interface product string (id can't be 0)

[string-descriptor 2]

string = MDK-BLINKY

Vendor and Product String definitions

; Control protocol on CPort 0

[cport-descriptor 0]

bundle = 0

protocol = 0x00

; Control protocol Bundle 0

[bundle-descriptor 0]

class = 0

; Motorola specific on CPort 1

[cport-descriptor 1]

bundle = 1

protocol = 0xff

; Debug related Bundle 1

[bundle-descriptor 1]

class = 0xff

Greybus and Moto Mod interfaces for enumeration, communication, and control.

; Battery on CPort 2

[cport-descriptor 2]

bundle = 2

protocol = 0x08


; PTP on CPort 3

[cport-descriptor 3]

bundle = 2

protocol = 0xef


; Battery related Bundle 2

[bundle-descriptor 2]

class = 0x08

Battery and Power Transfer Protocols for metering and charging.


These are grouped together into a single Bundle, meaning both must enumerate properly for either to be accessible.

; RAW interface on CPort 4

[cport-descriptor 4]

bundle = 3

protocol = 0xfe


; RAW Bundle 3

[bundle-descriptor 3]

class = 0xfe

Raw Protocol, used for basic on/off switch.



Blinky is based off hdk-powered.mnfs.  hdk.mnfs should be used if your project does not require a battery.


nuttx/nuttx/config/hdk/muc/blinky Project Files



Makefile definitions

Script to configure environment to build


Moto Mod interfaces for enumeration, communication, and control.

Modified via “make menuconfig”


After creating your project, make it the active one:

cd $BUILD_TOP/nuttx/nuttx

make distclean

cd $BUILD_TOP/nuttx/nuttx/tools

./configure hdk/muc/blinky

cd $BUILD_TOP/nuttx/nuttx



Blinky is based off of base-powered.  base_unpowered should be used if your project does not require a battery.




Update Kconfig to add your new project’s support:


  bool "Blinky LED Mods Raw support"

  default n

  depends on GREYBUS_RAW

  select DEVICE_CORE

  select STM32_TIM6


    Enable Blinky LED Raw support


This integrates Blinky with the ‘make menuconfig’ and defines any build dependencies needed to support the ‘Board Selection’ step later.   A primer on the NuttX menuconfig is available here:


Additional information on configuring NuttX can be found here:


Update the VID/PID

Go to the nuttx top and run use menuconfig

cd $BUILD_TOP/nuttx/nuttx

make menuconfig

Select “System Type” from the top level menu


Update the Board VID and PID

For Developer Mode:

VID = 0x42

PID = 0x1


Select <Save>, then <Exit> to the top level

Board Selection

Select “Board Selection” from the top level menu

Scroll to “Blinky LED Mods Raw Support” and press the space bar to toggle On


Select <Save>, then <Exit> to the top level

Setting the Manifest

1. Select “Application Configuration” from the top level menu

2. Select “Greybus Utility”

3. Select “manifest name”.  Type “hdk-blinky” in the dialog box and press Enter. 

Select <Save>, then <Exit> to the top level

Setup Raw Support

1. Select “Device Drivers” from the top level menu

2. Select “Greybus Support”

3. Scroll to “Vendor Raw Support” and press the space bar to toggle On


Select <Save>, then <Exit> to the top level

Enable Timer6 for LED Toggle Interrupts

1. Select “System Type” from the top level menu


2. Select “STM32 Peripheral Support”

3. Scroll to “TIM6” and press the space bar to toggle On


Select <Save>, then <Exit> to the top level

Update the Makefile

Add the new files to nuttx/nuttx/config/hdk/muc/src/Makefile


CSRCS += stm32_modsraw_blinky.c



To ensure the changes made with “make menuconfig” are permanent, the nuttx/nuttx/.config should be copied over top the nuttx/nuttx/config/hdk/muc/{project}/defconfig

Setup Raw Device Driver

Copy stm32_modsraw.c to stm32_modsraw_blinky.c to use as a starting point.

Customize the device_driver and associated structures:

static struct device_raw_type_ops blinky_type_ops = {

    .recv = blinky_recv,

    .register_callback = blinky_register_callback,

    .unregister_callback = blinky_unregister_callback,


static struct device_driver_ops blinky_driver_ops = {

    .probe = blinky_probe,

    .type_ops = &blinky_type_ops,


struct device_driver mods_raw_blinky_driver = {

    .type = DEVICE_TYPE_RAW_HW,

    .name = "mods_raw_blinky",

    .desc = "Blinky LED Raw Interface",

    .ops = &blinky_driver_ops,


Implement Driver Functions

From the ops structures, there are 4 functions to be implemented for Raw:

  • blinky_probe()
    • Called by kernel after device registration
  • blinky_recv()
    • Called by greybus when data has arrived on the Raw channel
  • blinky_register_callback()
    • Called by kernel to provide a pointer to the raw_send_callback.  The driver should save this pointer and use when sending data to the Moto Z
  • blinky_unregister_callback()
    • Called by the kernel when the device is no longer registered


static int blinky_probe(struct device *dev)


    gpio_direction_out(GPIO_MODS_LED_DRV_3, LED_OFF);

    gpio_direction_out(GPIO_MODS_DEMO_ENABLE, 0);

    return 0;


static int blinky_recv(struct device *dev, uint32_t len, uint8_t data[])


    if (len == 0)

        return -EINVAL;

    if (data[0] == 0 || data[0] == '0')





   return 0;


Implement Behavior

For Blinky, 3 other functions are implemented to provide the actual behavior:

  • blinky_timer_start()
    • Called when a Raw message arrives with the ON command
    • Creates and starts the timer used to blink the LED on the Reference Moto Mod on and off
  • blinky_timer_stop()
    • Called when a Raw message arrives with the OFF command
    • Cancels the running timer and ensures the LED is off
  • blinky_timer_handler()
    • Handles interrupts from the timer and toggles the GPIO state


These functions also reside in stm32_modsraw_blinky.c

Register the Device Driver

  • Open nuttx/nuttx/configs/hdk/muc/src/stm32_boot.c
  • In the devices[] array, add the following:




        .type = DEVICE_TYPE_RAW_HW,

        .name = "mods_raw_blinky",

        .desc = "Blinky LED Raw Interface",

        .id   = 0,




  • In the board_initialize() function, add the following:



  extern struct device_driver mods_raw_blinky_driver;




Blinky Support Application (MDK Utility)

Your Moto Mod project may require an Android application to unlock its full capabilities.  To this end, Moto has released the modlib.  This library enables your app to query and receive Moto Mods status, as well as controls specific to the different Protocols.


Blinky uses two main components from the modlib:

  1. ModManager
    1. Provides Moto Mod Connect/Disconnect status
    2. Provides details about currently attached Moto Mod
    3. Allows access to Moto Mod protocols and handles permissions
  2. Raw access
    1. Retrieve File Descriptor to talk to the Moto Mod’s Raw protocol


The MDK Utility provides other developer functionality as well.  See for more detail.

Blinky Application Setup

Ensure that Android Studio 2.0 and the Android SDK API 23 is installed.

Download the modlib from

Open Android Studio and create a New Project


Then add the modlib.jar and version.xml files to your Project

cp modlib-{version}.jar $APP_TOP/app/libs

cp res/version.xml $APP_TOP/app/src/main/res/values


AndroidManifest.xml for all Moto Mods

To be a Moto Mods aware application, features and permissions must be added:


<uses-feature android:name="com.motorola.hardware.mods"/>

This defines your application as using the Moto Mods feature for Play Store filtering




   android:value="@integer/moto_mod_services_version" />

This uses the value from the version.xml file as the Moto Mods Services version.  This is used for future compatibility checks as Moto Mods capabilities expand.


<uses-permission android:name="com.motorola.mod.permission.MOD_ACCESS_INFO" />

This permission allows access to the ModManager for access to Moto Mods information



Blinky access to the Raw Protocol

Blinky makes use of the Raw protocol as a custom data path to turn the LED on and off.  Since the Raw protocol provides direct access to communicate with the Moto Mod, it is protected by a unique permission in the AndroidManifest.xml.

<uses-permission android:name="com.motorola.mod.permission.RAW_PROTOCOL" />

This permission (when granted by the user) allows this Application to access the Raw protocol.


Before opening Raw, you should always check the VID/PID to ensure this is the Moto Mod you wish to communicate with.  And, of course, check with the user:

requestPermissions(new String[]{ModManager.PERMISSION_USE_RAW_PROTOCOL},



Implement onRequestPermissionsResult() to handle the result of the Permission request.  Only request the Raw file descriptor after receiving Permission or an exception will be thrown.

Handling Moto Mods State

Obtaining the basic of Moto Mods is done through the ModManager.  First and foremost, your application should determine whether the current device supports Moto Mods.

if(ModManager.isModServicesAvailable(context) == ModManager.SUCCESS) {
  // This device supports Moto Mods



The Moto Mods state can either be monitored through Intents, or via direct callbacks from the ModManager.  Blinky makes use of a BroadcastReceiver and Intents.

modReceiver = new MyBroadcastReceiver();

IntentFilter filter = new IntentFilter(ModManager.ACTION_MOD_ATTACH);


context.registerReceiver(modReceiver, filter, ModManager.PERMISSION_MOD_INTERNAL, null);


For additional information on the ModManager, refer to

Check what was attached

As mentioned earlier, when using the Raw protocol you should always verify the VID/PID.  Never open the Raw protocol simply because it is available, since the actual data will be custom to that product.

String action = intent.getAction();

if(action != null ){


int vid = intent.getIntExtra(ModManager.EXTRA_VENDOR_ID,

int pid = intent.getIntExtra(ModManager.EXTRA_PRODUCT_ID,

if ((vid == MY_BLINKY_VID) && (pid == MY_BLINKY_PID)) {





When using Raw, reads and writes should be done separate from the UI thread.  The MDK Utility handles this via the RawPersonalityService class.

Opening the Raw Interface

The Raw protocol is exposed to Android applications via a ParcelFileDescriptor provided by the ModManager:


List<ModInterfaceDelegation> devices =



if (devices != null && !devices.isEmpty()) {

   ModInterfaceDelegation device = devices.get(0);

   Log.d(Constants.TAG, "openRawDeviceifAvailable checking " + device);


   parcelFD = modManager.openModInterface(device,



This code block obtains the Raw interface and retrieves a file descriptor that is used for direct read/write access.

Sending Data over Raw

FileDescriptor fd = parcelFD.getFileDescriptor();

outputStream = new FileOutputStream(fd);

outputStream.write((byte[]) cmd);


Although sending data over Raw appears simple, this should always be performed on a separate Thread from the UI or via an AsyncTask.  Otherwise, you will may receive ANR while your application is attempting to communicate with the Moto Mod.


Moto Mods adds increased functionality to the Moto Z with Insta-Share Projector, JBL SoundBoost Speaker and offGrid Power Pack. (all images via Moto-Mods)


Every year smartphone companies release a new iteration of their flagship devices that seemingly have marginal upgrades from their previous line - usually a slightly higher screen resolution, better camera and a larger battery. That’s to say revolutionary upgrades with new technology don’t happen every year and what’s more, users typically can’t upgrade their existing phones beyond increasing the storage (provided it has a microSD slot) and increasing battery life with an external pack.


How about they stop telling us what we should upgrade to, but give the ability to change it ourselves?


Some companies such as Google, Phonebloks and PuzzlePhone (among a host of others) are looking to change the way these devices are upgraded by going modular - different cameras, batteries, speakers and storage can be switched out when damaged or when better hardware is introduced. While all of those modular phones hold promise for the way we will use smartphones in the near future, none of them have hit the market as of yet, except for Motorola’s (Lenovo) new Moto Z and the introduction of their Moto Mods.



The Moto Z itself features a 5.5-inch (1440 X 2560 resolution) AMOLED screen, 4 GB RAM, 13MP camera and a 2600mAh Li-Ion battery.


The Moto Z itself sports most of the hardware you would expect in any flagship phone- a 5.5-inch AMOLED display (1440 X 2560 resolution @ 535ppi), 4 GB of RAM, 13MP camera, 32/64 GB of storage (with up to 256 GB using microSD slot) and a 2600mAh battery. Nothing out of the ordinary or truly innovative when compared to others currently on the market but when you factor in the upcoming Moto Mods, the phone clearly separates itself from the others.


Motorola is currently releasing four Mods along with a slew of interchangeable back-plates from several different manufacturers that are designed to increase the phone’s functionality. Each Mod connects to the back of the phone using a series of strong magnets (housed inside the phone itself) to hold them in place and automatically adjusts itself when connected- meaning users simply snap them in place and start using the new functionality.


Those Mods include the Insta-Share Projector - projects media onto flat surfaces from up to 70-inches away, JBL SoundBoost Speaker-gives the phone a powerful stereo external speaker (complete with stand) and an Incipio offGrid Power Pack- gives the phone increased battery life. Notice I said four Mods, the last turns the Moto Z into a development platform using the Moto Mods Development Kit (MDK).



The Moto Mods Development Kit includes a reference Moto Mod, Perforated Board and example cover plate. Hope the kit comes with a few of these. How many perf-boards have you destroyed?


The Development Kit is essentially a blank Mod that houses a Perforated Board that can be used as an adapter platform for other dev boards, including Raspberry Pi HATs and Motorola’s Personality Cards. This essentially allows developers to design their own Mods or other projects with the Moto Z without altering the ROM. They’ve even included the APIs necessary for developing with Android.


The Perforated Board is essentially the primary platform for Mod development and includes 80 connection pins with 26 rows of soldering points to attach the other dev boards directly to the phone. The MDK also includes the HAT adapter that acts as a bridge to connect any number of RPi HATs to the Moto Z and features a standard 40-pin header and 15-pin camera and display header as well. Of course in order to use the HATs, it needs to be connect to the 80-pin connector on the Moto Mod seen above.


For strictly developing Mods for the Moto Z, Motorola designed Personality Cards for building prototypes. These are end-to-end reference modules that can be attached for developing your own Mods that include samples for audio, battery, display and even a temperature sensor if the project calls for it. If you actually build your own Moto Mod and want to sell and want to bring to the market, you’ll have to collaborate with Motorola- meaning no using any personal online retail entity or community, which could be a turn-off for some.


Then there’s the cost- the phones come in two flavors (minus the MDK) with the standard Moto Z costing $624 and the Force version (larger batter @ 3500mAh and camera @ 21MP) costing $720 respectively. Will this Moto Z be the next big thing in dev?


You can read more about the Moto Mods Development Kit and the personality cards that element14 have available.


Have a story tip? Message me at: