Ugi Class Reference

Overview

Singleton class that implements the U Grok It API.

The Ugi class is used as a singleton - only one instance of the class exists.

The singleton object should be explicitly created by calling createSingleton.

Class Methods
(void)	+ createSingleton
	Create the singleton object with the default configuration handler, This is usually done in your application delegate's didFinishLaunchingWithOptions: method or in main.c
(void)	+ createSingletonWithConfigurationDelegate:
	Create the singleton object with a specific configuration handler This is usually done in your application delegate's didFinishLaunchingWithOptions: method or in main.c More...
(Ugi *_Nonnull)	+ singleton
	Get the singleton object. More...
(void)	+ releaseSingleton
	Release the singleton object. More...
(BOOL)	+ isTablet
	See if this iOS device is a tablet More...
(void)	+ debug_setIsTablet:
	Set the isTablet property. More...

Instance Methods
(void)	- checkMicPermission:
	See if the application has microphone permission. More...
(UIInterfaceOrientationMask)	- supportedInterfaceOrientationsWithAllowRotationOnTablet:
	Get the preferred orientation More...
(NSString *_Nonnull)	- localizedRegionNameForName:
	Get the localized region name for an unlocalized region name More...
(nonnull id)	- reportConnectionStateAndBatteryInfoPeriodically:
	Periodically report connection state and battery information to the callback. More...
(void)	- endReportConnectionStateAndBatteryInfoPeriodically:
	End periodic connection state and battery info reports. More...
(void)	- debug_setBatteryPercentageAdjustment:withCompletion:
	Set an adjustment to the battery percentage (the adjustment value is added to or subtracted from the real battery percentage). More...
(void)	- debug_setTemperatureAdjustment:withCompletion:
	Set an adjustment to the battery temperature (the adjustment value is added to the real temperature). More...
(BOOL)	- barcodeScanWithConfiguration:withCompletion:
	Scan for a barcode More...
(void)	- cancelBarcodeScan
	Cancel barcode scan
(void)	- repromptForAutomaticFirmwareUpdateIfAvailable [implementation]
	If an automatic firmware update is available, reprompt for it (via the configuration delegate)
(void)	- automaticCheckForFirmwareUpdateWithCompletion: [implementation]
	Check for firmware update automatically. More...
(void)	- forceFirmwareChannelReload: [implementation]
	Update the firmware update status (reload the control file). More...
(BOOL)	- forceFirmwareGrokkerCheck [implementation]
	Check the grokker for firmware update More...
(void)	- loadUpdateWithName:withHfName:withCompletion: [implementation]
	Load an update. More...
(void)	- cancelFirmwareUpdate [implementation]
	Cancel an update in progress
(void)	- loadUpdatesFromChannel:withCheckCompatibility:withCompletion: [implementation]
	Load updates (metadata) More...
(void)	- updateFirmwareInfoCompatibility: [implementation]
	After firmware has been updated, update an array of UgiFirmwareUpdateInfo objects More...
(BOOL)	- isUpdateInProgress [implementation]
	See if an update is in progress More...
(BOOL)	- isUpdateRequired [implementation]
	See if an update is required More...
(void)	- requiresFirmwareVersion: [implementation]
	Set that this app requires a minimum firmware version on the Grokker More...
(void)	- firmwareUpdateWithAllowDowngrade:withProgressCompletion:withCompletion: [implementation]
	Update firmware that has been previously loaded with loadUpdateWithName: More...
Connection
(void)	- openConnection
	Try to open a connection to the reader. More...
(void)	- closeConnection
	Close connection to the reader. More...
Configuration
(BOOL)	- getGeigerCounterSound:
	Get the current geiger counter sound configuration More...
(void)	- setGeigerCounterSound:
	Set the geiger counter sound configuration More...
(UgiSpeakerTone *_Nonnull)	- getFoundItemSound
	Get the current set of tones played when an item is found More...
(void)	- setFoundItemSound:
	Set the set of tones played when an item is found More...
(UgiSpeakerTone *_Nonnull)	- getFoundLastItemSound
	Get the current set of tones played when the last item is found More...
(void)	- setFoundLastItemSound:
	Set the set of tones played when the last item is found More...

Properties
NSObject< UgiConfigurationDelegate > *	configurationDelegate
	Delegate to handle configuration events.
NSString *	FIRMWARE_CHANNEL_RELEASE [implementation]
	Name of release channel.
NSString *	FIRMWARE_CHANNEL_DEVELOPMENT [implementation]
	Name of development channel.
NSString *	automaticFirmwareUpdateChannel [implementation]
	Name of channel for automatic updates (normally FIRMWARE_CHANNEL_RELEASE)
BOOL	debug_forceFirmwareUpdateToPreviousVersion [implementation]
	DEBUGGING - cause the firmware update code to update to the previous version.
Reader Information Properties
int	requiredProtocolVersion
	Protocol version that the host requires.
int	supportedProtocolVersion
	Protocol version that the host supports.
int	readerProtocolVersion
	Reader protocol version.
NSString *	readerHardwareModel
	Reader's model.
UgiReaderHardwareTypes	readerHardwareType
	Reader's hardware type.
int	readerHardwareRevision
	Reader's hardware version.
int	firmwareVersionMajor
	Firmware version in the reader, major.
int	firmwareVersionMinor
	Firmware version in the reader, minor.
int	firmwareVersionBuild
	Firmware version in the reader, build.
int	readerSerialNumber
	Reader's serial number.
NSString *	unlocalizedRegionName
	name of region of the world, not localized
int	maxTonesInSound
	Maximum number of tones in a sound.
double	maxPower
	Maximum power that the reader can use.
int	maxSensitivity
	Maximum sensitivity.
int	numVolumeLevels
	Maximum number of volume levels.
BOOL	hasBattery
	YES if the reader has battery power.
int	batteryCapacity
	Battery capacity in minutes.
int	batteryCapacity_mAh
	Battery capacity in mAh.
BOOL	deviceInitializedSuccessfully
	YES if device initialized successfully.
NSString *	readerDescription
	Description of the reader, generally used for debugging.
SDK Version Properties
int	sdkVersionMajor
	SDK Version, major More...
int	sdkVersionMinor
	SDK Version, minor.
int	sdkVersionBuild
	SDK Version, minor.
NSDate *	sdkVersionDateTime
	SDK Version, date/time.

Structures
struct	UgiGeigerCounterSound
	Geiger counter sound configuration, used by getGeigerCounterSound and setGeigerCounterSound More...
struct	UgiSpeakerTone
	A single tone, used by setFoundItemSound and setFoundLastItemSound More...

Types
enum	UgiOngoingOperations {   UGI_ONGOING_OPERATION_INACTIVE, UGI_ONGOING_OPERATION_INVENTORY, UGI_ONGOING_OPERATION_FIRMWARE_UPDATE, UGI_ONGOING_OPERATION_OTHER,   UGI_ONGOING_OPERATION_BARCODE_SCAN }
	Operation used by ReportConnectionStateAndBatteryInfoCallback More...
enum	UgiFirmwareUpdateReturnValues {   UGI_FIRMWARE_UPDATE_SUCCESS = 0, UGI_FIRMWARE_UPDATE_NO_FILE = 100, UGI_FIRMWARE_UPDATE_BAD_FILE = 101, UGI_FIRMWARE_UPDATE_INCOMPATIBLE_HARDWARE = 102,   UGI_FIRMWARE_UPDATE_INCOMPATIBLE_VERSION = 103, UGI_FIRMWARE_UPDATE_CRC_MISMATCH = 3, UGI_FIRMWARE_UPDATE_PROTOCOL_FAILURE = 104, UGI_FIRMWARE_UPDATE_CANT_RECONNECT = 105,   UGI_FIRMWARE_UPDATE_CANCELLED = 106, UGI_FIRMWARE_UPDATE_BATTERY_TOO_LOW = 107 }
	Values returned from firmwareUpdate and sent with firmwareUpdateCompleted More...
typedef void(^	ReportConnectionStateAndBatteryInfoCallback) (UgiConnectionStates connectionState, UgiOngoingOperations ongoingOperation, BOOL batteryInformationIsValid, BOOL externalPowerIsConnected, BOOL isCharging, BOOL canScan, BOOL canGetBatteryWhileScanning, BOOL temperatureAtOrAboveThreshold, BOOL temperatureWithin5DegreesOfThreshold, BOOL temperatureWithin10DegreesOfThreshold, BOOL temperatureWithin20DegreesOfThreshold, int averagedBatteryPercentage, NSString *_Nonnull statusDescription)
	Callback function for reportBatteryInfoPeriodically More...
typedef void(^	BarcodeScanCompletion) (NSData *_Nullable barcode)
	Function definition for completion for barcodeScan:withCompletion:
typedef void(^	AutomaticCheckForFirmwareUpdateCompletion) (UgiFirmwareUpdateInfo *_Nullable info, BOOL required)
	Completion type for checkForUpdateOnConnect More...
typedef void(^	FirmwareUpdateProgressCompletion) (int amountDone, int amountTotal, BOOL canCancel)
	Function definition for completion for firmwareUpdate
typedef void(^	FirmwareUpdateCompletion) (UgiFirmwareUpdateReturnValues result, int seconds)
	Function definition for completion for firmwareUpdate
Connection Types
enum	UgiConnectionStates { UGI_CONNECTION_STATE_NOT_CONNECTED, UGI_CONNECTION_STATE_CONNECTING, UGI_CONNECTION_STATE_INCOMPATIBLE_READER, UGI_CONNECTION_STATE_CONNECTED }
	States for the connection, sent with [Ugi singleton].NOTIFICAION_NAME_CONNECTION_STATE_CHANGED More...
Reader Information Types
enum	UgiReaderHardwareTypes { UGI_READER_HARDWARE_UNKNOWN, UGI_READER_HARDWARE_GROKKER_1 =5 }
	Reader hardware type and version More...
Logging Types
enum	UgiLoggingTypes {   UGI_LOGGING_INTERNAL_BYTE_PROTOCOL = 0x1, UGI_LOGGING_INTERNAL_CONNECTION_ERRORS = 0x2, UGI_LOGGING_INTERNAL_CONNECTION_STATE = 0x4, UGI_LOGGING_INTERNAL_PACKET_PROTOCOL = 0x8,   UGI_LOGGING_INTERNAL_COMMAND = 0x10, UGI_LOGGING_INTERNAL_INVENTORY = 0x20, UGI_LOGGING_INTERNAL_FIRMWARE_UPDATE = 0x40, UGI_LOGGING_INTERNAL_BATTERY_STATUS = 0x80,   UGI_LOGGING_INTERNAL_PLATFORM_SPECIFIC = 0x100, UGI_LOGGING_STATE = 0x1000, UGI_LOGGING_INVENTORY = 0x2000, UGI_LOGGING_INVENTORY_DETAIL = 0x4000,   UGI_LOGGING_BATTERY_STATUS = 0x8000 }
	Types of logging. More...

Protected Types
typedef void(^	VoidBlock) (void)
	Generic completion type

Connection Properties
BOOL	inOpenConnection
	Has openConnection has been called (without a corresponding call to closeConnecion)
BOOL	isAnythingPluggedIntoAudioJack
	Is anything is plugged into the audio jack (as best we can determine)
NSString *	NOTIFICAION_NAME_CONNECTION_STATE_CHANGED
	Notification of connection state changed is sent to default NSNotificationCenter. More...
NSString *	NOTIFICAION_NAME_INVENTORY_STATE_CHANGED
	Notification of connection state changed is sent to default NSNotificationCenter. More...
UgiConnectionStates	connectionState
	The current connection state.
BOOL	isConnected
	Whether the reader is connected (returns YES if connectionState == UGI_CONNECTION_STATE_CONNECTED)
(nonnull id)	- addConnectionStateListener:
(void)	- removeConnectionStateListener:

Grokker password
enum	UgiGrokkerPasswordReturnValues {   UGI_GROKKER_PASSWORD_SUCCESS =0, UGI_GROKKER_PASSWORD_NOT_AUTHENTICATED =1, UGI_GROKKER_PASSWORD_WRONG_PASSWORD =2, UGI_GROKKER_PASSWORD_NO_PASSWORD_SET =3,   UGI_GROKKER_PASSWORD_NOT_CONNECTED =4, UGI_GROKKER_PASSWORD_OTHER_ERROR =5 }
	Values returned by setGrokkerPassword and authenticateGrokker More...
BOOL	grokkerAuthenticationRequired
	YES if the Grokker requires authentication.
BOOL	grokkerPasswordExists
	YES if the Grokker has a password.
(void)	- setGrokkerPassword:withCompletion:
	Set the Grokker's password. More...
(void)	- authenticateGrokker:withCompletion:
	Authenticate the Grokker. More...

Inventory
UgiInventory *	activeInventory
	Get the currently active inventory object (if any)
(UgiInventory *_Nonnull)	- startInventory:withConfiguration:withEpcs:
	Start running inventory (if a reader is connected). More...
(UgiInventory *_Nonnull)	- startInventoryIgnoringEpcs:withConfiguration:withEpcsToIgnore:
	Start running inventory (if a reader is connected). More...
(UgiInventory *_Nonnull)	- startInventory:withConfiguration:
	Start running inventory to find any tags More...
(UgiInventory *_Nonnull)	- startInventory:withConfiguration:withEpc:
	Start running inventory to find one specific tag More...
(nonnull id)	- addInventoryStateListener:
(void)	- removeInventoryStateListener:

Logging Properties
typedef void(^	UgiLoggingCallback) (NSString *_Nonnull string)
UgiLoggingTypes	loggingStatus
	The current logging status
BOOL	loggingTimestamp
	If YES, add a timestamp to each logging line (default = NO)
void	NS_NO_TAIL_CALL
(void)	+ setLoggingCallback:
	Set the logging callback More...
(void)	+ log:
	Log a string, either to NSLog or to the logging callback
(void)	- UgiLog
	Log a string, either to NSLog or to the logging callback

Instance Method Documentation

createSingletonWithConfigurationDelegate:()

+ (void) createSingletonWithConfigurationDelegate:

(nullable NSObject< UgiConfigurationDelegate > *)

configurationDelegate

Create the singleton object with a specific configuration handler This is usually done in your application delegate's didFinishLaunchingWithOptions: method or in main.c

Parameters

configurationDelegate

Delegate to use with singleton

singleton()

+ (Ugi * _Nonnull) singleton

Get the singleton object.

Returns

The one and only Ugi object, through which the application accesses the API.

releaseSingleton()

+ (void) releaseSingleton

Release the singleton object.

Normally called in applicationWillTerminate

checkMicPermission:()

- (void) checkMicPermission:

(nonnull void(^)(BOOL havePermission))

completion

See if the application has microphone permission.

This always returns YES prior to iOS7

Parameters

completion

Block called with permission status

isTablet()

+ (BOOL) isTablet

See if this iOS device is a tablet

Returns

isTablet YES if this iOS device is a tablet

debug_setIsTablet:()

+ (void) debug_setIsTablet:

(BOOL)

isTablet

Set the isTablet property.

This can be useful for debugging.

Parameters

isTablet

value to set

supportedInterfaceOrientationsWithAllowRotationOnTablet:()

- (UIInterfaceOrientationMask) supportedInterfaceOrientationsWithAllowRotationOnTablet:

(BOOL)

allowRotationOnTablet

Get the preferred orientation

Parameters

allowRotationOnTablet

YES to allow rotation on tablets

Returns

UIInterfaceOrientationMask to return in supportedInterfaceOrientations method

openConnection()

- (void) openConnection

Try to open a connection to the reader.

openConnection returns immediately, it does not wait for a connection to the reader to actually be established. If a reader is connected, the connection takes 400-500ms (just under half a second) for the connection sequence. Your app can get notification of connection state changes by registering with the default NotificationCenter with the name [Ugi singleton].NOTIFICAION_NAME_CONNECTION_STATE_CHANGED:

[[NSNotificationCenter defaultCenter] addObserver:self
selector:@selector(connectionStateChanged:)
name:[Ugi singleton].NOTIFICAION_NAME_CONNECTION_STATE_CHANGED
object:nil];

This method is normally called in applicationDidBecomeActive but may be called elsewhere if the app does not want to always be connected to the reader.

closeConnection()

- (void) closeConnection

Close connection to the reader.

This method is normally called in applicationWillTerminate.

setGrokkerPassword:withCompletion:()

- (void) setGrokkerPassword:		(NSString *_Nullable)	password
withCompletion:		(nonnull void(^)(UgiGrokkerPasswordReturnValues result))	completion

Set the Grokker's password.

if a password is set, then the Grokker must be authenticated before any operation that changes tag data.

Parameters

password	Password to set
completion	Code to run when operation is completed

authenticateGrokker:withCompletion:()

- (void) authenticateGrokker:		(NSString *_Nonnull)	password
withCompletion:		(nonnull void(^)(UgiGrokkerPasswordReturnValues result))	completion

Authenticate the Grokker.

Parameters

password	Password to authenticate with
completion	Code to run when operation is completed

startInventory:withConfiguration:withEpcs:()

- (UgiInventory * _Nonnull) startInventory:		(nonnull id< UgiInventoryDelegate >)	delegate
withConfiguration:		(UgiRfidConfiguration *_Nonnull)	configuration
withEpcs:		(NSArray< UgiEpc * > *_Nullable)	epcs

Start running inventory (if a reader is connected).

If one or more EPCs are passed in, only they will be reported back to the delegate If no EPCs are passed (epcs=nil, numEpcs=0) then all EPCs will be reported back to the delegate

If a small number of EPCs are passed (<=maxEpcsSentToReader), filtering is done on the reader and the reader plays sounds immediately (with no host interaction). Otherwise filtering is done on the host, and the host tells the reder when to play sounds which is slower.

The inventory code keeps a history for each tag. This history is the number of finds for each time interval. The default is to store history for 20 intervals of 500ms each. This default can be modified via properties: historyIntervalMSec and historyDepth.

Parameters

delegate	Delegate object to report back to
configuration	Configuration to use
epcs	EPCs to find, all other EPCs are ignored (or nil to find all EPCs)

Returns

UgiInventory object that will hold the results of this inventory

startInventoryIgnoringEpcs:withConfiguration:withEpcsToIgnore:()

- (UgiInventory * _Nonnull) startInventoryIgnoringEpcs:		(nonnull id< UgiInventoryDelegate >)	delegate
withConfiguration:		(UgiRfidConfiguration *_Nonnull)	configuration
withEpcsToIgnore:		(NSArray< UgiEpc * > *_Nonnull)	epcsToIgnore

Start running inventory (if a reader is connected).

If one or more EPCs are passed in, ignore these EPCs

Parameters

delegate	Delegate object to report back to
configuration	Configuration to use
epcsToIgnore	EPCs to ignore

Returns

UgiInventory object that will hold the results of this inventory

startInventory:withConfiguration:()

- (UgiInventory * _Nonnull) startInventory:		(nonnull id< UgiInventoryDelegate >)	delegate
withConfiguration:		(UgiRfidConfiguration *_Nonnull)	configuration

Start running inventory to find any tags

Parameters

delegate	Delegate object to report back to
configuration	Configuration to use

Returns

UgiInventory object that will hold the results of this inventory

startInventory:withConfiguration:withEpc:()

- (UgiInventory * _Nonnull) startInventory:		(nonnull id< UgiInventoryDelegate >)	delegate
withConfiguration:		(UgiRfidConfiguration *_Nonnull)	configuration
withEpc:		(UgiEpc *_Nonnull)	epc

Start running inventory to find one specific tag

Parameters

delegate	Delegate object to report back to
configuration	Configuration to use
epc	EPC to find, all other EPCs are ignored

Returns

UgiInventory object that will hold the results of this inventory

localizedRegionNameForName:()

- (NSString * _Nonnull) localizedRegionNameForName:

(NSString *_Nonnull)

unlocalizedRegionName

Get the localized region name for an unlocalized region name

Parameters

unlocalizedRegionName

unlocalized region name

Returns

localized region name

getGeigerCounterSound:()

- (BOOL) getGeigerCounterSound:

(UgiGeigerCounterSound *_Nonnull)

config

Get the current geiger counter sound configuration

This configuration is used if UGI_INVENTORY_SOUNDS_GEIGER_COUNTER is passed to startInventory

Parameters

config

Buffer to fill

Returns

YES if successful, NO if reader has never been connected)

setGeigerCounterSound:()

- (void) setGeigerCounterSound:

(UgiGeigerCounterSound *_Nonnull)

config

Set the geiger counter sound configuration

This configuration is used if UGI_INVENTORY_SOUNDS_GEIGER_COUNTER is passed to startInventory

If no reader is connected, the reader will be configured with these parameters after a connection is established. Similiarly, if the reader is disconnected and reconncted, these parameters will be configured with these parameters.

Parameters

config

Configuration parameters to set

getFoundItemSound()

- (UgiSpeakerTone * _Nonnull) getFoundItemSound

Get the current set of tones played when an item is found

This sound is used if UGI_INVENTORY_SOUNDS_FIRST_FIND or UGI_INVENTORY_SOUNDS_FIRST_FIND_AND_LAST is passed to startInventory

Returns

A memory buffer containing an array of UgiSpeakerTone structures, ending in a structure with durationMsec==0. The caller must free() this bufffer. Returns NULL if a reader has never been connected

setFoundItemSound:()

- (void) setFoundItemSound:

(UgiSpeakerTone *_Nonnull)

sound

Set the set of tones played when an item is found

This sound is used if UGI_INVENTORY_SOUNDS_FIRST_FIND or UGI_INVENTORY_SOUNDS_FIRST_FIND_AND_LAST is passed to startInventory

If no reader is connected, the reader will be configured with these parameters after a connection is established. Similiarly, if the reader is disconnected and reconncted, these parameters will be configured with these parameters.

Parameters

sound

Array of UgiSpeakerTone structures, ending in a structure with durationMsec==0.

getFoundLastItemSound()

- (UgiSpeakerTone * _Nonnull) getFoundLastItemSound

Get the current set of tones played when the last item is found

This sound is used if UGI_INVENTORY_SOUNDS_FIRST_FIND_AND_LAST is passed to startInventory

Returns

A memory buffer containing an array of UgiSpeakerTone structures, ending in a structure with durationMsec==0. The caller must free() this bufffer. Returns NULL if a reader has never been connected

setFoundLastItemSound:()

- (void) setFoundLastItemSound:

(UgiSpeakerTone *_Nonnull)

sound

Set the set of tones played when the last item is found

This sound is used if UGI_INVENTORY_SOUNDS_FIRST_FIND_AND_LAST is passed to startInventory

If no reader is connected, the reader will be configured with these parameters after a connection is established. Similiarly, if the reader is disconnected and reconncted, these parameters will be configured with these parameters.

Parameters

sound

Array of UgiSpeakerTone structures, ending in a structure with durationMsec==0.

reportConnectionStateAndBatteryInfoPeriodically:()

- (nonnull id) reportConnectionStateAndBatteryInfoPeriodically:

(nonnull ReportConnectionStateAndBatteryInfoCallback)

callback

Periodically report connection state and battery information to the callback.

Parameters

callback

Callback function

Returns

id to pass to endReportConnectionStateAndBatteryInfoPeriodically

endReportConnectionStateAndBatteryInfoPeriodically:()

- (void) endReportConnectionStateAndBatteryInfoPeriodically:

(nonnull id)

idFromReportConnectionStateAndBatteryInfoPeriodically

End periodic connection state and battery info reports.

Parameters

idFromReportConnectionStateAndBatteryInfoPeriodically

id returned from reportConnectionStateAndBatteryInfoPeriodically

debug_setBatteryPercentageAdjustment:withCompletion:()

- (void) debug_setBatteryPercentageAdjustment:		(int)	adjustment
withCompletion:		(nonnull void(^)(BOOL success))	completion

Set an adjustment to the battery percentage (the adjustment value is added to or subtracted from the real battery percentage).

This is useful for development for testing displaying of different battery levels.

Parameters

adjustment	adjustment value
completion	Code to run afterwards

debug_setTemperatureAdjustment:withCompletion:()

- (void) debug_setTemperatureAdjustment:		(int)	adjustment
withCompletion:		(nonnull void(^)(BOOL success))	completion

Set an adjustment to the battery temperature (the adjustment value is added to the real temperature).

This is useful for development for testing hanlding of warnings when the Grokker is used in very hot environments.

Parameters

adjustment	adjustment value (must be positive or zero)
completion	Code to run afterwards

barcodeScanWithConfiguration:withCompletion:()

- (BOOL) barcodeScanWithConfiguration:		(nonnull UgiBarcodeConfiguration *)	configuration
withCompletion:		(nonnull BarcodeScanCompletion)	completion

Scan for a barcode

Parameters

configuration	Barcode configuration to use
completion	Code to run when barcode scan is completed

Returns

YES if scan started, NO if Grokker not connected, or Grokker dos not have a barcode reader

setLoggingCallback:()

+ (void) setLoggingCallback:

(nullable UgiLoggingCallback)

callback

Set the logging callback

By default logging goes to NSLog(), if a logging callback is set, it goes to this callback instead

Parameters

callback

Callback to send logging output to

automaticCheckForFirmwareUpdateWithCompletion:()

- (void) automaticCheckForFirmwareUpdateWithCompletion: (nonnull AutomaticCheckForFirmwareUpdateCompletion)  completion

implementation

Check for firmware update automatically.

The channel data is reloaded:

• when forceFirmwareChannelReload: is called
• on UIApplicationDidBecomeActiveNotification
• once a day The Grokker is checked for needing to be updated:
• each time a Grokker is connected
• whenever new channel data is loaded (and a Grokker is connected and not running inventory)
• when forceFirmwareGrokkerCheck: is called It is possible that a firmware update is available at a time that is inconveient for an update.

Parameters

completion

Completion code when an update is ready

forceFirmwareChannelReload:()

- (void) forceFirmwareChannelReload: (BOOL)  onlyIfSomeTimeHasPassed

implementation

Update the firmware update status (reload the control file).

Parameters

onlyIfSomeTimeHasPassed

YES to only force the check if time has passed since the last check

forceFirmwareGrokkerCheck()

- (BOOL) forceFirmwareGrokkerCheck

implementation

Check the grokker for firmware update

Returns

YES if a firmware update was initiated

loadUpdateWithName:withHfName:withCompletion:()

- (void) loadUpdateWithName: (NSString *_Nonnull)  name withHfName: (NSString *_Nullable)  hfName withCompletion: (nonnull void(^)(NSError *_Nullable error))  completion

implementation

Load an update.

The update is loaded into a file in the _UGrokItSDK directory Calback is called with YES if the update loaded successfully

Parameters

name	Update to load
hfName	HF update to load
completion	Completion called after the update has been loaded

loadUpdatesFromChannel:withCheckCompatibility:withCompletion:()

- (void) loadUpdatesFromChannel: (NSString *_Nonnull)  channel withCheckCompatibility: (BOOL)  checkCompatibilityWithConnectedGrokker withCompletion: (nonnull void(^)(NSMutableArray< UgiFirmwareUpdateInfo * > *_Nullable updates))  completion

implementation

Load updates (metadata)

Parameters

channel	Channel to load from, normally FIRMWARE_CHANNEL_RELEASE
checkCompatibilityWithConnectedGrokker	YES to check compatibility
completion	Completion code when updates are loaded

updateFirmwareInfoCompatibility:()

- (void) updateFirmwareInfoCompatibility: (NSMutableArray *_Nonnull)  updates

implementation

After firmware has been updated, update an array of UgiFirmwareUpdateInfo objects

Parameters

updates

Updates to update

isUpdateInProgress()

- (BOOL) isUpdateInProgress

implementation

See if an update is in progress

Returns

YES if an update is in progress

isUpdateRequired()

- (BOOL) isUpdateRequired

implementation

See if an update is required

Returns

YES if an update is required

requiresFirmwareVersion:()

- (void) requiresFirmwareVersion: (NSString *_Nullable)  firmwareVersion

implementation

Set that this app requires a minimum firmware version on the Grokker

Parameters

firmwareVersion

The minimum firmware version

firmwareUpdateWithAllowDowngrade:withProgressCompletion:withCompletion:()

- (void) firmwareUpdateWithAllowDowngrade: (BOOL)  allowDowngrade withProgressCompletion: (nonnull FirmwareUpdateProgressCompletion)  progressCompletion withCompletion: (nonnull FirmwareUpdateCompletion)  completion

implementation

Update firmware that has been previously loaded with loadUpdateWithName:

Parameters

allowDowngrade	YES to allow downgrading
progressCompletion	Code to run preiodically to update status
completion	Code to run when done

Property Documentation

NOTIFICAION_NAME_CONNECTION_STATE_CHANGED

- (NSString*) NOTIFICAION_NAME_CONNECTION_STATE_CHANGED

readnonatomicassign

Notification of connection state changed is sent to default NSNotificationCenter.

The object sent with the notification is an NSNumber containing the connection state.

NOTIFICAION_NAME_INVENTORY_STATE_CHANGED

- (NSString*) NOTIFICAION_NAME_INVENTORY_STATE_CHANGED

readnonatomicassign

Notification of connection state changed is sent to default NSNotificationCenter.

The object sent with the notification is an NSNumber containing the connection state.

sdkVersionMajor

- (int) sdkVersionMajor

readnonatomicassign

SDK Version, major

Version 1.4.1 - September 10, 2014 - Reader protocol 17
RFID configuration changes
Bug fixes

Version 1.5.1 - October 30, 2014 - Reader protocol 19
Bug fixes and performance improvements

Version 1.6.1 - December 18, 2014 - Reader protocol 19
EU Grokker support (region setting)

Version 1.7.2 - February 5, 2015 - Reader protocol 19
Streamlined UI for housekeeping tasks (set region and firmware update): added UgiConfigurationDelegate and UgiDefaultConfigurationUi

Version 1.7.3 - February 11, 2015 - Reader protocol 19
Bug fix for app inactive/active while inventory is running

Version 1.7.5 - March 9, 2015 - Reader protocol 19
Bug fix for passing both a select mask and EPCs to startInventory

Version 1.7.6 - March 26, 2015 - Reader protocol 19
Better handling of protocol errors while starting/stopping inventory

Version 1.7.7 - April 8, 2015 - Reader protocol 19
Minor bug fixes with setting region

Version 1.7.8 - April 25, 2015 - Reader protocol 19
Bug fix for intermittent issue with pausing/resuming connection

Version 1.7.13 - July 9, 2015 - Reader protocol 20
Updated Australia region information
Do not allow getting battery level during firmware update

Version 1.7.16 - August 15, 2015 - Reader protocol 20
Fix crashing bug in SetRegion if no region selected

Version 1.7.18 - September 19, 2015 - Reader protocol 20
iOS 9 / XCode 7

Version 1.7.19 - September 24, 2015 - Reader protocol 20
Fix problem with setting region on new Grokkers

Version 1.8.1 - October 5, 2015 - Reader protocol 20
API for controlling the SDK's Internet use
Fix problem with archive builds and bitcode

Version 1.8.3 - October 20, 2015 - Reader protocol 20
Fix for iOS6 and initializing new Grokkers
Remove minimum EPC length

Version 1.8.5 - October 28, 2015 - Reader protocol 20
Fix for accidentally hitting the dictation key while Grokker is connected

Version 1.9.1 - January 13, 2016 - Reader protocol 21
Protocol 21: force-tari-25 flag, delay-after-select flag
API for reading RF Micron Magnus sensor tags
Fix DetailedPerReadData readData1 and readData2 to not be byte-swizzled
Added Ugi requiresFirmwareVersion method

Version 1.9.5 - March 5, 2016 - Reader protocol 21
Added reportConnectionStateAndBatteryInfoPeriodically:

Version 1.9.6 - March 14, 2016 - Reader protocol 21
Bug fix with reportConnectionStateAndBatteryInfoPeriodically:

Version 1.10.1 - April 2, 2016 - Reader protocol 21
UgiUiUtil rework, added UI building blocks

Version 1.11.1 - May 20, 2016 - Reader protocol 21
More work on UI building blocks
Added Swift support

Version 1.11.2 - May 31, 2016 - Reader protocol 21
Farsens tag support
API Demo bug fix
Minor UgiUiUtil API enhancement

Version 1.12.1 - July 11, 2016 - Reader protocol 22
Removed support for protocol levels before 17
Protocol 22: battery info while scanning, temperature in reportConnectionStateAndBatteryInfoPeriodically

Version 1.12.2 - July 29, 2016 - Reader protocol 22
Battery status images incorporating warning about Grokker being too hot

Version 1.12.3 - August 11, 2016 - Reader protocol 22
Audio protocol fix to better handle an obscure error condition

Version 1.13.1 - September 8, 2016 - Reader protocol 23
Add localization support
Fix UgiTitleView to center the title better

Version 1.13.2 - September 28, 2016 - Reader protocol 23
Small API addition to mirror Android
Small bug fixes

Version 1.13.3 - October 28, 2016 - Reader protocol 23
Check battery level before doing firmware update
Small translation fixes
Small change to battery status images

Version 1.13.4 - November 23, 2016 - Reader protocol 23
Fix race condition bug in reporting battery info with very rapid disconnect/connect
Fix bug writing a data and passing data==previousData
Swift 3.0 compatibility

Version 1.14.1 - December 15, 2016 - Reader protocol 24
Support a password in readTag (requires firmware 1.12.3)
Support for killTag (requires firmware 1.12.3)
Fix objc_autoreleaseNoPool warning>br> Added UGI_LOGGING_BATTERY_STATUS, UGI_LOGGING_INTERNAL_BATTERY_STATUS and UGI_LOGGING_INTERNAL_PLATFORM_SPECIFIC
Add UgiLog, improve app's ability to capture logging

Version 1.15.1 - January 25, 2017 - Reader protocol 26
Support for authentication (requires firmware 1.12.4)
Single find mode (requires firmware 1.12.5)

Version 1.15.3 - February 8, 2017 - Reader protocol 26
Fix bug in 64-bit devices and per-read data

Version 1.15.4 - February 15, 2017 - Reader protocol 26
Small localization changes

Version 1.15.6 - March 31, 2017 - Reader protocol 26
XCode 8.3 support

Version 1.16.1 - July 14, 2017 - Reader protocol 26
Set Region removed (will be done in the factory)
Use Turck part number/model
Change internal Reachability symbols to avoid conflicts
Fixed a couple of minor memory leaks

Version 1.16.2 - September 27, 2017 - Reader protocol 26
Fix minor memory leak
Minor region table changes
Reduce MAX_RFID_CONFIGURATION_MASK_LENGTH_BYTES to 12, enforce this
Support for China's frequencies
Support for iOS11 and XCode 9, drop support for iOS6 and iOS7

Version 1.16.4 - October 13, 2017 - Reader protocol 26
Fix SINGLE_FIND mode, broken in previous SDK

Version 1.16.5 - January 11, 2018 - Reader protocol 27
Fix to work with very old firmware (1.6.2) still in a few Grokkers
Minor bug fixes

Version 1.16.6 - March 9, 2018 - Reader protocol 27
Fix bug writing more than 200 bytes to memory when previous memory contents are unknown

Version 1.16.7 - May 4, 2018 - Reader protocol 27
Change "Grokker" references to "PD20"

Version 1.16.8 - May 29, 2018 - Reader protocol 28
Fix bug with SINGLE_FIND mode when passing EPCs to ignore

Version 1.16.9 - June 6, 2018 - Reader protocol 28
Add parameter checking to catch illegal combinations in UgiRfidConfiguration

Version 1.16.12 - July 23, 2018 - Reader protocol 28
Updated French translations

Version 1.16.13 - October 25, 2018 - Reader protocol 28
Fixed memory leaks
UI tweaks and cleanups

Enumeration Documentation

UgiConnectionStates

- (enum) UgiConnectionStates

States for the connection, sent with [Ugi singleton].NOTIFICAION_NAME_CONNECTION_STATE_CHANGED

Enumerator
UGI_CONNECTION_STATE_NOT_CONNECTED	Nothing connected to audio port.
UGI_CONNECTION_STATE_CONNECTING	Something connected to audio port, trying to connect.
UGI_CONNECTION_STATE_INCOMPATIBLE_READER	Connected to an reader with incompatible firmware.
UGI_CONNECTION_STATE_CONNECTED	Connected to reader.

UgiGrokkerPasswordReturnValues

- (enum) UgiGrokkerPasswordReturnValues

Values returned by setGrokkerPassword and authenticateGrokker

Enumerator
UGI_GROKKER_PASSWORD_SUCCESS	Successful.
UGI_GROKKER_PASSWORD_NOT_AUTHENTICATED	Failure, grokker is not authenticated.
UGI_GROKKER_PASSWORD_WRONG_PASSWORD	Incorrect password passed.
UGI_GROKKER_PASSWORD_NO_PASSWORD_SET	No password is set, so can't authenticate.
UGI_GROKKER_PASSWORD_NOT_CONNECTED	Grokker is not connected.

UgiReaderHardwareTypes

- (enum) UgiReaderHardwareTypes

Reader hardware type and version

Enumerator
UGI_READER_HARDWARE_UNKNOWN	Unknown.
UGI_READER_HARDWARE_GROKKER_1	The original Grokker.

UgiOngoingOperations

- (enum) UgiOngoingOperations

Operation used by ReportConnectionStateAndBatteryInfoCallback

Enumerator
UGI_ONGOING_OPERATION_INACTIVE	No operation active.
UGI_ONGOING_OPERATION_INVENTORY	Running inventory.
UGI_ONGOING_OPERATION_FIRMWARE_UPDATE	Firmware update in progress.
UGI_ONGOING_OPERATION_OTHER	Other operation in progress.
UGI_ONGOING_OPERATION_BARCODE_SCAN	Barcode scan in progress.

UgiFirmwareUpdateReturnValues

- (enum) UgiFirmwareUpdateReturnValues

Values returned from firmwareUpdate and sent with firmwareUpdateCompleted

Enumerator
UGI_FIRMWARE_UPDATE_SUCCESS	Update successful.
UGI_FIRMWARE_UPDATE_NO_FILE	No update file loaded.
UGI_FIRMWARE_UPDATE_BAD_FILE	The update file is corrupted.
UGI_FIRMWARE_UPDATE_INCOMPATIBLE_HARDWARE	The update is not compatible with the reader.
UGI_FIRMWARE_UPDATE_INCOMPATIBLE_VERSION	The update is incompatible with the existing firmware.
UGI_FIRMWARE_UPDATE_CRC_MISMATCH	CRC mismatch in the file.
UGI_FIRMWARE_UPDATE_PROTOCOL_FAILURE	Failure communicating with the Grokker.
UGI_FIRMWARE_UPDATE_CANT_RECONNECT	Can't reconnect to the Grokker.
UGI_FIRMWARE_UPDATE_CANCELLED	Update was cancelled.
UGI_FIRMWARE_UPDATE_BATTERY_TOO_LOW	Battery is too low to update the firmware.

UgiLoggingTypes

- (enum) UgiLoggingTypes

Types of logging.

The default is no logging. The internal logging types are primarily for debugging of the API itself.

Enumerator
UGI_LOGGING_INTERNAL_BYTE_PROTOCOL	Lowest level communication protocol: connection handshaking and byte send/receive.
UGI_LOGGING_INTERNAL_CONNECTION_ERRORS	Low level communication errors.
UGI_LOGGING_INTERNAL_CONNECTION_STATE	Low level connection state changes.
UGI_LOGGING_INTERNAL_PACKET_PROTOCOL	Packet send/receive.
UGI_LOGGING_INTERNAL_COMMAND	Command send/receive.
UGI_LOGGING_INTERNAL_INVENTORY	Low-level inventory.
UGI_LOGGING_INTERNAL_FIRMWARE_UPDATE	Low-level firmware update.
UGI_LOGGING_INTERNAL_BATTERY_STATUS	Low-level battery status reporting.
UGI_LOGGING_INTERNAL_PLATFORM_SPECIFIC	Low-level platform specific debugging.
UGI_LOGGING_STATE	Connection and inventory state.
UGI_LOGGING_INVENTORY	Inventory activity.
UGI_LOGGING_INVENTORY_DETAIL	Inventory details.
UGI_LOGGING_BATTERY_STATUS	Battery status details.

---

Class Documentation

Ugi::UgiGeigerCounterSound

struct Ugi::UgiGeigerCounterSound

Class Members
int	frequency	Frequency for each click (Hz)
int	durationMsec	Duration of each click, in milliseconds.
double	clickRate	Ratio used for translating finds/second into clicks/second.
int	maxClicksPerSecond	Maximum number of clicks per second.
int	historyDepthMsec	Number of history periods to consider for determining click rate.

Ugi::UgiSpeakerTone

struct Ugi::UgiSpeakerTone

Class Members
int	frequency	Frequency of tone (Hz)
int	durationMsec	Duration of tone, in milliseconds.

Member Typedef Documentation

ReportConnectionStateAndBatteryInfoCallback

- (typedef void(^ ReportConnectionStateAndBatteryInfoCallback) (UgiConnectionStates connectionState, UgiOngoingOperations ongoingOperation, BOOL batteryInformationIsValid, BOOL externalPowerIsConnected, BOOL isCharging, BOOL canScan, BOOL canGetBatteryWhileScanning, BOOL temperatureAtOrAboveThreshold, BOOL temperatureWithin5DegreesOfThreshold, BOOL temperatureWithin10DegreesOfThreshold, BOOL temperatureWithin20DegreesOfThreshold, int averagedBatteryPercentage, NSString *_Nonnull statusDescription))

Callback function for reportBatteryInfoPeriodically

Parameters

connectionState	Connection state
ongoingOperation	Ongoing operation
batteryInformationIsValid	YES if externalPowerIsConnected, isCharging, canScan and averagedBatteryPercentage are valid
externalPowerIsConnected	YES if external power is connected
isCharging	YES if battery is charging
canScan	YES if battery is capable of scanning
canGetBatteryWhileScanning	YES if this Grokker can return battery information while scanning (firmware 1.11.2 or above)
temperatureAtOrAboveThreshold	YES if temperature is at or above the threshold for scanning
temperatureWithin5DegreesOfThreshold	YES if temperature is within 5 degrees C of the threshold for scanning
temperatureWithin10DegreesOfThreshold	YES if temperature is within 10 degrees C of the threshold for scanning
temperatureWithin20DegreesOfThreshold	YES if temperature is within 20 degrees C of the threshold for scanning
averagedBatteryPercentage	Battery percentage averaged over a short period, so more stable, -1 if not valid. Only valid if external power is not connected
statusDescription	Text description

AutomaticCheckForFirmwareUpdateCompletion

- (typedef void(^ AutomaticCheckForFirmwareUpdateCompletion) (UgiFirmwareUpdateInfo *_Nullable info, BOOL required))

Completion type for checkForUpdateOnConnect

Parameters

info	Info for update that is ready (or nil if update cannot be loaded)
required	YES if update is required