PicoP Gen4 Linux SDK Getting Started Guide DA0140038 Pico P

User Manual:

Open the PDF directly: View PDF PDF.
Page Count: 14

DownloadPicoP Gen4 Linux SDK Getting Started Guide DA0140038 Pico P
Open PDF In BrowserView PDF
Getting Started with PicoP® Gen4 SDK for Linux

1. Abstract
This guide explains how to get started with the MicroVision Linux Software Development Kit (SDK)
for its 4th Generation PicoP Scanning Engines (PSE). The PicoP Linux SDK allows developers to
quickly and easily integrate PicoP Scanning Engine control into a Linux application. The Linux
Application can communicate with PSE over USB. The SDK package includes the C Application
Programming Interface (API), SDK libraries, documentation, and sample projects that demonstrate use
of some basic (PSE) functions. The sample applications have been developed and built using GNU
command line tools.

2. Table of Contents
1.

ABSTRACT .........................................................................................................................................................1

2.

TABLE OF CONTENTS ...................................................................................................................................1

3.

INSTALLING PICOP SDK ...............................................................................................................................2

4.

ACCESSING SDK DOCUMENTATION ........................................................................................................3

5.

USING THE PICOP APPLICATION PROGRAMMING INTERFACE (API) ..........................................4
5.1.
SDK VERSION CONTROL ..............................................................................................................................4
5.2.
STEP 1: LINK SDK LIBRARY TO THE APPLICATION .......................................................................................4
5.3.
STEP 2: INITIALIZE THE SDK LIBRARY .........................................................................................................4
5.4.
STEP 3: CONNECT TO PICOP ..........................................................................................................................4
5.5.
STEP 4: CONFIGURE AND CONTROL PICOP ....................................................................................................5
5.5.1.
Connection Management .....................................................................................................................5
5.5.2.
Display Control Functions ..................................................................................................................6
5.5.3.
System Management Functions ...........................................................................................................8
5.5.4.
Input Control Functions ......................................................................................................................8
5.5.5.
Rendering Functions ...........................................................................................................................8
5.6.
STEP 5: EXIT APPLICATION ...........................................................................................................................9

6.

SDK HOST PLATFORMS .............................................................................................................................. 10
6.1.

7.

REQUIRED PLATFORM PACKAGES ............................................................................................................... 10

DEMO APPLICATIONS ................................................................................................................................. 11
7.1.
7.2.
7.3.

PICOP_CONSOLE SAMPLE PROJECT ............................................................................................................ 11
PICOP_DISPLAY SAMPLE PROJECT ............................................................................................................. 13
PICOP_UPDATE_FW SAMPLE PROJECT ...................................................................................................... 14

PicoP Gen4 Linux SDK Ver. 1.3.0 Getting Started Guide
MVIS #: DA0140038 May 2019 Revision A.0
© 2019 MicroVision, Inc. All rights reserved.

MicroVision.com
Page 1 of 14

PicoP® is a registered trademark of MicroVision, Inc.
Specifications subject to change without notice.
MicroVision, Inc. Specifications subject to change
without
customerservice@microvision.com

notice.

Getting Started with PicoP® Gen4 SDK for Linux

3. Installing PicoP SDK
The latest PicoP Linux SDK can be cloned or downloaded from:
https://github.com/MicroVision-Inc/Interactive_Projection
Alternatively, the SDK may be delivered as a compressed file named
PicoP_Linux_SDK_Ver_X_Y_Z.zip. The X_Y_Z postfix of the file name represents the version
number of the SDK (X equals the major version, Y the minor version, and Z the patch number of the
SDK). To install the SDK, simply decompress the file into a directory of your choice. The cloned or
uncompressed destination folder will contain the following subfolders:
SDK Root folder

PicoP_Linux_SDK

SDK Documentation

Docs

Detailed Programmer’s Reference Guide

Reference_Guide/html
index.html
*.html
DA0140028_PicoP_Gen4_Progra
mmers_Guide.pdf
EULA.pdf

Interface
picop_api.h
picop_def.h
picop_rc.h

Lib
libPicoP_Api.so.1.3.0
libPicoP_Api.a

Samples

Programmer’s Reference Guide entry point
Programmer’s Reference Guide documentation
High-Level Programmer’s Guide
SDK End User License Agreement
PicoP SDK API Interface
PicoP SDK header file with function prototypes
PicoP SDK definitions files
PicoP SDK return codes
PicoP SDK Linux libraries (64-bit)
PicoP SDK shared library
PicoP SDK static library
SDK Sample Applications

Bin

Contains the 64-bit executables for the sample
applications.

PicoP_Console

Simplest Console application demonstrating
how to communicate with PSE

PicoP_Display
PicoP_Update_FW
DA0140038_PicoP_Gen4_Linux_SDK_Getting_
Started_Guide.pdf

Simple GUI Application demonstrating the basic
usage of sample C APIs for Display functions
Simplest Console application demonstrating
how to perform a FW update on the PSE
This Getting Started guide for PicoP Linux SDK

PicoP Gen4 Linux SDK Ver. 1.3.0 Getting Started Guide
MVIS #: DA0140038 May 2019 Revision A.0
© 2019 MicroVision, Inc. All rights reserved.

MicroVision.com
Page 2 of 14

PicoP® is a registered trademark of MicroVision, Inc.
Specifications subject to change without notice.
MicroVision, Inc. Specifications subject to change
without
customerservice@microvision.com

notice.

Getting Started with PicoP® Gen4 SDK for Linux

4. Accessing SDK Documentation
For high level description of functions/commands supported by the PSE Application Programming
Interface (API), please refer to the DA0140028_PicoP_Gen4_Programmers_Guide.pdf .
For detailed description of the C-language API, please refer to the Programmer’s Reference Guide at
Docs\Reference_Guide\index.html. The Reference Guide is a set of hyperlinked HTML files
containing detailed description of all Function interfaces and definitions provided by the API.

PicoP Gen4 Linux SDK Ver. 1.3.0 Getting Started Guide
MVIS #: DA0140038 May 2019 Revision A.0
© 2019 MicroVision, Inc. All rights reserved.

MicroVision.com
Page 3 of 14

PicoP® is a registered trademark of MicroVision, Inc.
Specifications subject to change without notice.
MicroVision, Inc. Specifications subject to change
without
customerservice@microvision.com

notice.

Getting Started with PicoP® Gen4 SDK for Linux

5. Using the PicoP Application Programming Interface (API)
The PicoP SDK for Linux allows you to easily interface your application software with the PicoP
Scanning Engine. This section explains the steps of the integration process.

5.1. SDK Version Control
The SDK API version can be queried with the PicoP_GetLibraryInfo() function. The Library
info returns the major (X), minor (Y), and patch number (Z) for the SDK Version X.Y.Z. The library
information also includes capability flags which can differentiate library implementation
enhancements that are compatible with the same API and header files.
// Library information
typedef struct {
UINT8 majorVersion;
UINT8 minorVersion;
UINT8 patchVersion;
UINT32 capabilityFlags;
} PicoP_LibraryInfoS;

//
//
//
//

Contains the major version of the library
Contains the minor version of the library
Contains the patch version of the library
Flags that describe the capability of the library

5.2. Step 1: Link SDK Library to the application
To include the PicoP Linux SDK to an application, include the picop_api.h header file into the
application source code
and link the libPicoP_Api.a static library or
libPicoP_Api.so.1.3.0 shared library to the application executable.

5.3. Step 2: Initialize the SDK Library
The first step in connecting to a PicoP is to initialize the PicoP library by calling
PicoP_OpenLibrary(). The PicoP_OpenLibrary() function returns a handle to the library that
can be used to open a connections to the PicoP device.

5.4. Step 3: Connect to PicoP
After successful initialization of the library, the next step is to create a connection to the PicoP device.
The connection can be established using either Universal Serial Bus (USB) or Universal Asynchronous
Receiver-Transmitter (UART) physical interfaces. To create a connection to the PicoP Scanning
Engine, call either the PicoP_OpenConnection(), PicoP_OpenConnectionUSB(), or
PicoP_OpenConnectionUart() functions. Upon successful connection, the library will return a
connection handle to be used with subsequent library calls. The connection handle identifies the
connected system.

PicoP Gen4 Linux SDK Ver. 1.3.0 Getting Started Guide
MVIS #: DA0140038 May 2019 Revision A.0
© 2019 MicroVision, Inc. All rights reserved.

MicroVision.com
Page 4 of 14

PicoP® is a registered trademark of MicroVision, Inc.
Specifications subject to change without notice.
MicroVision, Inc. Specifications subject to change
without
customerservice@microvision.com

notice.

Getting Started with PicoP® Gen4 SDK for Linux

5.5. Step 4: Configure and Control PicoP
The PicoP API is split into the following functional categories:
•

Connection & Library Management: Connect to PicoP over USB or Serial (UART)
interface.

•

Display Control: Configure and control the PicoP Display.

•

System Management: Manage the PicoP System, Firmware upgrades, Event Log, etc.

•

Input Control: Configure the PicoP Input Video.

•

3D Sensing: Configure and control PicoP 3D Sensing interface and retrieve 3D point cloud
data.

•

Rendering: Render images and test patterns into Framebuffer and On-Screen Display (OSD).

5.5.1. Connection Management
The Connection Management Functions are used to connect to the PicoP Display Engine using USB
or UART.

Function
PicoP_OpenLibrary( )

PicoP_GetLibraryInfo( )
PicoP_CloseLibrary( )
PicoP_OpenConnection( )
PicoP_CloseConnection( )

Description
Opens the library and allocates resources
necessary for operation. It returns a handle to
the library that must be used in subsequent
calls
Retrieves the version and capability
information of the SDK Library
Closes the library and releases all resources. It
also closes all the open connections.
Opens a connection to the PicoP Display
Engine using either USB or UART.
Closes a previously opened connection to the
PicoP Display Engine.

PicoP Gen4 Linux SDK Ver. 1.3.0 Getting Started Guide
MVIS #: DA0140038 May 2019 Revision A.0
© 2019 MicroVision, Inc. All rights reserved.

MicroVision.com
Page 5 of 14

PicoP® is a registered trademark of MicroVision, Inc.
Specifications subject to change without notice.
MicroVision, Inc. Specifications subject to change
without
customerservice@microvision.com

notice.

Getting Started with PicoP® Gen4 SDK for Linux

5.5.2. Display Control Functions
The Display Control Functions can be used to configure the output display.

Function
PicoP_SetBrightness( )
PicoP_GetBrightness( )
PicoP_SetColorMode( )
PicoP_GetColorMode( )
PicoP_SetGamma( )
PicoP_GetGamma( )
PicoP_SetVideoGammaBoostMode( )
PicoP_GetVideoGammaBoostMode( )
PicoP_SetMicroWeaveMode( )
PicoP_GetMicroWeaveMode( )
PicoP_SetFlipState()

PicoP_GetFlipState()

Description
Sets brightness for the output display.
Returns brightness setting of the output
display.
Sets color mode for the output display.
Returns color mode setting of the output
display.
Sets gamma value for the output display.
Returns gamma value setting of the output
display.
Set the color specific video gamma boost
mode.
Return the color specific video gamma
boost mode.
Select the MicroWeave mode.
Return the MicroWeave mode.
Sets the flip state of the image to
horizontal, vertical, both horizontal and
vertical or none.

PicoP_GetOutputVideoState( )

Returns the current flip state of the output
display.
Set the video output state to enabled or
disabled.
Returns the current video output state.

PicoP_GetOutputVideoProperties( )

Return output video properties.

PicoP_SetBiPhase( )

Sets the scan line phase delay to align the
forward and reverse scan video.
Returns the scan line phase delay setting.

PicoP_SetOutputVideoState( )

PicoP_GetBiPhase( )
PicoP_SetColorAlignment()
PicoP_GetColorAlignment()

Performs vertical or horizontal color
alignment for the selected color
Gets the color alignment offset of the
chosen color

PicoP Gen4 Linux SDK Ver. 1.3.0 Getting Started Guide
MVIS #: DA0140038 May 2019 Revision A.0
© 2019 MicroVision, Inc. All rights reserved.

MicroVision.com
Page 6 of 14

PicoP® is a registered trademark of MicroVision, Inc.
Specifications subject to change without notice.
MicroVision, Inc. Specifications subject to change
without
customerservice@microvision.com

notice.

Getting Started with PicoP® Gen4 SDK for Linux

PicoP_SetColorConverter()
PicoP_GetColorConverter()
PicoP_SetFrameRateMode( )

PicoP_GetFrameRateMode( )

Sets the color converter values
Gets the color converter values
Sets the output frame rate mode (frame
rate vs. vertical display and sensing
resolutions) and display scaling.
Returns the output frame rate mode
(frame rate vs. vertical display and sensing
resolutions) and display scaling

PicoP Gen4 Linux SDK Ver. 1.3.0 Getting Started Guide
MVIS #: DA0140038 May 2019 Revision A.0
© 2019 MicroVision, Inc. All rights reserved.

MicroVision.com
Page 7 of 14

PicoP® is a registered trademark of MicroVision, Inc.
Specifications subject to change without notice.
MicroVision, Inc. Specifications subject to change
without
customerservice@microvision.com

notice.

Getting Started with PicoP® Gen4 SDK for Linux

5.5.3. System Management Functions
The System Management Functions are used to control the PicoP System and to access the system
information.

Function

Description

PicoP_GetSystemInfo( )
PicoP_GetSystemStatus( )
PicoP_GetEventLog( )
PicoP_RestoreFactoryConfig( )

Retrieves system information.
Retrieves the system status.
Retrieves the system event log.
Restores System Settings to Factory
Configuration.
Commits all user settings to flash.
Upgrades the embedded Software.

PicoP_CommitAll( )
PicoP_UpgradeSoftware( )

5.5.4. Input Control Functions
The Input Control functions are used to configure the PicoP Input Video.

Function

Description

PicoP_GetInputVideoProperties( )

Returns detected input video Frame Rate
and Lines per Frame.
Enables or Disables the input video. When
input video is disabled, the framebuffer will
not be updated and the output video will
contain the last captured frame.
Returns the current state of the input
video.

PicoP_SetInputVideoState( )

PicoP_GetInputVideoState( )

5.5.5. 3D Sensing Functions
The 3D Sensing functions are used to configure the 3D sensor.

Function
PicoP_SetSensingState( )

PicoP_GetSensingState( )

Description
Turns the 3D Sensing function on or off.
When the 3D Sensing function is off, the IR laser
is not pulsing and no 3D sensing data is sent
over the USB.
Returns the current Sensing state.

PicoP Gen4 Linux SDK Ver. 1.3.0 Getting Started Guide
MVIS #: DA0140038 May 2019 Revision A.0
© 2019 MicroVision, Inc. All rights reserved.

MicroVision.com
Page 8 of 14

PicoP® is a registered trademark of MicroVision, Inc.
Specifications subject to change without notice.
MicroVision, Inc. Specifications subject to change
without
customerservice@microvision.com

notice.

Getting Started with PicoP® Gen4 SDK for Linux

5.5.6. Rendering Functions
The Rendering function allows the host system to render information into the PicoP On-Screen Display
(OSD) or FrameBuffer.

Function
PicoP_DrawTestPattern( )

Description
Displays one of the built-in test patterns.

5.6. Step 5: Exit Application
gracefully exit the host application, call the PicoP_CloseConnection() and
PicoP_CloseLibrary() functions to shut down the connection to PicoP and to release all resources
To

used by the library.

PicoP Gen4 Linux SDK Ver. 1.3.0 Getting Started Guide
MVIS #: DA0140038 May 2019 Revision A.0
© 2019 MicroVision, Inc. All rights reserved.

MicroVision.com
Page 9 of 14

PicoP® is a registered trademark of MicroVision, Inc.
Specifications subject to change without notice.
MicroVision, Inc. Specifications subject to change
without
customerservice@microvision.com

notice.

Getting Started with PicoP® Gen4 SDK for Linux

6. SDK Host Platforms
The PicoP Gen4 SDK and applications has been verified on the following hardware platforms
("$ cat /etc/os-release", "$ uname -r"):
•

PC : Ubuntu Linux 16.04
o

DISTRIB_ID=Ubuntu

o

DISTRIB_RELEASE=16.04

o

DISTRIB_CODENAME=xenial

o

DISTRIB_DESCRIPTION="Ubuntu 16.04.5 LTS"

o

NAME="Ubuntu"

o

VERSION="16.04.5 LTS (Xenial Xerus)"

o

ID=ubuntu

o

ID_LIKE=debian

o

PRETTY_NAME="Ubuntu 16.04.5 LTS"

o

VERSION_ID="16.04"

o

HOME_URL="http://www.ubuntu.com/"

o

SUPPORT_URL="http://help.ubuntu.com/"

o

BUG_REPORT_URL="http://bugs.launchpad.net/ubuntu/"

o

VERSION_CODENAME=xenial

o

UBUNTU_CODENAME=xenial

o

kernel version: 4.15.0-36-generic

6.1. Required Platform Packages
Each Linux platform requires the installation of the following packages:
•

libudev-dev, (GNU Lesser General Public License (LGPL), version 2.1)

•

libbluetooth-dev, (GNU General Public License (GPL))

•

libusb-1.0-0-dev, (GNU Lesser General Public License (LGPL), version 2.1)

•

v4l-utils, (GNU Lesser General Public License)

•

build-essential

•

git

PicoP Gen4 Linux SDK Ver. 1.3.0 Getting Started Guide
MVIS #: DA0140038 May 2019 Revision A.0
© 2019 MicroVision, Inc. All rights reserved.

MicroVision.com
Page 10 of 14

PicoP® is a registered trademark of MicroVision, Inc.
Specifications subject to change without notice.
MicroVision, Inc. Specifications subject to change
without
customerservice@microvision.com

notice.

Getting Started with PicoP® Gen4 SDK for Linux

7. Demo Applications
PicoP_Linux_SDK/samples/ contains the following demo applications utilizing the PicoP SDK:
•

PicoP_Console

•

PicoP_Display

•

PicoP_Update_FW

To build any of these applications, open a shell and navigate to the application directory and execute
"make". This will build the application using the static library.
There is no Advanced Packaging Tool (APT) package created for shared library installation. To
evaluate the shared library, softlink creation is required to traverse the versions of the soname. For
example, if released version is libPicoP_ALC_Api.so.1.0.0 then create following softlinks in library
path directory:
$ sudo ln -sf libPicoP_Api.so.1.3.0 libPicoP_Api.so.1.3
$ sudo ln -sf libPicoP_Api.so.1.3 libPicoP_Api.so.1
$ sudo ln -sf libPicoP_Api.so.1 libPicoP_Api.so

The library utilizes USB device node access for communication and video streaming. This requires
running all demo applications under sudo access control or create udev rules to allow user space
programs access to usb device nodes. There are several ways to create the udev rules, but one simple
rule set which allows device node access to any user on the host is the following 2 lines:
•

SUBSYSTEMS=="usb", ENV{DEVTYPE}=="usb_device", ATTRS{idVendor}=="148a",
ATTRS{idProduct}=="0004", MODE="0666"

•

SUBSYSTEMS=="usb", ENV{DEVTYPE}=="usb_device", ATTRS{idVendor}=="04b4",
ATTRS{idProduct}=="00f9", MODE="0666"

Add these 2 lines to a udev file (filename extension .rules) located in /etc/udev/rules.d. Note if your
chosen filename exists in /lib/udev/rules.d directory those rules will be overridden, so it is advisable
to choose a unique filename for these udev rules.

7.1. PicoP_Console Sample Project
The PicoP_Console sample project is a simple Linux console application. It demonstrates the use
of SDK interfaces to communicate with the PicoP device and to control basic Projector functions. The
application can control the following PicoP operations:
•

Retrieve library info and PSE system status

•

Retrieve/Change display brightness setting

PicoP Gen4 Linux SDK Ver. 1.3.0 Getting Started Guide
MVIS #: DA0140038 May 2019 Revision A.0
© 2019 MicroVision, Inc. All rights reserved.

MicroVision.com
Page 11 of 14

PicoP® is a registered trademark of MicroVision, Inc.
Specifications subject to change without notice.
MicroVision, Inc. Specifications subject to change
without
customerservice@microvision.com

notice.

Getting Started with PicoP® Gen4 SDK for Linux

•

Retrieve/Change display color mode setting

•

Flip display

•

Retrieve System Status

•

Retrieve/Change Horizontal Scan Angle

•

Retrieve/Change Vertical Scan Angle

•

Present Test Patterns

To build the application using a static library invoke make with no arguments:
$ make
To build using a shared library, configure softlinks as detailed above, and invoke make with the
STATIC argument:
$ make STATIC=false
To run the application issue “sudo ./PicoP_Display_Console_Demo” at the shell command line to
run the application. As shown below, Library and System information will be displayed in the shell
followed by help instructions. Select one of the supported modes, and then press the up key (key
value 65) or down key (key value 66) to cycle though configurations for that mode.

PicoP Gen4 Linux SDK Ver. 1.3.0 Getting Started Guide
MVIS #: DA0140038 May 2019 Revision A.0
© 2019 MicroVision, Inc. All rights reserved.

MicroVision.com
Page 12 of 14

PicoP® is a registered trademark of MicroVision, Inc.
Specifications subject to change without notice.
MicroVision, Inc. Specifications subject to change
without
customerservice@microvision.com

notice.

Getting Started with PicoP® Gen4 SDK for Linux

7.2. PicoP_Display Sample Project
The PicoP_Display_GUI_Demo application presents a GUI to exercise several more of the Display
control API functions. The application can control the following PicoP operations:
•

Retrieve library info and PSE system status

•

Retrieve/Change display color mode setting

•

Retrieve/Change Input Video State

•

Retrieve/Change Output Video State

•

Retrieve Output Video Properties

•

Retrieve/Change Frame Rate Mode

•

Retrieve/Change Brightness value

•

Retrieve/Change Brightness Compensation Mode

•

Retrieve/Change Color Mode

•

Retrieve/Change Color Conversion

•

Retrieve/Change Gamma

•

Retrieve/Change Gamma Boost Mode

•

Retrieve/Change Microweave Mode

•

Retrieve/Change BiPhase value

•

Change Flip State

•

Perform Factory Configuration Reset

•

Present Test Patterns

•

Perform Commit All and Factory Reset

Installation of the following platform package is required for this application:
•

libgtkmm-3.0-0-dev, (version >= 3.18.0-1) (GNU Lesser General Public License)

To build the application using a static library invoke make with no arguments:
$ make

PicoP Gen4 Linux SDK Ver. 1.3.0 Getting Started Guide
MVIS #: DA0140038 May 2019 Revision A.0
© 2019 MicroVision, Inc. All rights reserved.

MicroVision.com
Page 13 of 14

PicoP® is a registered trademark of MicroVision, Inc.
Specifications subject to change without notice.
MicroVision, Inc. Specifications subject to change
without
customerservice@microvision.com

notice.

Getting Started with PicoP® Gen4 SDK for Linux

To run the application issue “sudo ./PicoP_Display_GUI_Demo” at the shell command line to run the
application. As shown below, a GUI application launches with supported commands enumerated on
the left side of the pane. Selecting a command mode radio button will show its control widgets on the
right side of the pane.

7.3. PicoP_Update_FW Sample Project
The PicoP_Update_FW is a command line application for performing a FW update. Place the FW
binary named “pde_client.chunk.bin” in the same directory as the PicoP_Update_FW_Demo
executable. Connect USB to the Dev Kit target and run the executable. The console will display the
FW update progress.

PicoP Gen4 Linux SDK Ver. 1.3.0 Getting Started Guide
MVIS #: DA0140038 May 2019 Revision A.0
© 2019 MicroVision, Inc. All rights reserved.

MicroVision.com
Page 14 of 14

PicoP® is a registered trademark of MicroVision, Inc.
Specifications subject to change without notice.
MicroVision, Inc. Specifications subject to change
without
customerservice@microvision.com

notice.



Source Exif Data:
File Type                       : PDF
File Type Extension             : pdf
MIME Type                       : application/pdf
PDF Version                     : 1.7
Linearized                      : No
Page Count                      : 14
Language                        : en-US
Tagged PDF                      : Yes
XMP Toolkit                     : 3.1-701
Producer                        : Microsoft® Word for Office 365
Title                           : PicoP Gen4 Linux SDK Getting Started Guide
Creator                         : Jari Honkanen
Creator Tool                    : Microsoft® Word for Office 365
Create Date                     : 2019:05:23 15:04:07-07:00
Modify Date                     : 2019:05:23 15:04:07-07:00
Document ID                     : uuid:99ED94C3-B13B-4128-A641-87179BED8822
Instance ID                     : uuid:99ED94C3-B13B-4128-A641-87179BED8822
Author                          : Jari Honkanen
EXIF Metadata provided by EXIF.tools

Navigation menu