qubevu developer guide v1.0qubevu.com/products/documentation/qubevu developer guide.pdf · qubevu...

SPECIFICATION v1.0.17

QubeVu®

DEVELOPER GUIDE

QubeVuDeveloperGuide 2

1 Table of Contents

1 TABLEOFCONTENTS....................................................................................................................2

2 INTRODUCTION............................................................................................................................5

2.1 PURPOSE.........................................................................................................................................5

2.2 SCOPE.............................................................................................................................................5

3 BACKGROUND..............................................................................................................................6

4 OVERVIEW...................................................................................................................................7

5 WEBSERVICEINTERFACESPECIFICATIONS....................................................................................8

5.1 RETRIEVINGTHEDIMENSIONS.............................................................................................................8

5.1.1 Scanningwithoutautotrigger.............................................................................................19

5.2 RETRIEVINGTHEIMAGE....................................................................................................................19

5.3 SETTINGZEROHEIGHTOFSCANPLATFORM..........................................................................................20

5.3.1 Zeroheighterrormessages................................................................................................20

5.4 RETRIEVINGBARCODES....................................................................................................................21

5.4.1 Enablingbarcoderecognitionthroughcapturedefinition..................................................21

5.5 SETTINGTHEWEIGHTFROMANEXTERNALSCALE..................................................................................21

5.6 RETURNEDVALUES..........................................................................................................................23

5.6.1 Status..................................................................................................................................23

5.6.2 Extendedstatus..................................................................................................................24

5.7 CAPTUREDEFINITIONS.....................................................................................................................25

5.7.1 Creatingcapturedefinitions...............................................................................................25

5.7.2 Listingcapturedefinitions..................................................................................................28

5.7.3 Retrievingcapturedefinitiondetails...................................................................................28

5.7.4 Deletingcapturedefinition.................................................................................................28

5.8 SYSTEMDATEANDTIME...................................................................................................................29

5.8.1 Gettingsystemtime............................................................................................................29

5.8.2 Settingsystemtimeandtimezone.....................................................................................29

5.9 DEVICEINFO..................................................................................................................................29

5.10 RESTARTING...................................................................................................................................31

5.11 MISCELLANEOUS.............................................................................................................................31

5.11.1 DeprecatedFunction...........................................................................................................31

6 EXTERNALINTERFACES:SERIAL,TCPANDHTTP..........................................................................32

6.1 PROTOCOLMODES.........................................................................................................................32

6.2 QUBEVUPROTOCOL........................................................................................................................32


6.2.1 SampleRequestsandResponses........................................................................................33

6.3 CUBISCANEMULATIONPROTOCOL.....................................................................................................33

6.3.1 RequestandResponse........................................................................................................33

6.3.2 SupportedCommands........................................................................................................33

6.3.3 SampleRequestsandResponses........................................................................................35

6.3.4 Troubleshooting..................................................................................................................35

6.4 HTTPPROTOCOL............................................................................................................................36

6.4.1 RequestandResponse........................................................................................................36

6.4.2 ResponseFormatConfiguration.........................................................................................37

7 APPENDIXA–SHORTFORMATURLS..........................................................................................38

8 APPENDIXB–SAMPLE.NETCLIENTCODE..................................................................................40

9 APPENDIXC–C#.NETCODESAMPLES.......................................................................................42

9.1 DIM101........................................................................................................................................42

9.2 DIM102........................................................................................................................................42

9.3 DIM103........................................................................................................................................42

9.4 DIM104........................................................................................................................................42

9.5 EXTERNALTRIGGER..........................................................................................................................42

9.6 BARCODES.....................................................................................................................................43

9.7 BARCODES2D.................................................................................................................................43

9.8 BARCODES2D_DTK.........................................................................................................................43

9.9 BARCODES2D_DTK_WITH_KEY.........................................................................................................43

9.10 IMAGECONVERSION........................................................................................................................43

10 APPENDIXD–SAMPLEHTTPDIALOG.....................................................................................44

10.1 QUBEVUSTATUSQUERY..................................................................................................................44

10.1.1 Request(InternetExplorer11,usingAjaxpollinginwebpage).........................................44

10.1.2 “ReadytoScan”ResponsefromQubeVu(white-spaceaddedtobodyforreadability).....44

10.1.3 “ItemScanned”SampleResponsefromQubeVu................................................................46

11 APPENDIXE–UNIVERSALWINDOWSPLATFORMSAMPLE(C#)..............................................51

11.1 DIM101........................................................................................................................................51

12 APPENDIXF–QUBEVUBARCODESCLIENTAPI........................................................................52

12.1 FUNCTIONREFERENCE.....................................................................................................................52

CreateReader......................................................................................................................................52

CreateReaderMT................................................................................................................................52

DestroyReader....................................................................................................................................52

RecognizeBarcode..............................................................................................................................52


13 APPENDIXG–POSTEA.QUBEVU2DBCRECOGNITIONCLIENTAPI.............................................53

13.1 BARCODERECOGNIZER2DCLASSFUNCTIONREFERENCE........................................................................53

BarcodeRecognizer2D(bcTypes2D).....................................................................................................53

ReadImage(Image).............................................................................................................................53

13.2 BARCODERECOGNIZER2D_DTKCLASSREFERENCE...............................................................................53

BarcodeRecognizer2D_DTK(dtkDeveloperLicenseKey).......................................................................53

BarcodeRecognizer2D_DTK(dtkDeveloperLicenseKey,dtkRuntimeLicenseKey).................................54

BarcodeRecognizer2D_DTK(dtkDeveloperLicenseKey,dtkRuntimeLicenseKey,bcTypes2D)..............54

BarcodeRecognizer2D_DTK(dtkDeveloperLicenseKey,dtkRuntimeLicenseKey,barcodeSettingsXml)54

ReadImage(Image).............................................................................................................................54

IsDtkLicensed......................................................................................................................................54

GetSettingsXmlString().......................................................................................................................54

DtkBarcodeToBarcodeInfo(DTKBarReader.Barcode)..........................................................................54

13.3 DTKXMLSETTINGSSTRING.............................................................................................................54

DTKXMLsettings................................................................................................................................54

DTKXMLsettingssample...................................................................................................................56

14 APPENDIXH–SUPPORTEDBARCODES...................................................................................57

15 APPENDIXI–ITEMRECTILLUSTRATION..................................................................................58

16 APPENDIXJ–ITEMWIREFRAMESAMPLE................................................................................59


2 Introduction

2.1 Purpose

ThisdocumentspecifieshowaQubeVucanbeconnectedtoauser’sclientsystemandhowthatsystemcanthenobtaininformationfromtheQubeVuaboutanitem’sdimensionsandtheitem’simage.

2.2 Scope

Thisdocumentdescribesthewebservice,serialport,TCPandHTTPinterfacestoQubeVu.ThewebserviceinterfaceisnotsupportedonQubeVudevicespriortoQubeVuMark4.SerialandTCPinterfacesaresupportedstartingwithfirmwarev.4.9.2,HTTPbeginningwithv.4.9.4.Certainmodels(e.g.LTL)don’timplementexternalinterfacesotherthanthewebserviceAPI.

Majorityoftheinterfaces’purposeistosupportdimensioningandimageretrieval,whicharediscussedinthefollowingsections.Somesupportingfunctions,e.g.retrievingdeviceinfo,restartingandexternalscalesupportarebrieflytouchedon.

Takingadvantageofexternalinterfaces,otherthanthewebservices,requiresadditionalsoftwareconfigurationasdescribedinQubeVuManagerGuide.USBserialconnectivitymayrequireadditionalhardwaresetup(pleasecontactQubeVuSupportfordetails).


3 Background

QubeVuprovidesasolutiontotheproblemofquicklyandreliablymeasuringthethreedimensionsofamailitemaspartofthemailacceptanceorhandlingprocess.ItalsoprovideshighresolutionimagesofthetopsurfaceoftheitemthatcansubsequentlybeusedforvariouspurposesincludingbarcoderecognitionandOCRorICR1.

ItoftenoperatesinconjunctionwithaweighscalethatiscollectingtheweightoftheitemandtheQubeVuispositionedcentrallyovertheweighscalesothatthedimensionscanbecapturedatthesametimeastheweight.

TheQubeVuisabletoautomaticallyrecognisethatanitemhasbeenplacedunderneathitandbegintheprocessofmeasurementimmediately.Hencethisinformationcanalreadybeavailablebythetimetheuser’sclientsystemrequiresit.

Oninstallation,theQubeVuiscalibratedtosuitthelocationandthespecificcharacteristicsoftheindividualdevice.

ConfigurationdatafortheQubeVuisheldinfilesonitsembeddeddatastorage.

1OCRorICRcapabilityrequiresaseparateLeadtools15license


4 Overview

TheQubeVuconnectstotheuser’sworkstationwithasingleEthernetconnector.Beginningwithfirmwarev.4.9.2,othertypesofconnectivityisalsosupported.

TheQubeVurequiresonepowersocket.

Nospecialisedsoftwarecomponentsordriversareinstalledontheworkstationinthedefaultusecases,i.e.whentakingadvantageofthewebinterface.Allnecessarysoftwarecomponentsareembeddedinthedevice.Clientapplicationscaninterfacewiththedeviceviaawebserviceinterface.Thewebservicestartsautomaticallywhenthedeviceisstarted.

TheinterfacecomponentsdefinedinthisdocumentprovidethemechanismbywhichtheclientapplicationcancommunicatewiththeQubeVu.

TheclientprocessingisstartedbytheuserinresponsetothepackagebeingpresentedbythecustomerandaftertheitemhasbeenplacedundertheQubeVu.

ThereisaseparationbetweentheclientsupportinterfaceandtheinternaloperationoftheQubeVusoftwarewithintheservice.TheclientinterfacesreadwhatinformationiscurrentlyavailablefromtheQubeVuandreportthestatusoftheinformation.Thesecallsdonotblockwaitingfortherequiredinformation.Thisistopreventtheclientinterfacehanginginindeterminatecircumstances.

TheclientapplicationwillthereforeprobablywanttoimplementsomeformofdelayedlooptoreadtheQubeVuinformationbymonitoringthestatusonthewebinterfaceitiscalling.Itmayalsoimplementitsowntime-outtopreventtheUIhangingindefinitelyifthereisaproblem.

Thewebservicecanbefoundatthefollowingurl:http://{device}/WebServices/QubeVuService.

ThewebservicesupportstheHTTPPostbinding.Clientmustusethisbindingtointeractwiththeservice.AC#proxyclass(QubeVuServiceHttpPostClient.cs)fortheserviceisavailableaspartoftheAPI.OtherproxyclassesmaybegeneratedifnecessaryfromtheWSDLfile.TheWSDLfileofthisservicecanbefoundathttp://{device}/WebServices/QubeVuService.AsecondC#proxyclass(QubeVuServiceAsyncClient.cs)isavailableforusewithWindowsStoreappsandUniversalWindowsPlatformdevelopmentprojects(including,butnotlimitedtoWindowsIoT).

Webservicesinterfaceisenabledbydefault,bututilizingotherinterfacesrequireadditionalsoftwareconfigurationasdescribedinQubeVuManagerGuide.USBserialconnectivitymayrequireadditionalhardwaresetup(pleasecontactQubeVuSupportfordetails).


5 Web Service Interface Specifications

ThewebinterfacesareimplementedwithintheQubeVuServicewebservice.

InformationisonlyavailablewhileanitemisontheQubeVuandtheQubeVuhashadtimetoprocessit.Oncetheitemisremovedtheinformationisnolongeravailable.

Statusinformation,includinginformationaboutthemailitem,isretrievedthroughtheStatusmethod.TheStatusmethodonlyreturnsaURLforanyimagescaptured.ImagecontentisretrievedusingstandardHTTPrequests.

AnXMLErrorelementwiththeerrormessagewillbereturnedintheeventofasoftwareerror.

SampleHTTPdialogisincludedinAppendixD–SampleHTTPDialog.

5.1 Retrieving the Dimensions

ThisusestheStatusinterface:QubeVuService/Status.

ItreturnsasinglestringvaluecontaininganXMLdocument.

TheactualcontentoftheXMLdependsonwhetherthecallissuccessfulornot.ThisreflectedintheErrorelement.

• Ifthecallissuccessful,thenthereisnoErrorelement,orifthereisone,thentheCodeattributeis0andtheMessageattributeisemptystring.

• Ifthecallfails,thenanerrorcodeandanerrormessagearereturned.• TheremaybenodataasthecallistoosoonaftertheitemwasplacedundertheQubeVu.Inthis

casetherewillbenoDimensionselementandthestatusattributewillindicatewhy.DimensionsareonlyavailablewhenstatusissettoIMAGINGorREMOVE–seebelowforothervalues.Non-zerodimensionsreturnedduringanystatusotherthanIMAGINGorREMOVEareconsideredinvalidandconsumercodeshouldignorethem.

<QVStatus CaptureId="string" Status="string" ExtendedStatus="string" OutOfBounds="int" > <Error Code="int" Message="string"> <LiveData TrackingId="int"> [Only present if READY] <TrackerImage Name="string" Url="string"/> </LiveData> <CapturedData CaptureDefinitionName="string"> [Only present if available] <ExternalData> <Barcode> <TextData>string</TextData> </Barcode> </ExternalData> <DateTime>string</DateTime> <Weight>float</Weight> <ScaleData> <Error Code="int" Message="string"> [Only present if error]


<Weight>int</Weight> <ScaleFactor>int</ScaleFactor> <IsStable>boolean</IsStable> <WeightUnit>string</WeightUnit> <RawData>string</RawData> <DisplayWeight>string</DisplayWeight> </ScaleData> <Dimensions [Only present if available] Irregular="boolean" Undersize="int" Oversize="int" Refinement="int" DimUnit="string" OutOfBounds="int" UnknownDimensions="boolean" UnknownDimensionsReason="string"> <Height>decimal</Height> <Length>decimal</Length> <Width>decimal</Width> </Dimensions> <TrackerImage /> [Only present if available] <LowResImages> [Only present if available] <LowResImage /> [Only present if available] </LowResImages> <HighResImages> [Only present if available] <HighResImage> [Only present if available] <Barcodes/> </HighResImage> </HighResImages> </CapturedData> <Crc>string</Crc> </QVStatus> Thisnotablockingcallandmayrequiretheclienttouseadelayedlooptocallituntilitreturnstherequiredresponse.

/QVStatus Top level wrapper element

./@CaptureId Sequential capture identifier. CaptureId is incremented each time QubeVu processes an item and is reset when the system is restarted.

./@Status The current status of the device/operation. See below for more details.

./@ExtendedStatus Extended information about the status of the device/operation. See below for more details.

./@OutOfBounds Flag indicating that an item


extends out of the sensor’s field of view. (1) Left, (2) Right, (4) Top, (8) Bottom or a combination of these.

/QVStatus/LiveData Live data preview, available in READY state

(firmware 4.9.3 and higher)

./@TrackingId A unique id number designed to help keep track of live data content changes. A new value indicates that clients should update their display showing live data content as it has changed since the last update.

./TrackerImage Details of preview image

./TrackerImage/@Url URL of preview image

./TrackerImage/@Name

/QVStatus/Error Error details

./@Code Error Code

./@Message Error Message

/QVStatus/CapturedData

Data captured by QubeVu

./@CaptureDefinitionName Name of capture definition that has triggered the capture

./@CaptureId Sequential capture identifier. CaptureId is incremented each time QubeVu processes an item and is reset when the system is restarted.


./ExternalData/Barcode/TextData The data read by the externally attached USB scanner. See Capture API function for more info.


./DateTime The date and time of the scan.

./Weight

./ScaleData Data reported from attached scale or received through Scale Service interface.

./Error Scale-specific error details

./@Code Error code

./@Message Error message

./Weight The weight of the item as an integer. Use scale factor to find number of decimal places.

./ScaleFactor Indicates the number of decimals in ./Weight

./IsStable Indicates whether the weight is stable or not.

./WeightUnit Specifies the unit in use for the weight.

./RawData Hex encoded raw data as received from the scale.

./DisplayWeight Weight and unit reported from the scale using the scale’s own unit settings and display format.

/QVStatus/CapturedData/Dimensions The dimensions of the item

./@Irregular Irregular shaped object (true or false)

./@Undersize Flag indicating undersize Height (4) or Width (2) or Length (1) or


a combination of these.

./@Oversize Flag indicating oversize Height (4) or Width (2) or Length (1) or a combination of these.

./@Refinement Refinement of Width (2) or Length (1) or a combination of these.

The Refinement field is a bit field indicating the refinement state of each dimension and whether the current certificate settings require the dimensions to be refined.

bit1 := set if Length is refined

bit2 := set if Width is refined

bit3 := set if Height is refined

bit4 := set if refinement is required (this is set under certification settings)

If refinement is not required (i.e. bit4 is not set) then the other bits should be ignored.

As an example a value of 8 means that refinement is required and Length, Width and Height are refined.

Note that for the LTL system, refinement is not required.

./@DimUnit The unit of measure. Valid values are ‘in’, ‘mm’, ‘cm’ and ‘m’.


./@OutOfBounds Flag indicating that an item extends out of the sensor’s field of view. (1) Left, (2) Right, (4) Top, (8) Bottom or a combination of these.

./@UnknownDimensions When dimensions cannot not be determined the unit returns 0-s for length, width and height and this indicator is set to true.


./@UnknownDimensionsReason When dimensions cannot not be determined and UnknownDimensions is true, the UnknownDimensionsReason attribute provides additional information about why the system was not able to dimension the item. For possible values and explanations, please see end of this section.


./Length Length of object (longer dimension in the X,Y plane)

./Width Width of object (shorter dimension in the X,Y plane)

./Height Height of object (dimension in the Z plane)

/QVStatus/CapturedData/RawDimensions Included if raw (unrounded) dimensions are enabled

./Length Length of object (longer dimension in the X,Y plane)

./Width Width of object (shorter dimension in the X,Y plane)


./Height Height of object (dimension in the Z plane)

/QVStatus/CapturedData/LowResImages Wrapper for zero or more LowResImage elements

/QVStatus/CapturedData/LowResImages/LowResImage

./@Url URL of low-res image

./@Name Unique name for image.

./ItemRect Either this element or ItemWireFrame is filled in.

./ItemRect/CenterX Item rectangle’s center on the captured image, horizontal coordinate (from left edge of image).

./ItemRect/CenterY Item rectangle’s center on the captured image, vertical coordinate (from top edge of image).

./ItemRect/D1 Width of item rectangle.

./ItemRect/D2 Height of item rectangle.

./ItemRect/Theta Clockwise rotation of item rectangle in radian.

./ItemWireFrame Either this element or ItemWireRect is filled in.

./ItemWireFrame/Faces Multiple faces may be defined

./ItemWireFrame/Faces/Face

./@Visible “false” if specified face is obstructed from view, “true” if visible

./Vertices Multiple points may be defined under this element

./Point


./X X pixel coordinate of the vertex

./Y Y pixel coordinate of the vertex

/QVStatus/CapturedData/HighResImages Wrapper for zero or more HighResImage elements

/QVStatus/CapturedData/HighResImages/HighResImage

./@Url URL of high-res image

./@Name






./ItemRect/Theta Clockwise rotation of item rectangle in radian.







./Point

./X X pixel coordinate of the vertex

./Y Y pixel coordinate of the vertex

./Barcodes Multiple Barcode elements, one for each barcode found, may appear under this item.

./Barcodes/Barcode Details of a single barcode

./RawData Barcode value (deprecated)

./EncodedData Barcode value in hex encoded format

./DecodedData Barcode value

./TextData Barcode value

/QVStatus/CapturedData/TrackerImage Details of low resolution image used for finding item

./@Url

./@Name

./ItemRect Either this element or ItemWireFrame is filled in






./ItemRect/Theta Clockwise rotation of item


rectangle in radian.






./Point

./X

./Y

/QVStatus/Crc Hex string of CRC32 checksum generated over the entire response string prior to inserting the CRC element. To validate checksum, calculate CRC32 over the entire response as it was received but exclude the CRC element and then compare to value stored in this element. Note that checksum includes all characters including whitespace and therefore cannot be calculated on an xml string that has been reconstructed by an xml parser from the parsed nodes.

Errorcodesandmessage:

ErrorCode Message0 None.


1 HardwareInitializationFAILED.2 TrackerConfigInitializationFAILED.3 MissingRegistrationMarksCropped.bmp.4 SettingreferenceimageforTargetfinderFAILED.5 LoadingofCalibrationfilesFAILED.6 GettingnewImagesfromhardwareFAILED.7 TrackingFAILED.8 Calibrating.9 TCPServerPortbindingfailed10 TCPServerexceptioninProcessingClient11 TCPServertimeoutonImaging12 Lowrescameraneedstobecalibratedfirst!13 Calibrationstopped.14 Errorloading/parsingConfiguration.15 UnabletosaveCalibrationtofile.

16 UnabletousenamesetinCapture/GetCommand.CaptureDefinitionwithnamewerenotset.

17 InvalidCaptureDefinitioncommand.18 UnabletodeleteCalibrationfiles.19 UnabletoZeroHeight20 Failedtowriteorverifyaudittrail

Scale-specificerrorcodesandmessages:

ErrorCode Message0 None.1 Timeoutwaitingforstableweight.

UnknownDimensionReasoncodesandexplanation:

UnknownDimensionReasonCode Explanation

<blank> Dimensionsdeterminationsuccessful.(UnknownDimensionsattributeissetto“false”)

Timeout Dimensionscouldnotbeestablishedwithinsystemspecifiedtimeoutperiod.

InvalidBackgroundDimensionscouldnotbeestablishedbecauseitem-freebackgroundcouldnotbeacquired.Pleasecleartheplatform,zerotheheightandtrytoscanagain.

InvalidBackgroundOrOutOfBounds

Dimensionscouldnotbeestablishedbecauseobjectisoutofboundsoritem-freebackgroundcouldnotbeacquired.Pleasecleartheplatform,zerotheheightandtrytoscanagainbyplacingtheitemcompletelywithinthescanzone.


NoDimItem Dimensionscouldnotbeestablishedbecausesystemisconfigurednottomeasurethistypeofitem.

InvalidDepthData Dimensionscouldnotbeestablishedduetoanunexpectedinconsistencyinthemeasureddepthdata.

RemoteSensorVoidPixel Dimensionscouldnotbeestablishedduetotoomanyvoidpixelsinthemeasureddepthdata.

Unknown Dimensionscouldnotbeestablished;reasonnotgiven.

5.1.1 Scanning without autotrigger

QubeVuissettodetecttwomajortypesofobjectsbydefault:parcelsandflatsitems.Dependingonsystemconfiguration,the2typesofautotriggerscanfeaturescanbecompletelysuppressed.Whenautotriggersaredisabled,theunitwillnotdetectwhenanobjectisplacedontheplatformautomatically,andthestatuswillstayinREADY(i.e.notgotoIMAGING).TheCaptureAPIcallisdesignedtoinitiateascanmanually.

Methodsignature:

QVServiceResponse Capture(string captureDefinitionName, string captureParameters)

captureDefinitionName-Thenameofthecapturedefinitionwhichshouldbeusedtoperformthescan.Ifparameterisomittedoremptystring,nocapturewilltakeplace.Ifnamecapturedefinitiondoesnotexist,anerrorresponsewillbereturned.

captureParameters-Usedbyexternalbarcodescanner.Userdefineddatamaybesentintheformat“<ExternalData><Barcode><TextData>string</TextData></Barcode></ExternalData>”.ThevalueofstringsentinwillbereturnedinthestatusXMLunder/QVStatus/CapturedData/ExternalData/Barcode/TextDatanode.

5.2 Retrieving the Image

IndesigningtheclientdialoguethatusestheQubeVuitshouldbekeptinmindthatthelocked-inQubeVuimageisavailablesometimelaterthanthedimensionsasithastodeterminethedimensionsbeforeitcanadjustthecameratotaketheimage(s).Thetransfertimeoftheimagestotheworkstationalsotakesafinitetime.

Theimagereturnedisofthetopfaceofitem.Thehigh-resolutioncamerawillzoominaccordingtotheparametersspecifiedinthecapturedefinition.

Startingwithversion4.9.3alow-resolutionpreviewimageisalsoavailable,butonlywhenthedeviceisintheREADYstate.Thisimageupdatesmultipletimespersecond.ClientscankeeptrackoftheTrackingIdattribute(inQVStatus/LiveDatatag)whichisdesignedtochangeeverytimethepreviewdata/imagecontentchangesindicatingthatclientUIareasshouldbeupdatedtoreflectsuchchange.

ThisusesHTTPGET:GET{imageurl}HTTP/1.1

TheimageurlisretrievedfromtheresponseofasuccessfulStatuscallasdescribedabove.TheimageisonlyavailableifthestatusvalueissettoREMOVE.

Itreturnsanimagefileinbitmapformat.Thecolourdepthandresolutionoftheimagedependsontheparametersspecifiedinthecapturedefinition.


5.3 Setting zero height of scan platform

TheQubeVudevicerecordsthedistancebetweenthecameraandtheplaneofthebaseplateduringcalibration.Thebaseplatformheightchangeswhenascale,whichrestsonthebaseplate,isattachedorremovedfromtheQubeVusetup.Whensuchachangeinbaseplatformheightoccursitisnecessarytotellthedevicetomeasuretheheightofthedistancebetweenthebaseandthecameraanew.Thisprocessisreferredtoas“zeroingheight”.Customersmustperformazeroheightoperationwhentheeffectiveplatformisraisedorloweredforanyreasonorthedevicewilllikelynotscanitemsuntilthisoperationissuccessfullyperformed.(ThisAPIcalldoesnotrequireQubeVutrackertoberestarted.)

ZeroingheightontheQubeVudeviceinvolvesplacingthecalibrationobjectontheplatform,steppingbackandthenmakingtheAPIcallbelowwith“true”passedinasparameter.Iftheplatformhasacompletelysmooth,uniformsurface,thenitisnotnecessarytouseacalibrationobject.Ifthesurfacehasanybumps,ridges,ascalewithtexturedtopplateorithasrollersthenacalibrationobjectmustbeplacedontheplatformbeforecallingSetZeroHeight.Onlywhenthebaseplaneiscompletelysmoothandflat(adotorgraphicorpatternisOKaslongasit’sflatandlevelwiththebaseplate)thenyoucancalltheAPIwiththe“false”argumentandNOTuseacalibrationobjectforthezeroheightprocess.

Methodsignature:

QVServiceResponse SetZeroHeight(bool usingCalibrationObject)

Theprocessusuallytakes1-6seconds.Duringthistimethedeviceshouldbeleftundisturbed.ThemethodreturnsasinglestringvaluecontaininganXMLdocument:

<QVServiceResponse> <Error Code="int" Message="string" > </QVServiceResponse>

Atthispointthecalibrationobjectmayberemovedfromtheplatform(ifonewasused).ErrorCode0indicatesasuccessfulzeroheightoutcome.Anyerrorcodeotherthan0shouldbeinterpretedasfailuretozeroingheight.Itisrecommendedthatimplementersofthezeroheightprocessofferusersachancetoretryzeroingtheheightuponfailure.AretrysimplymeansanothercalltoSetZeroHeightasbefore.

5.3.1 Zero height error messages

Message MeaningandResolution

Motiondetected

Motionwasdetectedduringthezeroheightprocess.Pleasemakesuretonotinterferewiththedeviceduringzeroheightoperation.Leavetheplatformclearofobjectscompletelyorleavetheplatformwithjustthecalibrationobjectplacedontopofthescale(ifoneisused)orothernon-smoothsurface.

Heightnotstable

Pleasemakesuretonotinterferewiththedeviceduringzeroheightoperationandtryzeroingheightagain.IfproblempersistspleasecontactPosteasupport.

Changeinheightexceededsetvalue

Therewasanunexpectedlylargedifferenceinpreviouslyknownheightandnewlymeasuredheight.Toremedythissituationpleasemakesurethatthenewheightisclosertotheoriginallymeasuredheightoralternatively,youmayincreasetheZeroheightmaxchange(ZeroHeightChangeMaxMM)configurationiteminAdmintools!MeasurementSettings.


5.4 Retrieving barcodes

Readingbarcodesrequiresthecaptureofanimagebythehighresolutioncameratypicallyat140dpiorbetterbuttheactualresolutionwilldependonthebarcodetoberecognized.QubeVuprovidestwoapproachestoretrievebarcodesfromthecapturedhighresolutionimages.

Oneapproachistosimplyspecifythetypesofbarcodesofinterestinthecapturedefinition.OncethisissetupthenQubeVuwillsearchforbarcodesinthecorrespondinghighresolutionimagesandwillreturnthevaluesofeachbarcodefoundinresponsetoaStatusalongwiththehighresolutionimages’urls.ThefoundbarcodesarereturnedintheBarcodeselementofeachHighResImage.

AnotherapproachistousetheQubeVuBarcodesClientAPI.ThisAPIcanbeusedbytheclientapplicationtofindbarcodesfromahighresolutionimagecapturedbyQubeVu.TheAPIissimpletouseandisdescribedindetailinthefollowingsectionsAppendixF–QubeVuBarcodesClientAPI,AppendixG–Postea.QubeVu2DBCRecognitionClientAPI,AppendixH–SupportedbarcodeswithsamplecodeavailableasdescribedinAppendixC–C#.Netcodesamples.

ThebenefitofusingtheclientAPIisthatitcantakeadvantageofthefastprocessorsoftheclienthardwareandgettheresultsfaster.

Notethatthenumberofbarcodetypesenabledwillhaveaneffectonperformance;themorebarcodetypesthatareenabledthelongeritwilltaketoprocessanimage.Foroptimumperformanceminimizethenumberofbarcodetypesthatareenabled.

5.4.1 Enabling barcode recognition through capture definition

UsetheCreateCaptureDefinitioninterfacetoenablebarcoderecognition.

E.g.

<CaptureDefinitionDetail Name=\"autotriggerparcel\"> <TimeoutMsecs>0</TimeoutMsecs> <NoDimItems>Flat</NoDimItems> <LowResImages></LowResImages> <HighResImages> <HighResCamCapture ImageName=\"HighResImage1\"> <MinDpi>140</MinDpi> <MaxDpi>140</MaxDpi> <BarcodeCapture> <BCTypes>CODE128 CODE93 CODE39</BCTypes> </BarcodeCapture> </HighResCamCapture> </HighResImages> </CaptureDefinitionDetail>

ForinformationontheCreateCaptureDefinitioninterfacepleaseseetheCaptureDefinitionssectionbelow.

5.5 Setting the weight from an external scale.

InatypicalconfigurationaweighingscaleisconnectedtoQubeVutodetectitemplacementandremoval.Insomesituations,itmaybenecessarytohavethescaleconnectedtotheclientcomputerdirectlyratherthantotheQubeVudevice.Onesuchscenarioiswherethereisanexistingclient


applicationthatrequiresdirectcontrolofthescale.OperatingQubeVuwithanexternalscalerequiresthatthe‘Scaletype’configurationitembesetto‘EXTERNAL’andthataprocessontheclientcomputermonitorsthescaleandnotifiesQubeVuofanyweightchanges.Itisimportantthattheweightchangenotificationhappensinatimelyfashiontoensurethatitisinsynchwithwhatthescanheadsees.

Figure1-Externalscaleconfiguration

ClientapplicationmustusetheQubeVu’sscaleservicetonotifythedeviceofanyweightchangewhenusingtheexternalscaleconfiguration.Thescalewebservicecanbefoundatthefollowingurl:http://{device}/WebServices/ScaleService.

UsetheScaleService/SetCurrentWeightwebservicemethodtonotifyQubeVuofanyweightchanges,regardlessofwhethertheweightiszeroornotortheweightisstableornot.

ItisimportanttonotethatwhentheQubeVufirststartsupitwillnotenterthe‘Ready’stateuntilithasbeennotifiedthatthereisastablezeroweightbeingoutputfromthescale.ThiswillbeautomaticallydetectedifthescaleisconnecteddirectlytotheQubeVubutmustbecommunicatedtotheQubeVuviatheSetCurrentWeightwebservicemethodwhenusinganexternalscaleconfiguration.

Thebestwaytoimplementthisistouseabackgroundprocess/thread/taskthatconstantlyqueriesthecurrentweightfromthescaleandthencallstheSetCurrentWeightmethodwiththevaluesreceivedfromthescale.

Methodsignature:


QVServiceResponse SetCurrentWeight(int weight, int scaleFactor, bool isStable, string weightUnit)

weight-Thecurrentweightreturnedbythescale.

scaleFactor–Apositiveofnegativepoweroftentobeusedtomultiplythevalueinweighttogettheactualweightinthespecifiedunits.

isStable–Indicateswhetherthespecifiedweightreadingisstableornot.Astableweightisrequiredtostartcapture.Astablezeroweightisrequiredforbackgroundupdates,however,anon-stablezeroweightordropinweightwillsignalitemremoval/orreplacement.

weightUnit–Theunitoftheweightspecified.Currentlysupportedunitsare‘g’forgramsand‘oz’forounces.

ThemethodreturnsasinglestringvaluecontaininganXMLdocument.

<QVServiceResponse> <Error Code="int" Message="string" > [Only present if error] <CapturedData CaptureDefinitionName="string"> [Only present if available] </QVServiceResponse>

5.6 Returned values

5.6.1 Status

Statusvalue Meaning

STARTING Theserviceisstartingup.

STARTED Theservicehasstartedbutisnotreadyforprocessing.Ifthedeviceisinthisstatusformorethanacoupleofsecondsafterstartingthenitisverylikelythatthereisanitemontheplatformthatneedstoberemoved.Theplatformshouldbeclearwhenthedevice/serviceisstarting.

READY Thedeviceisreadyandwaitingtobeused–thereisnoitemonit.

TRACKING Thedeviceisprocessingachangeinimageafteranitemhasbeenplacedunderit.

IMAGING Thedevicemeasurementshavebeendeterminedandthecameraisbeingadjustedtotaketheimage.

REMOVE Theimagehasbeenfullyprocessed–theitemcanberemovedwhentheclientprocessinghascompleted.

WAIT Preparingthedeviceforthenextitem.Thepreviousimageanddimensionsaredeletedfrommemoryandthelensisreset.

STOPPING DeviceistransitioningintoSTOPPEDstate.

STOPPED Theservicehasstopped–thereissomeproblem.

CALIBRATING Thedeviceisincalibrationmode.


CONFIGURING Thedeviceisinconfigurationmode.

5.6.2 Extended status

Thereturnedextendedstatusattributecontainsnoneormorecommaseparatedstringsthatprovideadditionalinformationaboutthestatusofthedevice.

Constraintvalue Meaning

ScaleNotStable Thisissetduringtrackingifthescaleindicatesthatthevaluereturnedisnotastablevalue.Thisisonlyusedwhenarecognizedscaleisconnectedtothesystem.Processingwillnotprogresstothenextstepuntilthisflagisclearedbyreceivingastableweightfromthescale.

MotionDetected Thisissetduringtrackingandreadystatesandindicatesthatthesystemhasdetectedmovement.Processingwillnotprogresstothenextstepwhilethisisset.

ItemDetected Thisissetwhenthesystemhasdetectedthatanitemisplacedonthedeviceplatform/scale.Whenascaleisusedthisindicatesthatweightreturnedisnotzero.In‘scale-less’modethisindicatesthatthesystemcannotfindthetargetpanel.

ItemNotDetected Thisissetwhenthesystemisinreadymodeandthereisnoitemontheplatform/scale.

TrackerNotConfident Thisindicatesthatthetrackerdetectedanitembutitisnotconfidentwhatthedimensionsoftheitemare.Afteratimeout(configurable)thesystemwillprogresstonextstepandreturnzero-valueddimensions.

ExceptionOccured Thisissetwhenanexceptionoccurs.

DeviceNotStable Thisissetduringtrackingifoneofthesensorsindicatesthatthesensorvaluereturnedisnotastablevalue.Processingwillnotprogresstothenextstepuntilthisflagisclearedbyreceivingastablevaluefromthesensor.

ServiceStarting Thisissetwhenthesystemisinitializing.

ConfigMode Thisissetwhenthesystemisinconfigurationmode,suchasduringcalibrationorimageexposureadjustment.Arestartoperationtakesthedeviceoutofconfigurationmode.

ResultNotStable Thisissetwhentheitemisbeingmanipulatedsuchaswhentheitemisintheactofbeingplacedontheplatformorremovedfromit.

ItemOutOfBounds Thisindicatesthattheitemprotrudesoutsidethemeasurablearea.Arepositioningoftheitemisnecessary.

WaitingToWarmUp Thisissetduringthewarmupperiod.Ifdeviceisusedinacertified-for-tradeapplicationthewarm-upperiodmusthavebeenelapsedbeforecertifiedmeasurementscanbetaken.

PlatformNotClear Thisissetwhenthereissomethingontheplatform.


5.7 Capture definitions

5.7.1 Creating capture definitions

UsetheCreateCaptureDefinitioninterface:QubeVuService/CreateCaptureDefinition

Methodsignature:

QVServiceResponse CreateCaptureDefinition(string name, string definitionString)

name-Thenameofthecapturedefinitiontobecreated

definitionString–TheXMLstringdescribingthecapturedefinition.

<CaptureDefinitionDetail Name="string" > <TimeoutMsecs>int</TimeoutMsecs> <NoDimItems>nodim_options</NoDimItems> <LowResImages> <LowResCamCapture ImageName="string" > <ResX>int</ResX><ResY>int</ResY> <Markings> <SerialNumber Visible="boolean"/> <DateTimeStamp Visible="boolean"/> <ScanId Visible="boolean"/> <Dimensions Visible="boolean"/> <Indicators Visible="boolean"/> <ItemOutline Visible="boolean"/> </Markings> </LowResCamCapture> </LowResImages> <HighResImages> <HighResCamCapture ImageName="string"> <MinDpi>int</MinDpi> <MaxDpi>int</MaxDpi> <BarcodeCapture> <BCTypes>bctype_list</BCTypes> </BarcodeCapture> </HighResCamCapture> </HighResImages> </CaptureDefinitionDetail>

ThemethodreturnsasinglestringvaluecontaininganXMLdocument.

<QVServiceResponse> <Error Code="int" Message="string" > [Only present if error] <CapturedData CaptureDefinitionName="string"> [Only present if available] </QVServiceResponse>

/CaptureDefinitionDetail Top level wrapper element

./@Name Name of the capture definition.


./TimeoutMsecs The system will report a timeout when it is unable to detect an item within the time specified by the capture definition. If the timeout is set to zero, then system will continue trying indefinitely.


./NoDimItems Specifies the type of items that should be processed without dimensioning. For LTL systems this must be set to ‘None’. See table below for more options.

/CaptureDefinitionDetail/LowResImages/LowResCamCapture Low resolution image parameters

./ResX Specifies the X resolution of the low resolution image to be taken. For LTL sytems this should be 640.

./ResY Specifies the Y resolution of the low resolution image to be taken. For LTL sytems this should be 480.

./Markings/SerialNumber/@Visible Specifies whether to show the serial number on the low resolution image.

./Markings/DateTimeStamp/@Visible Specifies whether to show the date/time stamp on the low resolution image.

./Markings/ScanId/@Visible Specifies whether to show the scan id on the low resolution image.

./Markings/Dimensions/@Visible Specifies whether to show the dimensions on the low


resolution image.

./Markings/Indicators/@Visible Specifies whether to show the indicators (over size, under size, unrefined) on the low resolution image.

./Markings/ItemOutline/@Visible Specifies whether to show the item outline (bounding box) on the low resolution image.

/CaptureDefinitionDetail/HighResImages/HighResCamCapture High resolution image parameters. Not applicable to LTL systems.

Thefollowingtabledescribesthevalidvaluesfornodim_options.

Nodimoption Meaning

None Dimensionallitems.Thisisthedefault.

Flat Donottrydimensioningflats–i.e.itemsthataretallerthantheflatthreshold.

Parcel Donottrydimensioningparcels-i.e.itemsthanthatarenottallerthantheflatthreshold.

All Donottrydimensioninganyitems.

Thefollowingtabledescribesthevalidvaluesforbctype_list.Multiplevaluesmustbeseparatedbyaspace.

BCTypes Meaning

EAN13 EnabledecodingofEAN13 barcodes.

CODE128 EnabledecodingofCODE128 barcodes.



EAN8 EnabledecodingofEAN8 barcodes.

UPCE EnabledecodingofUPCEbarcodes.

UPCX EnabledecodingofUPCXbarcodes.

INT25 EnabledecodingofINT25 barcodes.

CODABAR EnabledecodingofCODABARbarcodes.


PATCHCODE EnabledecodingofPATCHCODEbarcodes.

DATAMATRIX EnabledecodingofDATAMATRIXbarcodes.

QR EnabledecodingofQRbarcodes.

PDF417 EnabledecodingofPDF417 barcodes.

5.7.2 Listing capture definitions

ListallcapturedefinitionsdefinedinQubeVu,oneCaptureDefinitionXMLelementforeachdefinition.UsetheCaptureDefinitionListinterface:QubeVuService/CaptureDefinitionList

Methodsignature:

QVCaptureDefinitionList CaptureDefinitionList(string filter)

filter–Ignored.Maybeomitted.

ThemethodreturnsanXMLdocument.

<QVCaptureDefinitionList> <Error Code="int" Message="string" > [Only present if error] <CaptureDefinitions> <CaptureDefinition Name="string"> </CaptureDefinitions> </QVCaptureDefinitionList>

5.7.3 Retrieving capture definition details

Retrievedetailsofspecifiedcapturedefinition.

Methodsignature:

CaptureDefinitionDetail GetCaptureDefinition(string name)

name–Nameofcapturedefinitionyouwishtoretrieve.

ThemethodreturnsanXMLdocument.ThedetailsofCaptureDefinitionDetailXMLaredefinedearlierinthissection.

5.7.4 Deleting capture definition

Deletethespecifiedcapturedefinition.

Methodsignature:

QVServiceResponse DeleteCaptureDefinition(string name)

name–Nameofcapturedefinitionyouwishtodelete.

ThemethodreturnsanXMLdocument.AnErrorXMLelementwiththeerrormessagewillbereturned.Codeof0andemptyMessageattributeindicatessuccess.Ifthecapturedefinitionspecifieddoesnotexist,anerrorcode16willbereturned.Foracompletelistoferrorcodesandmessagespleaserefertothebeginningofthissection.


<QVServiceResponse> <Error Code="int" Message="string" > </QVServiceResponse>

5.8 System Date and time

5.8.1 Getting system time

Getssystemtimeanddateinspecifiedformat.

Methodsignature:

QVSystemTime GetSystemTime(string format)

format-Formatshouldbe+sequenceasdefinehere:http://linux.die.net/man/1/date.Ifnoformatisprovided(i.e.parameternotsentinPOSTdataorspecifiedasemptystring),then+%Y%m%d%H%M%S %z %Zwillbeused,whichmeansYYYYMMDDHHMMSS-0500EST

5.8.2 Setting system time and time zone

Setssystemtimeanddateinspecifiedformat.

Methodsignature:

QVServiceResponse SetSystemTime(string time, string timezone)

time-TimemustuseformatYYYYMMDDHHMMSSor(e.g.youmightuseDateTime.Now.ToString("yyyyMMddHHmmss")toformthestringyoulatersendinC#).

timezone-TimezonesarebasedonUbuntuTrustytimezones,e.g."America/New_York",or“US/Eastern”.Foracompletelist,pleaserefertohttp://manpages.ubuntu.com/manpages/trusty/man3/DateTime::TimeZone::Catalog.3pm.html

5.9 Device info

DeviceInfocallreportshardwareandnetworkpropertiesofthedevice.TheURLissimilartopreviousservicecalls:

http://{QubeVu_host}/Webservices/QubeVuService/DeviceInfo

ItreturnsasinglestringvaluecontaininganXMLdocument.<QVDeviceInfo xmlns="http://postea.com/WebServices/QubeVu"> <Error Message="None." Code="0"/> <DeviceInfo> <ModelNo>string</ModelNo> <Manufacturer>string</Manufacturer> <FirmwareVersion>string</FirmwareVersion> <SerialNo>string</SerialNo> <CertificateNo>string</CertificateNo> [Only present if available] <CertificateType>string</CertificateType> [Only present if available] <FirmwareCrc>string</FirmwareCrc> </DeviceInfo>


<NetworkInfo> <Ip>string</Ip> <NetworkMask>string</NetworkMask> <Gateway>string</Gateway> <IsDhcp>boolean</IsDhcp> <LeaseExpires>string</LeaseExpires> <MacAddress>string</MacAddress> <Hostname>string</Hostname> <SslEnabled>boolean</SslEnabled> </NetworkInfo> </QVDeviceInfo>

/QVDeviceInfo/DeviceInfo Device hardware information and certification status wrapper

./ModelNo Device model.

./Manufacturer Manufacturer of the device.

./FirmwareVersion Version of the currently installed firmware.

./SerialNo Serial number of the unit.

./CertificateNo If a certified set of configuration is in effect this element shows the certificate number. (E.g. 15-023P) Always returns empty element for non-certified firmware.

./CertificateType If a certified set of configuration is in effect this element shows the certificate number. (E.g. NTEP) Always returns empty element for non-certified firmware.

./FirmwareCrc Firmware CRC check bytes. Used in legal-for-trade certification.

/QVDeviceInfo/NetworkInfo Network information wrapper

./Ip Public IP address of device. E.g. 192.168.1.2

./NetworkMask Network mask for the unit. E.g. 255.255.255.0

./Gateway Gateway for the network interface of QubeVu. E.g. 192.168.1.1

./IsDhcp True if IP address is dynamically acquired, false if static IP.

./LeaseExpires If present, the date and time when DHCP lease expires. E.g. 2016/12/31 23:59:59

./MacAddress MAC address of the device.

./Hostname Hostname of QubeVu unit.

./SslEnabled True if SSL is enabled, false otherwise. QubeVu Manager


and the WS API is accessible through HTTPS in addition to HTTP, when enabled.

(The elements listed above may return empty under certain conditions. Consumers of the API should ensure their code is prepared to handle such cases.)

5.10 Restarting

RestartstheQubeVuserviceordevice.

Methodsignature:

QVServiceResponse Restart(string restartMode)

restartMode-Whenomittedorpassinganemptystring,theAPIcallrestartsthetrackingmodule.Thisisusuallynecessarywhenconfigurationsettingsarechanged(excludescapturedefinitionchanges),orwhenanewscaleisconnected.Arestartisalsonecessarytoexitconfigurationmode.AccessingcertainadministrativepagesfromQubeVuManagerwillresultinthedeviceswitchingtoconfigurationmode.

Passing“REBOOT”forrestartModeparameterwillresultinacompleteshutdownandrestartoftheQubeVuunit.

5.11 Miscellaneous

5.11.1 Deprecated Function

CalltoadeprecatedAPIfunctionwillresultinanHTTP404(NotFound)errorresponse.

Methodsignature:

QVServiceResponse SetZero()


6 External Interfaces: Serial, TCP and HTTP

SerialinterfacecommunicationispossibleusingUSBandserialcables.Formoreinformationaboutcablehardwaresetup,pleasecontactQubeVuSupport.TheuseofTCPorHTTPprotocolsdonotrequireanyadditionalhardwaresetup.

Serial,TCPandHTTPinterfacesmustbeenabledinQubeVu’sconfiguration.PleaserefertoQubeVuManagerGuideforconfigurationdetails.

SerialandTCPinterfacesusethesameprotocolformatsforsendingdatatotheclientdevice(PC).

6.1 Protocol Modes

TheconfigurationoftheserialorTCPinterfacesmaybesettooneofthefollowingoptions:

• Off–QubeVuwillnotberespondingtoincomingserialport(orTCP)commands.(default)• QubeVu–AverysimpleQubeVuprotocolisused.OnlytheDimensioncommandisvalid.Thedevice

willreturn‘?’toallothercommands.Controlcharactersareomitted.• Cubiscan110/150–InCubiscanemulationmode,amorecomprehensivecommandsetissupported

asdescribedbelow.PleasenotethatonlyasubsetofallcommandssupportedbyCubiscanproductsareimplementedbyQubeVu.

SpecialcharactersymbolsarebasedonstandardASCIInotation:

Characterorsymbol Decimal Hexadecimal Meaning

<STX> 2 0x02 StartofText

<ETX> 3 0x03 EndofText

<LF> 10 0x0A LineFeed

<CR> 13 0x0D CarriageReturn

6.2 QubeVu Protocol

Command

Description Request Response

Dimension

CausestheQubeVutosendthedimensionandweightdatatotheclientcomputer.

D<CR> {length}x{width}x{height}{dimUnit}{displayWeight}<CR><LF>

Errorhandling

Unitwillreturnfollowingresponsewhendimensionsarenotavailable.

D<CR> 0x0x0{dimUnit}<CR><LF>


Invalidcommand. … ?<CR><LF>

DisplayWeightnote:displayWeightaboveisthesamevaluewhichappearsin/StatuswebserviceAPIcall.(XPath:/QVStatus/CapturedData/ScaleData/DisplayWeight)Itistheweightandweightunit(combined)asreportedfromthescaleusingthescale’sownunitsettingsanddisplayformat.IfascaleisnotconnectedthenDisplayWeightmaybeblank(seeexamplebelow).

6.2.1 Sample Requests and Responses

1. DimensionCommandRequest:D<CR>

Response:9.75x7.25x3.50in<CR><LF>

2. DimensionCommandRequest:D<CR>

Response:0x0x0in<CR><LF>

3. InvalidCommandRequest:M<CR>

Response:?<CR><LF>

6.3 Cubiscan Emulation Protocol

6.3.1 Request and Response

Eachrequestmustbemadeusingthefollowingformat:

<STX><COMMAND><ETX><CR><LF>

Theresponsewillbeeitheranacknowledgementoranegativeacknowledgement(errorcondition)intheformatsbelow:

Acknowledgement:<STX><COMMAND>A<DATA><ETX><CR><LF>

Negativeacknowledgement:<STX><COMMAND>N<ETX><CR><LF>

6.3.2 Supported Commands

Command

Description Request<COMMAND>

Response

ContinuousMeasureandMeasure

CausestheQubeVutotransmitthedimensionandweightdataofthepackagetotheclientcomputer.

CorM <STX>MAH000000,L<LENGTH###.#>,W<WIDTH###.#>,H<HEIGHT###.#>,<M/Eformetric/USCustomary>,


K<WEIGHT###.##>,D<DIMWEIGHT###.##>,<M/Eformetric/USCustomary>,F<DIMWEIGHTFACTOR####>,D<ETX><CR><LF>

e.g.

<STX>MAH000000,L009.8,W007.2,H003.5,E,K000.00,D000.00,E,F0138,D<ETX><CR><LF>

Errorhandling

Unitwillreturnfollowingresponseimmediatelywhendimensionsarenotavailable.

CorM Sameformatasabove,butalldimensionandweightvalueswillbe0(seesamplebelow)

Invalidcommand. … <STX>?N<ETX><CR><LF>

Test

ThiscommandcausesthedevicetoreplywitharesponseofTA00meaningthatQubeVuisreadyandrespondingtotransmissionsfromtheclient.Iftheclientreceivesnoresponsefromtheunitaftersendingthiscommand,anerrorconditionexistsinthecommunicationsbetweenthehostandcontroller.

T <STX>TA00<ETX><CR><LF>

Units

Thiscommandcausesthedevicetoreportitscurrentmodesofoperation.

U WhenQubeVuusesthemetricsystem,theresponsewillbe:

<STX>UAMMD0000100000<ETX><CR><LF>

ForUSCustomary:

<STX>UAEED0000100000<ETX><CR><LF>

Values

Thiscommandcausesthedevicetoreportallitsinternalparametersasdefaultvalues(mostlyas0-s).Thiscommandisimplementedforcompatibility.

V <STX>VA0.00,0.00,0.00,0.00,0000,0000,0000,0000,0.00,0.00,0.00,0.00,0.00,0.00,0.00,0.00,00,00,00,00,000,000,000,000,100L,100,1.000<ETX><CR><LF>

ZeroHeight

Causesthedevicetosetthezeroheightofthescanplatform.(Donot

Z <STX>ZA<ETX><CR><LF>


useacalibrationobjecttozeroheight.)

ReadIPAddress

ThiscommandisusedtoreadthecurrentIPaddresssettingofthedevice.

~I <STX>~IA<IP><ETX><CR><LF>

ReadTCPPort

ThiscommandisusedtoreadthecurrentTCPportofthedevice.

~P <STX>~PA<PORT><ETX><CR><LF>

ReadSubnetAddress

Thiscommandisusedtoreadthecurrentsubnetmasksettingofthedevice.

~N <STX>~NA<IP><ETX><CR><LF>

ReadGatewayAddress

Thiscommandisusedtoreadthecurrentlyspecifiedgateway’sIPaddressfromthedevice.

~G <STX>~GA<IP><ETX><CR><LF>

Note:Certaincommands(‘D’,‘”’,‘F’,‘L’,‘S’,‘#’,etc.)donotreturnanegativeacknowledgementmessage.Thisisbehaviorisintentionalandimprovescompatibilityinsomesituations.

6.3.3 Sample Requests and Responses

1. TestCommandRequest:<STX>T<ETX><CR><LF>

Response:<STX>TA00<ETX><CR><LF>

2. InvalidCommandRequest:<STX>A<ETX><CR><LF>

Response:<STX>?N<ETX><CR><LF>

3. MeasureCommandRequest:<STX>C<ETX><CR><LF>OR<STX>M<ETX><CR><LF>

Response:<STX>MAH000000,L009.8,W007.2,H003.5,E,K000.00,D000.00,E,F0138,D<ETX><CR><LF>OR<STX>MAH000000,L000.0,W000.0,H000.0,E,K000.00,D000.00,E,F0138,D<ETX><CR><LF>

4. UnitsCommandRequest:<STX>U<ETX><CR><LF>

Response:<STX>UAEED0000100000<ETX><CR><LF>

6.3.4 Troubleshooting

TestingTCPconnectivityisstraightforwardonWindows.Openacommandpromptandtype:


telnet <QubeVu_IP> <TCP_port>

e.g.telnet169.254.1.11024

Thecommandscreenshouldturnblankwhentheconnectionismadesuccessfullyandthesessionbegins.

QubeVuprotocoldoesnotusecontrolcharacters.Simplytype:D<ENTER>togetdimensions.

TotesttheCubiscanemulationmode,youcansend<STX>characterbypressingCTRL+B,and<ETX>usingCTRL+C.E.g.,tosendaTestcommand,typethefollowingsequence:<CTRL+B>T<CTRL+C><ENTER>

Youshouldseearesponsesimilartothis:

6.4 HTTP Protocol

WhenHTTPprotocolisenabled,itispossibletointerfacewithQubeVuinamannerthatiscompatiblewithParcelCube900R2device.

6.4.1 Request and Response

Clientsusingthisinterfaceshouldsendwell-formedHTTPGETmessages(similarlytowebbrowsers’implementation).Theresponsewillbeatext/plainMIMEtypemessage.Theresponsewillcontaindimensionandweightinformationwhenavailable,or0-swhensuchinformationisnotavailable.TheorderofthedatafieldsisdeterminedbyconfigurationwhichcanbemodifiedinQubeVuManager.

Samplerequestsandresponsesareincludedbelowforscenarioswhen(1)dataisnotavailableand(2)whenitis.[…]markersrepresentomittedcontenttopreservebrevityinordertobetterillustrateimportantpartsofthedialog.

GET http://192.168.2.55:8080/ HTTP/1.1 Host: 192.168.2.55:8080 User-Agent: [...] Accept: text/plain [or */*] [...] HTTP/1.1 200 OK Date: Mon, 23 Oct 2017 17:25:47 GMT Server: Apache/2.4.7 (Ubuntu) Content-Length: 23 Content-Type: text/plain [...] 0;0;0;0;0;0;;;;;;;0;0;0 ------------------------------------------------------------------


GET http://192.168.2.55:8080/ HTTP/1.1 Host: 192.168.2.55:8080 User-Agent: [...] Accept: text/plain [or */*] [...] HTTP/1.1 200 OK Date: Mon, 23 Oct 2017 17:25:52 GMT Server: Apache/2.4.7 (Ubuntu) Content-Length: 41 Content-Type: text/plain [...] 9.75;7.00;3.75;0;0;0;;;;;;;9.75;7.00;3.75

6.4.2 Response Format Configuration

TheformatconfigurationstringisstoredinQubeVu’soptions,underHttpEmulationFormatsetting(alsoexposedontheGeneralSettingspageofQubeVuManager).Thedefaultresponseformatis:

%LENGTH%;%WIDTH%;%HEIGHT%;0;%WEIGHT%;0;;;;;;;%LENGTH%;%WIDTH%;%HEIGHT%

ThetokensintheformatstringcorrespondtovaluesasiftheywereparsedfromtheXMLresultofaStatusAPIcalldescribedinSection5.1RetrievingtheDimensions.

Token XPathfromStatusAPIcall

%LENGTH% /QVStatus/CapturedData/Dimensions/Length

%WIDTH% /QVStatus/CapturedData/Dimensions/Width

%HEIGHT% /QVStatus/CapturedData/Dimensions/Height

%DIMUNIT% /QVStatus/CapturedData/Dimensions/@DimUnit

%WEIGHT% /QVStatus/CapturedData/ScaleData/Weight(scaledby/QVStatus/CapturedData/ScaleData/ScaleFactor)

Note:%WEIGHT%-notthesameasrawStatusXML.TheScaleFactorisalreadyappliedtotheraw<Weight>numbervalue.

%DISPLAYWEIGHT% /QVStatus/CapturedData/ScaleData/DisplayWeight

%%% %(literal)


7 Appendix A – Short format URLs

ManyAPIcallscanbeaccessedusingashortformURL.Theuseoftheseshortformsarenotrecommendedinaproductionsystemastheycanchangewithoutnotice.

ShortformURL(casesensitive)

e.g.http://{device}/status

ProductionURL(caseindifferent)

e.g.http://{device}/WebServices/QubeVuService/Status

/status /WebServices/QubeVuService/Status

Queryingreal-timedeviceinformation

/status

Managingtrackerenginelifetime

/restart

/stop

/start

Troubleshootingandmaintenance

/log

/log_1

/extractlog

Queryingconfigurationanddeviceinfo

/config

/options

/deviceinfo /WebServices/QubeVuService/DeviceInfo

Displaypages(shortURLsareintendedforproduction)

ShortformURL(casesensitive) AlternateURL

/display

/operatordisplay

/certified/displays/dsdisplay.php

(weightpanelisshowndependingonSuppressScaleDatasetting)

/customerdisplay /certified/displays/dsdisplay.php?pgtype=customer

(weightpanelisshowndependingonSuppressScaleDatasetting)

/dimonlydisplay /certified/displays/dsdisplay.php?pgtype=dimonly

/certified/displays/dsdisplay.php?pgtype=dimonlyoperator

/dimandweightdisplay /certified/displays/dsdisplay.php?pgtype=dimandweight

/certified/displays/dsdisplay.php?pgtype=dimandweightoperator


/dimonlycustomerdisplay /certified/displays/dsdisplay.php?pgtype=dimonlycustomer

/dimonlyoperatordisplay /certified/displays/dsdisplay.php?pgtype=dimonlyoperator

/dimandweightcustomerdisplay /certified/displays/dsdisplay.php?pgtype=dimandweightcustomer

/dimandweightoperatordisplay /certified/displays/dsdisplay.php?pgtype=dimandweightoperator


8 Appendix B – Sample .Net client code

ThisappendixcontainsthesourcecodeforaC#classtheusestheAPIdefinedabovefortestingpurposes.SamplecodeinotherlanguagessuchasJava,JavaScriptarealsoavailableuponrequest.

1) Createnewproject

• CreatenewConsoleApplicationprojectandnameitDim101_cs

2) Addreferences

• AddSystem.EnterpriseServicesreference

• AddSystem.Web.Servicesreference

3) Addwebserviceclientproxy

• AddQubeVuServiceHttpPostClient.cstoproject

4) Addsamplecode

• PastefollowingcodeintoProgram.cs

/* * QubeVu Dimensioning Sample Code #1 * * Include QubeVuServiceHttpPostClient.cs in the project. * * The following references are required by QubeVuServiceHttpPostClient.cs: * System.EnterpriseServices * System.Web.Services * System.Xml * */ using System; using QubeVuWebService; // needed for QubeVuService class - defined in QubeVuServiceHttpPostClient.cs namespace Dim101_cs { class Program { static void Main(string[] args) { // * modify this line below * - replace default IP address of QubeVu with your own unit's IP string qubeVuHost = "169.254.1.1"; QubeVuService qubeVuService; // // construct web service url using specified hostname // if (args.Length > 0) { qubeVuHost = args[0]; } string webServiceUrl = "http://" + qubeVuHost + "/WebServices/QubeVuService"; Console.WriteLine("Connecting to {0} ...", webServiceUrl); // // create an instance of the QubeVu service // qubeVuService = new QubeVuService();


// // set web service parameters: url, timeout // qubeVuService.Url = webServiceUrl; qubeVuService.Timeout = 1000; // // request status from QubeVu // QVStatus qvStatus = qubeVuService.Status(); Console.WriteLine("Connection successful"); // // show status // Console.WriteLine("Status: {0} Capture Id: {1} Ex status: {2}", qvStatus.Status, qvStatus.CaptureId, qvStatus.ExtendedStatus); // show dims and tracker image url if available if (qvStatus.Status == "IMAGING" || qvStatus.Status == "REMOVE") { Console.WriteLine("Dimensions: {0} x {1} x {2} ({3})", qvStatus.CapturedData.Dimensions.Length, qvStatus.CapturedData.Dimensions.Width, qvStatus.CapturedData.Dimensions.Height, qvStatus.CapturedData.Dimensions.DimUnit); Console.WriteLine("Tracker image: {0}", qvStatus.CapturedData.TrackerImage.Url); } // show image url from high resolution camera if available if (qvStatus.Status == "REMOVE") { if (qvStatus.CapturedData.HighResImages != null && qvStatus.CapturedData.HighResImages.Length > 0) { Console.WriteLine("High res image: {0}", qvStatus.CapturedData.HighResImages[0].Url); } } Console.WriteLine("\n\nPress any key to terminate"); Console.ReadKey(true); } } }


9 Appendix C – C# .Net code samples

SampleprojectswerecreatedusingVisualStudio2010andtheytarget.NETFramework4ClientProfile.ThesesamplesshouldworkfinewithlowerversionsofVisualStudioand.NETFrameworkaswell.

SamplestakeadvantageoftheQubeVuServiceproxyclass.Thesourcecodeforthisclassisprovided,butitcanalsobegeneratedautomaticallybasedontheWSDLfileforQubeVuService(inSDK_root\wsdl\QubeVuService.wsdl)usingthewsdl.exetool.Thewsdl.exetoolispartofmostrecentversionsofVisualStudioinstallations.

Mostsampleprojectsassumethatthedeviceisrunningat169.254.1.1IPaddress.

9.1 Dim101

Basicdemo.ConnectstoQubeVu,pollsforstatusonce,displaysdimensions,imageURLs.(SameasAppendixB–Sample.Netclientcode.)

9.2 Dim102

Expandsonthepreviousprojectbyaddingextendedstatusmonitoring,reportscaptureid,andcapturedefinitionname.Infinitelooppollsforstatusupdatescontinuously.

9.3 Dim103

Expandsonthepreviousprojectbyaddingbarcoderecognition.Thissamplealsohasaddedfunctionalityforsavingofallofthelowresolutionimages,also,savingthepointcoordinatesforfacesinwireframemodelofthescannedobject.

9.4 Dim104

Sampledemonstrateshowtoextractandsavearotatedandcroppedhighresolutionimageofthescannedobject.Itretainsbarcoderecognitionfunctionalityfromtheprevioussample,butdoesnotsavelowresolutionimagesorwireframedata.

9.5 ExternalTrigger

Demonstrateshowtotriggerascanviathe"Capture"APIcall.Alsoshowshowtocreateacapturedefinitionwhichenablesbarcoderecognitiononthedeviceitself(noneedforbarcoderecognitionlibraryonclientside).

YoumayrunDim102and/orDim103whilerunningExternalTriggeratthesametime.Whenyoupressanykeytotriggerascan/captureinExternalTriggeryoushouldobservetheotherwindowsreportingthestatusofthedeviceaccordingly.


9.6 Barcodes

DemonstratestheuseoftheQubeVuBarcodesAPI.dll1Dbarcoderecognitionlibrary.

9.7 Barcodes2D

DemonstratestheuseofthePostea.QubeVu2DBCRecognition.dll2Dbarcoderecognitionlibrary.

9.8 Barcodes2D_Dtk

DemonstratestheuseofthePostea.QubeVu2DBCRecognition.dll2DbarcoderecognitionlibrarywithDTKbarcodereaderintegration.

9.9 Barcodes2D_Dtk_with_key

DemonstratestheuseofthePostea.QubeVu2DBCRecognition.dll2DbarcoderecognitionlibrarywithDTKbarcodereaderintegration.ThisversionhardcodesaDTKdeveloperlicensekey,whichallowsfullfunctionalityonPCswhereaDTKruntimelicensehasbeenactivated.DuetoDTK’slicensingrestrictionsonlythecompiledbinaryisdistributedinthesamples\binfolder.

9.10 ImageConversion

ExpandsonDim102sampleproject.Retrievesdimensions,highresolutionimageandsavesitinbothitsoriginalformat(optional)aswellasarasterizedblackandwhiteTIFFimageforreducedsize.


10 Appendix D – Sample HTTP Dialog

10.1 QubeVu Status Query

10.1.1 Request (Internet Explorer 11, using Ajax polling in web page)

POST /WebServices/QubeVuService/Status HTTP/1.1 X-Requested-With: XMLHttpRequest Referer: http://192.168.2.55/ Accept-Language: en-US,en;q=0.5 Accept-Encoding: gzip, deflate User-Agent: Mozilla/5.0 (Windows NT 10.0; WOW64; Trident/7.0; Touch; rv:11.0) like Gecko Content-Length: 0 Host: 192.168.2.55 Connection: Keep-Alive Pragma: no-cache Cookie: PHPSESSID=40rieamst0noou978pqn4v0np4

10.1.2 “Ready to Scan” Response from QubeVu (white-space added to body for readability)

HTTP/1.1 200 OK Date: Mon, 22 Aug 2016 15:04:57 GMT Server: Apache/2.4.7 (Ubuntu) Last-Modified: Mon, 22 Aug 2016 15:04:57 GMT ETag: W/"326-53aaa5f1a4397-gzip" Accept-Ranges: bytes Vary: Accept-Encoding Access-Control-Allow-Origin: * Cache-Control: no-store,no-cache Expires: 0 Content-Length: 806 Keep-Alive: timeout=5, max=49 Connection: Keep-Alive Content-Type: text/xml; charset=utf-8 <?xml version="1.0" encoding="utf-8"?> <QVStatus Status="READY" CaptureId="226128" ExtendedStatus="UnsupportedFlatItem,ItemOutOfBounds" xmlns="http://postea.com/WebServices/QubeVu" OutOfBounds="10"> <DateTime>2016-08-22 11:04:57 -0400</DateTime> <Error Code="0" Message=""/> <LiveData TrackingId="1702756"> <TrackerImage Name="LowRes" Url="/Results/peekimages/16_1702756/TrackerImagePeek.bmp"/> </LiveData> <CapturedData CaptureDefinitionName="" CaptureId="226128"> <DateTime>2016-08-22 11:04:57 -0400</DateTime> <Weight>0</Weight> <ScaleData Name=""> <Weight>0</Weight> <ScaleFactor>0</ScaleFactor> <WeightUnit/> <RawData/> <DisplayWeight/> <IsStable>true</IsStable> </ScaleData> <Dimensions Irregular="false" Undersize="0" Oversize="0" Refinement="0" DimUnit="mm" OutOfBounds="0" UnknownDimensions="true" UnknownDimensionsReason="Unknown"> <Length>0</Length> <Width>0</Width> <Height>0</Height> </Dimensions> </CapturedData> <Crc>0x0ec8d78c</Crc> </QVStatus>


10.1.3 “Item Scanned” Sample Response from QubeVu

HTTP/1.1 200 OK Date: Mon, 23 Jan 2017 22:32:02 GMT Server: Apache/2.4.7 (Ubuntu) Last-Modified: Mon, 23 Jan 2017 22:32:02 GMT ETag: W/"5a4-53aaa9da45580-gzip" Accept-Ranges: bytes Vary: Accept-Encoding Access-Control-Allow-Origin: * Cache-Control: no-store,no-cache Expires: 0 Content-Length: 3895 Keep-Alive: timeout=5, max=91 Connection: Keep-Alive Content-Type: text/xml; charset=utf-8 <?xml version="1.0" encoding="utf-8"?> <QVStatus Status="REMOVE" CaptureId="51" ExtendedStatus="ItemDetected" xmlns="http://postea.com/WebServices/QubeVu" OutOfBounds="0"> <DateTime>2017-01-23 17:39:09 -0500</DateTime> <Error Code="0" Message=""/> <CapturedData CaptureDefinitionName="QVDemo" CaptureId="51"> <DateTime>2017-01-23 17:39:02 -0500</DateTime> <Weight>0</Weight> <ScaleData Name=""> <Weight>0</Weight> <ScaleFactor>0</ScaleFactor> <WeightUnit/> <RawData/> <DisplayWeight/> <IsStable>true</IsStable> </ScaleData> <Dimensions Irregular="false" Undersize="2" Oversize="0" Refinement="15" DimUnit="mm" OutOfBounds="0" UnknownDimensions="false" UnknownDimensionsReason=""> <Length>180</Length> <Width>80</Width> <Height>255</Height> </Dimensions> <RawDimensions DimUnit="mm"> <Length>179.5</Length> <Width>80.8</Width> <Height>255.4</Height> </RawDimensions> <TrackerImage Url="/Results/QVTrackerImage.bmp" Name=""> <ItemRect> <CenterX>153</CenterX> <CenterY>154</CenterY> <D1>38</D1> <D2>20</D2> <Theta>1.001886</Theta> </ItemRect> <ItemWireFrame> <Faces> <Face Visible="true"> <Vertices> <Point> <X>151</X><Y>134</Y> </Point> <Point> <X>136</X><Y>143</Y> </Point> <Point> <X>141</X><Y>138</Y> </Point> <Point> <X>153</X><Y>131</Y> </Point>


</Vertices> </Face> <Face Visible="false"> <Vertices> <Point> <X>157</X><Y>165</Y> </Point> <Point> <X>169</X><Y>158</Y> </Point> <Point> <X>153</X><Y>131</Y> </Point> <Point> <X>141</X><Y>138</Y> </Point> </Vertices> </Face> <Face Visible="true"> <Vertices> <Point> <X>151</X><Y>134</Y> </Point> <Point> <X>153</X><Y>131</Y> </Point> <Point> <X>169</X><Y>158</Y> </Point> <Point> <X>170</X><Y>166</Y> </Point> </Vertices> </Face> <Face Visible="false"> <Vertices> <Point> <X>157</X><Y>165</Y> </Point> <Point> <X>141</X><Y>138</Y> </Point> <Point> <X>136</X><Y>143</Y> </Point> <Point> <X>156</X><Y>175</Y> </Point> </Vertices> </Face> <Face Visible="true"> <Vertices> <Point> <X>151</X><Y>134</Y> </Point> <Point> <X>170</X><Y>166</Y> </Point> <Point> <X>156</X><Y>175</Y> </Point> <Point> <X>136</X><Y>143</Y> </Point> </Vertices> </Face> <Face Visible="false"> <Vertices> <Point>


</Point> <Point> <X>340</X><Y>332</Y> </Point> </Vertices> </Face> <Face Visible="false"> <Vertices> <Point> <X>314</X><Y>330</Y> </Point> <Point> <X>282</X><Y>276</Y> </Point> <Point> <X>272</X><Y>286</Y> </Point> <Point> <X>312</X><Y>350</Y> </Point> </Vertices> </Face> <Face Visible="true"> <Vertices> <Point> <X>302</X><Y>268</Y> </Point> <Point> <X>340</X><Y>332</Y> </Point> <Point> <X>312</X><Y>350</Y> </Point> <Point> <X>272</X><Y>286</Y> </Point> </Vertices> </Face> <Face Visible="false"> <Vertices> <Point> <X>314</X><Y>330</Y> </Point> <Point> <X>312</X><Y>350</Y> </Point> <Point> <X>340</X><Y>332</Y> </Point> <Point> <X>338</X><Y>316</Y> </Point> </Vertices> </Face> </Faces> </ItemWireFrame> </LowResImage> </LowResImages> <HighResImages> <HighResImage Url="/Results/QVHighResImage.bmp" Name="HighResImage1"> <ItemRect> <CenterX>1576</CenterX> <CenterY>1996</CenterY> <D1>1410</D1> <D2>635</D2> <Theta>0.928244</Theta> </ItemRect> <Barcodes/> </HighResImage>


</HighResImages> </CapturedData> <Crc>0x5cbc8786</Crc> </QVStatus>


11 Appendix E – Universal Windows Platform Sample (C#)

AUWPsampleprojectisincludedintheSDK.ThissampleprojecthasbeentestedwiththelatestavailableWindowsIoTOS(atthetimeofthiswriting)onRaspberryPi3hardware.DevelopmentofUWPappsrequirethelatestVisualStudio2015(Update2atthetimeofthiswriting)aswellastheWindows10SDK.

ThesampletakesadvantageoftheQubeVuServiceproxyclass(QubeVuServiceAsyncClient.cs).Thisisadifferentproxyclassthanwhatisdiscussedintheprevioussection.TheasynchronousC#proxyclassisavailableforusewithWindowsStoreappsandUniversalWindowsPlatformdevelopmentprojects(including,butnotlimitedtoWindowsIoTprojects).ThisclassusesthenewerWindows.Web.HttpnamespaceinfavouroftheolderSystem.Net.Httpnamespace,whilealsoprovidingonlyawaitablemethodsforAPIcalls.ThisclassmustbeusedinconjunctionwiththecodefilecontainingalltheQubeVuServicetypedefinitions(QubeVuServiceTypes.cs)whichhasbeenautomaticallygeneratedfromtheWSDLfile.BothfilescanbefoundinSDK_root\common\srcfolder.

TheUWPsamplefolderalsocontainscompiledapppackagesforIntelandARMarchitecturesaswellasinstructionsonhowtosideloadtheapponWindows10desktop/tableeditions.TheREADMEfilehasinstructionsonhowtodeploythecompiledARMapppackageonRaspberryPi2/3.

11.1 Dim101

Basicdemo.ConnectstoQubeVu,pollsforstatus,displaysdimensions.


12 Appendix F – QubeVuBarcodes Client API

ThebarcodelibraryisimplementedasaWindowsDLLQubeVuBarcodesAPI.dll(Linuxversionisavailableonrequest)andexposesthefollowingfourfunctions:CreateReader,CreateReaderMT,DestroyReaderandRecognizeBarcode.FunctionsignaturesandnecessarysupportingstructuresaredefinedinQubeVuBarcodesAPI.csfileintheSDK.

QubeVuBarcodesAPI.dlldependsonlibiomp5md.dllwhichislocatedinthe<SDKroot>\common\binfolder.AnyclientapplicationconsumingQubeVuBarcodesAPI.dllmusthavethisdependentlibrarypresentinthesamefolderwheretheexecutableresides.

12.1 Function Reference

CreateReader

Createsanewinstanceofthebarcodereaderengineandreturnsahandletoit.

CreateReaderMT

Createsanewinstanceofthebarcodereaderengineandreturnsahandletoit.Thisfunctionletscallersspecifythenumberofthreadsthelibraryshouldusetorecognizebarcodesaswellasthenumberofpicturesegmentseachthreadwillprocess.Callingthisfunctionwith1/1forthreadsandparts-per-threadvaluesisanaliastoCreateReaderfunctionabove.

DestroyReader

Destroysthespecifiedreaderandfreesanymemoryassociatewithit.

RecognizeBarcode

Scansthespecifiedimageforbarcodes.


13 Appendix G – Postea.QubeVu2DBCRecognition Client API

The2DbarcodelibraryisimplementedasaWindowsDLLPostea.QubeVu2DBCRecognition.dll(Linuxversionisavailableonrequest)andexposestheBarcodeRecognizer2DandBarcodeRecognizer2D_DTKclassesandtheirReadImagefunction.DetailedfunctionsignaturesandnecessarysupportingstructuresarealsoexposedthroughclassmetadatawhichcanbeviewedinVisualStudioIDE.

TheuseofBarcodeRecognizer2D_DTKclassrequiresthatyouhaveavaliddeveloperlicenceandthatyoupassittotheclassintheconstructor.ConsumersoftheapprelyingonthisclassmayrequirethatthePCwherethefinalappisdeployedhasanactiveDTKruntimelicensedependingontheDTKlicensingmodelused(limitedvs.unlimiteddeveloperlicensetypepassedtoBarcodeRecognizer2D_DTKclass).

13.1 BarcodeRecognizer2D Class Function Reference

BarcodeRecognizer2D(bcTypes2D)

Createsanewinstanceofthe2Dbarcodereaderengineandreturnsahandletoit.bcTypes2Disabitflagenumerationtypecorrespondingtotheavailabletypesof2Dbarcodesthelibrarysupports.Whenthebarcodetypeparameterisomittedallavailablebarcodetypeswillberecognized.

ReadImage(Image)

Recognizes2Dbarcodesintheimagepassedtothefunction.Returnsacollectionofbarcoderecognitions.

13.2 BarcodeRecognizer2D_DTK Class Reference

TheuseofBarcodeRecognizer2D_DTKclassrequiresthatyouhaveavaliddeveloperlicencewhichyoupasstotheconstructor.Forunlimitedlicensingthecorrespondingunlimitedruntimeorserverlicensekeymustalsobespecified.Forlimitedlicensingmodeltheunlimitedruntime/serverlicenseparametermustbespecifiedasanemptystring.ConsumersoftheapprelyingonthisclassmayrequirethatthePCwherethefinalappisdeployedhasanactiveDTKruntimelicensedependingontheDTKlicensingmodelused(basedonifunlimitedlicensetypepassedtoBarcodeRecognizer2D_DTKclassornot).

BarcodeRecognizer2D_DTK(dtkDeveloperLicenseKey)

Createsanewinstanceofthe2Dbarcodereaderengine(wrappingtheDTKbarcodereaderengine)andreturnsahandletoit.Allsupported2Dbarcodetypeswillberecognized.

Ifavaliddeveloperkeyisused,buttheDTKcomponentisnotlicensed(e.g.lackofruntimelicenseactivationetc.),allconstructorsofthisclasswillthrowLicenseExceptiontypeexception.

BesuretocallDisposemethodontheBarcodeRecognizer2D_DTKobjectinstanceattheendofyourcodeblock,oremployausingblocktoadheretotheIDisposablepattern.

Usingthisformoftheconstructorisonlycompatiblewithlimitedlicensingmodel.


BarcodeRecognizer2D_DTK(dtkDeveloperLicenseKey, dtkRuntimeLicenseKey)

Createsanewinstanceofthe2Dbarcodereaderenginesimilarlyasdescribedabove.UsethisconstructorwiththeunlimitedDTKlicensingmodel.Ifthesecondparameterisanemptystring,thenthefirstparameterwillbetreatedasadeveloperlicenseusedforlimitedlicensingmodel.

BarcodeRecognizer2D_DTK(dtkDeveloperLicenseKey, dtkRuntimeLicenseKey, bcTypes2D)

Createsanewinstanceofthe2Dbarcodereaderenginesimilarlyasdescribedabove.bcTypes2Disabitflagenumerationtypecorrespondingtotheavailabletypesof2Dbarcodesthelibrarysupports.

BarcodeRecognizer2D_DTK(dtkDeveloperLicenseKey, dtkRuntimeLicenseKey, barcodeSettingsXml)

Createsanewinstanceofthe2Dbarcodereaderenginesimilarlyasdescribedabove.barcodeSettingsXmlparameterisanXMLstringcontainingDTK-specificsettings.ItcanbeusedwhenyouwanttoapplyDTK-libraryspecificsettingswhilecreatingthebarcodereader.UseGetSettingsXmlStringfunctiontogenerateXMLsettingsstringofthecurrentBarcodeRecognizer2D_DTKinstance.

ReadImage(Image)

Recognizes2Dbarcodesintheimagepassedtothefunction.Returnsacollectionofbarcoderecognitions.

IsDtkLicensed

ReturnstrueifDTKcomponenthasbeenlicensed(andactivatedonthelocalPC,ifapplicable),falseotherwise.NoexceptionisthrownwhenDTKcomponentisunlicensed.

GetSettingsXmlString()

HelperfunctionwhichextractstheDTK-specificsettingsfromthecurrentinstanceoftheclassandreturnsitasanXMLstring.Youmayusethismethodtopersistconfigurationtodiskand/ormodifyitandthenloaditbackpassingittotheappropriateconstructor.

DtkBarcodeToBarcodeInfo(DTKBarReader.Barcode)

HelperfunctiontohelpconvertDTK-specificbarcodedatatobarcodedatacompatiblewithPostea.QubeVu2DBCRecognitionlibrary.ThismethodmaybeusedwiththeDTKSDKtoallowcompatibilitybetweentheresultsreturnedbyDTK’smanyReadFrommethods.

13.3 DTK XML Settings String

DTK XML settings

ThefullrangeofDTKbarcodereadersettingsareexposedthroughthebarcodeSettingsXml parameterofthe BarcodeRecognizer2D_DTK constructor.ThefollowingsectionisonlyanexcerptfromthefullDTKSDKdocumentation.Forthecompletelistofavailablesettings,includingavailablebarcodetypeswhichcanberecognizedbytheDTKlibrary,pleaserefertotheDTKSDKdocumentation.

XMLsettingelement Description


ThresholdStep Thestepofthethresholdvalueforthe'Multiple'thresholdmode.

ThresholdMode Imagethresholdingmode:TM_Adaptive,TM_Automatic,TM_FixedorTM_Multiple.

ThresholdCount Thenumberofthethresholdvaluesforthe'Multiple'thresholdmode.

Threshold Thecolorthresholdlevelfordistinguishingofthebackgroundandforegroundpixels.

ScanPage Thepagenumberforbarcoderecognition(formultipageimagesonly).

ScanInterval Thescanningintervalforrecognition(inpixels).Possiblevaluesarefrom1to10.

Code39NoStartStop SpecifieswhethertheCode39barcodehavenotstartandstopsymbols'*'(asterisk).ThedefaultvalueisFalse.

QRCodeRequiredECCLevel ThevaluethatspecifiestherequirederrorcorrectionlevelforQRcodes(0..3).Defaultvalue-1(allECClevels).

QuietZoneSize Getsorsetstheexpectedsizeofthe'quietzone'ofthebarcode.

PDFPassword Theparameterdefinesthepasswordwhichwillbeusedtoopenpassword-protectedPDFdocuments.

PDFRenderDPI TheparameterdefinesDPI(dotperinch)forPDFfilesrendering.

PDFReadingType ThetypeofthePDFdocumentsreading.

ImageSharp Specifieswhetherthesharpeningoperationmustbeexecutedbeforerecognition.(validvaluesare0or4)

ImageInvert Specifieswhethertheimageinversionisrequiredbeforerecognition.(validvaluesare0or5)

ImageErode Specifieswhetherthemorphologicaloperation'Erosion'mustbeexecutedbeforerecognition.(validvaluesare0or2)

ImageDilate Specifieswhetherthemorphologicaloperation'Dilation'mustbeexecutedbeforerecognition.(validvaluesare0or3)

ImageDespeckle SpecifieswhetherthemorphologicaloperationDespecklemustbeexecutedbeforerecognition.(validvaluesare0or1)

ConvertUPCEtoUPCA SpecifieswhethertheUPC-EbarcodemustbeconvertedtoUPC-Aformat.

I2of5Checksum Specifieswhetherthechecksumvalidationisrequiredfor2of5Interleavedbarcodes.

Code93Checksum SpecifieswhetherthechecksumvalidationisrequiredforCode93barcodes.

Code39Checksum SpecifieswhetherthechecksumvalidationisrequiredforCode


39barcodes.

Code11Checksum SpecifieswhetherthechecksumvalidationisrequiredforCode11barcodes.

BarcodeTypes Thebarcodetypesdefinedforrecognition.E.g.BT_All, BT_All_1D, BT_All_2D, BT_Code128, BT_PDF417,etc.Forthecompletelistofavailablebarcodetypes,pleaserefertotheDTKSDKdocumentation.

RecognitionTimeout Thevaluethatspecifiestheamountoftime(inmilliseconds)afterwhichthebarcoderecognitionwillbestopped.(0meansunlimitedtime)

BarcodesToRead Thenumberofexpectedbarcodes.

BarcodeOrientation Expectedorientationofthebarcode.E.g.BO_AllorBO_LeftToRight,etc.

ScanRectangle Scanningrectangleforbarcoderecognition.Mustfollowtheformat{X=0,Y=0,Width=0,Height=0}where0-sshouldbereplacedbytheappropriateclippingparametersinpixels.

DTK XML settings sample

<?xml version="1.0" encoding="utf-8"?> <BarcodeReader> <ThresholdStep>16</ThresholdStep> <ThresholdMode>TM_Multiple</ThresholdMode> <ThresholdCount>4</ThresholdCount> <Threshold>128</Threshold> <ScanPage>0</ScanPage> <ScanInterval>5</ScanInterval> <Code39NoStartStop>False</Code39NoStartStop> <QRCodeRequiredECCLevel>-1</QRCodeRequiredECCLevel> <QuietZoneSize>QZ_Normal</QuietZoneSize> <PDFPassword></PDFPassword> <PDFRenderDPI>300</PDFRenderDPI> <PDFReadingType>PDF_Images</PDFReadingType> <ImageSharp>4</ImageSharp> <ImageInvert>0</ImageInvert> <ImageErode>0</ImageErode> <ImageDilate>0</ImageDilate> <ImageDespeckle>0</ImageDespeckle> <ConvertUPCEtoUPCA>False</ConvertUPCEtoUPCA> <I2of5Checksum>False</I2of5Checksum> <Code93Checksum>False</Code93Checksum> <Code39Checksum>False</Code39Checksum> <Code11Checksum>False</Code11Checksum> <BarcodeTypes>BT_PDF417</BarcodeTypes> <RecognitionTimeout>0</RecognitionTimeout> <BarcodesToRead>1</BarcodesToRead> <BarcodeOrientation>15</BarcodeOrientation> <ScanRectangle>{X=0,Y=0,Width=0,Height=0}</ScanRectangle> </BarcodeReader>


14 Appendix H – Supported barcodes

ThefollowingbarcodetypesaresupportedbyQubeVu:

EAN13, CODE128, CODE39, CODE93, EAN8, UPCE, UPCX, INT25, CODABAR, PATCHCODE

Thefollowing2Dbarcodetypesaresupported:

DATAMATRIX, QR, PDF417


15 Appendix I – ItemRect illustration


16 Appendix J – ItemWireFrame sample

TheimagebelowcorrespondstothestatusXMLsampleinSection9.1.3.TheimageshownistheTrackerImagewitharesolutionof320x240pixels.Thesampleobjecthas3visibleand3invisiblesides.Visiblesideshavebeendrawnwiththicksolidbluelines,whileinvisiblefacetsaredrawnwiththinnerdashedlines.

qubevu developer guide v1.0qubevu.com/products/documentation/qubevu developer guide.pdf · qubevu...

Documents