Kodama DK

Overview

kodamaLogo

Welcome, Kodama developer! This guide covers how to get started with the hardware and software developer kit v0.1.0 .

V0.1.1B changelog
 - update package and initial package are now the same
 - NET 2.0 switch   
 - interface interactive play area wireframe display options
Hardware DK

In order to use the Kodama SDK you need the Kodama development kit.

Your Kodama development kit should include:

  • 1xKodama playground
  • 1xKodama tracker
  • 1xUSB mini cable

learn how to setup your Kodama developer kit

If you do not have your developer kit, order it here .

If any of these items are missing from your kit, please contact us

SDK for Unity

Features

  • Non-optical and real-time 3D positioning for one tracker
  • Unity implementation via USB serial interface
  • Smart orientation system
  • BLE connectivity
  • Android and iOS support
  • Windows and OSX support
  • ARkit ready

Development System Requirement

Target System Requirements

  • Device with BLE interface (Amazon TV, Apple TV, tablets…)

Join our community

Getting Started
Software Setup
  • Download and install USB drivers:

  • Download the latest version of Unity.

    • During the install, make sure that you have selected iOS Build Support if you are developping for iOS.
    • If you are developing for Android select Android Build Support. unitySettings
  • Create a new Unity project

  • Download the Kodama SDK package. You can download it here v0.1.1b.

  • Double click the package and click to import it: import

  • in the Unity top bar in the Kodama SDK section, you can activate the .NET 2.0. activating that option will enable USB support for communication with the Kodama mat via USB. net switch If your project doesn’t use the USB interface, or doesn’t require .NET 2.0 you can turn deactivate this option before building in order to reduce build size.

Hardware Setup

Hardware Definitions

  • Kodama MAT

    Represents the foor of your 3D scene. The ON/OFF switch is used for wireless only. You can keep the mat OFF all the time except to connect it to a wireless device. The USB interface is used for development and charging your mat.

  • Kodama tracker

    The controller. Move the tracker with your hand to control the digital representation.

  • USB mini cable

    Used to connect the Kodama playground to your PC or Mac.

Hardware Setup for testing with Unity

Checkout this video to see how to get started

The hardware developer kit can be used with unity in play mode to test your prototypes without having to build via a USB serial interface.

In order to test a unity scene, follow these steps before entering play mode:

  1. Place the MAT in front of you with the switch on OFF position.
  2. Make sure the tracker is at least a meter away from the mat.
  3. Connect the MAT to your computer with USB mini.
  4. Enter play mode.
  5. Bring the Tracker over the MAT and start interacting.
  6. Do not move the MAT during play mode.

Hardware Setup for testing on device

In order to test on device follow these steps:

  1. Make sure the MAT is charged and disconnect the USB cable.
  2. Place the MAT in front of you with the switch on OFF position.
  3. Make sure the tracker is at least a meter away from the mat.
  4. Put the switch on ON position.
  5. Launch the app on device.
  6. Bring the Tracker over the MAT and start interacting.
  7. Do not move the MAT while playing.

If you move the mat while testing on device or if for some reason the tracking gets out of control, just put the tracker a meter away and turn the mat OFF then ON. It will automatically reconnect to the device.

Unity Package content

Package Strucutre

This is the content of the package: imagestructure

  • Example contains the example scenes.
  • Plugins contains the orginal plugins files.
  • Prefabs contains the Prefab Gameobjects that make the Kodama 3D tracking run in your scenes.
  • Resources contains additional prefabs that deal with connectivity.
  • Scripts contains C# scripts that are essential to the Kodama Kit.
Example Scenes

Example scenes demonstrate basic usage of the Kodama SDK In the example folder there are two scenes that demonstrate the workflow of the SDK:

loadScreen scene

This scene contains the interfaceSelection prefab that detect which platform you are running, and uses appropriate data connectivity (BLE or USB). Once the prefab has detected your platform it loads the scene. You can customize which scene to load in your build settings and by changing the index in the Scene to Load parameter:

loadScreenScene

testScene

This contains the tracking reference area, the gizmo represents the limits of it and can be scaled with the public variable on the Tracking System script attached to the trackingArea prefab, for testing purposes this scene can be started and will initiate the USB connectivity automatically.

  • The prefab trackingArea represents the tracking space in 3D. You can adjust the volume scale by modifying the tracking scale, this is useful if you already have custom scenes with defined scales. testScene

    • the child object tracker, is the raw 3D position of your tracker relative to the MAT.
    • the child object wireframe represents the limits of the play area, it is useful to let the user know they are getting out of bound. the wireframe wireframe
  • The Character gameObject has the Follower Script, the purpose of this script is to follow the tracker prefab with data smoothing and processing. You can add the Follower Script to any gameobject. Rotation options are using the direction of movement to estimate an orientation for a better movement result. You can choose to activate or deactivate the Rotation option.

followerscript

Prefabs
  • InterfaceSelection: this prefab should be put into the first scene of the game and only executed once, this starts the connectivity depending on the platform, in the case of BLE in iOS or Android is highly recommended to have it in a first empty scene that only serves as a loader.

  • trackingArea: this prefab serves as a reference for the tracking system. It can be moved in the scene and can be scaled with the public variable on the script. Inside there’s the tracker which is the GameObject that will change the position based on the tracking system.

  • bleStatus: Example of how to implement UI showing the status of the BLE connection.

Scripts
  • follower: attach this script to the GameObject you want to move with the tracking system and assign the tracker as a target, this implements a simple filter for the movement and allow to apply rotation to face the direction of the movement.
Creating a custom scene

explain how to create a new scene step by step explain how to scale the tracking area create new scenes etc…

Create a new scene.

Drag and drop the trackingArea prefab into the scene: This gameObject serve as a reference point for the tracking system, the red lines represent the limit of the tracking.

To scale the area use the public value Tracking Scale in the script attached to the trackingArea prefab.

Inside the trackingArea we have the tracker that represents the position of the object in the real world, by default the Mesh Renderer component is disabled, if you want to see the raw data input you can enable it.

Follower: (How to move the desired gameObject in the scene) We have created a script that serve as a light filer for the tracking and allows to have rotation facing the direction of the movement in the gameObject we want to move in the 3d environment.

Attach the follower script to the desired gameObject and set the Target reference to the tracker gameObject inside the tracking area.

The script allows you to enable/disable the rotation function, and once enabled to lock the desired axis.

This script is just and example of how to implement a following function that allow rotation, feel free to experiment and create your own version of it, or use directly the raw data.

How to test: Just connect the Kodama Mat and start the scene, the tracking area would create the serialInterface to comunicate with it. If you prefer to test the whole project would be recommended to start from the loadScene.

Publishing
Unity to iOS

Amazing Resources Unity Tutorial: Building your Unity game to an iOS device for testing Cocoacasts: What Are App IDs and Bundle Identifiers Choosing a Bundle Identifier Below is an excerpt from Cocoacasts You may read the full article here for more information on Bundle IDs and App IDs. They have great resources!

A bundle ID or bundle identifier uniquely identifies an application in Apple’s ecosystem. This means that no two applications can have the same bundle identifier. To avoid conflicts, Apple encourages developers to use reverse domain name notation for choosing an application’s bundle identifier. Allowed characters are alphanumeric characters, periods and hyphens.

Let’s take Cocoacasts as an example. Every application I build for Cocoacasts has a bundle identifier that starts with com.cocoacasts, that is, the reverse of the Cocoacasts website. For my company, Code Foundry, I use bundle identifiers that start with be.codefoundry.

You don’t need to own the domain you use for your application’s bundle identifier. The domain is only used to ensure the bundle identifier is unique. For example, I could also use blog.cocoacasts for the applications I build for Cocoacasts even though I don’t own cocoacasts.blog.

To create a unique bundle identifier, you append the name of the application to the reversed domain, for example, com.cocoacasts.scribbles. Remember that you choose the bundle identifier. Reverse domain name notation is what Apple recommends and it’s a pattern most developers use.

The only requirement is that the bundle identifier is unique. Xcode warns you if you choose a bundle identifier that’s already in use by another application. I strongly recommended that you use a bundle identifier that makes sense and that’s why most developers stick to reverse domain name notation.

If you’re building a suite of applications, then you can use the same approach. Take a look at the following example. The first bundle ID is used for the iOS client of Scribbles whereas the second bundle ID is used for the macOS client of Scribbles.

com.cocoacasts.scribbles.ios com.cocoacasts.scribbles.macos It is important to note that at the time of writing, once you have registered a bundle identifier to a Personal Team in Xcode the same bundle identifier cannot be registered to another Apple Developer Program team in the future. This means that while you are testing your game using a free Apple ID and a Personal Team, you should choose a bundle identifier that is for testing only - you won’t be able to use the same bundle identifier to release the game. An easy way to do this is to add “Test” to the end of whatever bundle identifier you were going to use - for example, com.yourCompanyName.yourGameNameTest. For more information on bundle identifiers on iOS, see this Apple documentation. (Source Article)

Changing the Bundle ID in Unity Within Unity:

Open the Player Settings in the Inspector panel (Edit > Project Settings > Player). Expand the section at the bottom called Other Settings, and enter your chosen bundle identifier where it says Bundle identifier

Requesting a License Key Coming Soon

Unity to Android

how to build with Android - COMING SOON

Best Practices

game design guidelines - COMING SOON

Tutorial

Simple video tutorials to get you started

Kodama 101: 1mn setup

Get started in less than 2 minutes

Software setup video

Hardware setup video

Kodama 102: TiltBrush for iOS

example of a simple VR port for Kodama - COMING SOON

Kodama 103: AR touch

the fist interactive AR manipulation - COMING SOON

Troubleshooting
script errors

list of errors and corresponding fixes

  • Configure Player Settings:
    • In the top bar click Edit> Project Settings> Player.
    • In the inspector, under Standalone Settings> Configuration> Api Compatibility Level, select NET 2.0 isntead of NET 2.0 Subset.
Roadmap

This is an overview of the upcoming updates.

V0.1.1-UX patch(mid february)

  • added scene examples
  • video tutorials
  • setup optimisation

V0.1.2-Tracking patch (mid March)

  • calibration, orientation and accuracy optimisation

V0.3-Wireless patch(April)

  • moving to a BLE only interface for both desktop and devices
  • Battery levels BLE services

V0.4-Tracker upgrade(May)

  • RFID support
  • I2C support
  • Corresponidng BLE services and UX implementation

V1.0-Multi tracker implementation(October)

  • Hardware upgrade