Gonector 1.2

Specification revision: 25, 2018-11-02.

Specification revision: 26, 2018-11-06

Specification revision: 27, 2018-11-07

Specification revision: 28, 2018-11-26

Specification revision: 26, 2018-10-26

Specification revision: 29, 2018-12-03

Specification revision: 30, 2018-11-28

Specification revision: 31, 2018-12-03

Specification revision: 32, 2018-12-10

Specification revision: 33, 2018-12-17

Specification revision: 34, 2018-12-18

Specification revision: 35, 2018-12-19

Specification revision: 36, 2019-01-11

Specification revision: 37, 2019-01-24

Specification revision: 38, 2019-01-28

Created by: Martin Vraný, Patrik Horčičák, Zdeněk Hejl, Lukáš Liebzeit, Patrik Horčičák, Martin Vraný and Martin Iliev ©2019 24U Software.

Gonector is a FileMaker plugin. It allows You to develop applications for iOS devices with FileMaker Pro Advanced. These applications are able to control various devices like printers, scales, RFID readers and POS terminals.

1. Basic technical parameters

File name:	Gonector.fmplugin
plugin ID String:	24GO
Function names prefix:	Gonector_
iOS version:	11.2.6 and newer
SN product code and versions:	GON12G, GON12U
SNLib version:	SNLib 5.2
Supported Bluetooth 4.0 devices:	qIDMiniqIDmini with Apple profile (R1170IEAPLP) produced by CAENRFID Custom MyPrinter A Custom MY3 PCL driver for Ingenico Bluetooth devices tested on Link/2500 CSOB version Ingenico Bluetooth devices connected via PCL driver tested with Link/2500 CSOB version BlueSnap Smart (RS232 to Bluetooth adapter) Infinea mPos Flat Infinea mPos Flat
Supported RS232 via BlueSnap Smart adapter (Bluetooth 4.0) devices:	Scales with RS232 interface configured via Gonector_Set with selectors "scaleReadCommand" and "scaleWeightPattern" Tested on: Traveler TA301 OHAUS scale LESAK J1-RWP scale
Supported directly connected devices:	Linea and Infinea product line from Infinite Peripherals Infinite Peripherals Infinite Peripherals Tested on: LINEA PRO 7 encrypted LINEA PRO 7 encrypted LINEA PRO 7 encrypted Infinea mPos BP500 Infinea mPos BP500
Supported iOS devices for native RFID/NFC tag reading:	iPhone 7 and higher with iOS 11 and newer
Supported NFC cards:	ISO 14443A (Mifare Classic 1k, Mifare Ultralight) ISO 15693 cards
Product icon:

2. Distribution archive (DA)

• DA will be created only for iOS as .zip file and will contain:
  • Plug-In binaries for iOS, iOSSimulator, macOS (dummy) and Windows (dummy)
  • Examples for CustomPrinter, qIDMiniqIDmini, Linea Pro 7, BlueSnap Smart and native iPhone RFID/NFC tag reading.
  • Sample FileMaker solution with CSOB implementation of payment example on Ingenico Link/2500
  • Documentation: Licence agreement, HowToRegister, ReadMe, ReleaseNotes, Syntax, UsingFMPlugins and manual for supported devices.
  • Link to 24usoftware.com site
  • Link to Xgode in the ReadMe file
  • WhatIsNew.html document
  • Sample FileMaker solution of payment implementation using Infinea mPOS

3. Supported OS for development and testing in desktop version of the plug-in:

Windows	Windows 7 and newer, FileMaker 16.0 and higher
macOS	macOS Sierra 10.12, FileMaker 16.0 and higher

Functions return either default testing values or "notImplemented". This has to be set with function Gonector_Set.
The plugin used for desktop integration does not require SNLib verification

4. Complete syntax and functionality of the plugin functions

Gonector_Version( { versionFormat } )

Returns version string of the plugin, formatted as requested by the parameter

Parameters

Parameter values for versionFormat

Description

This function is very important and it has the same output format in all 24U plugins. You should call this function every time you need to check if the plugin is properly installed to the FileMaker Pro®. Even if the plugin is not registered (or badly registered) this function should work. Calling this function in the startup script of your solution is recommended.

Result

Returns requested version format or platform. If this function returns "?", the plugin is not properly installed or FileMaker Pro cannot load and activate it for some reason.

Examples

Gonector_Version( "long" )
This will return the plugin name and its version. For example "Gonector 1.1"

Gonector_Version( "platform" )
Returns "Mac OS X", "iOS" or "Windows" depending on the platform the plugin is currently running

Gonector_Version( "autoupdate" )
Returns "01000300" for the plugin version 1.1.3. The last two digits represent the build number. In this case it means build 00 (first build) of version 1.1.0

Description

Use this function to register or unregister plugin or to get information about current registration state

Result

Returns zero. In case of error the function will return "?". Use Gonector_Get( "lastError" ) to get the specific error code.

Examples

Gonector_Register( "GON11I-BXMWC-VNW7W-L8AJS-3KGX3-XYG84" )
This function will register the iOS plugin with serial number GON11I-BXMWC-VNW7W-L8AJS-3KGX3-XYG84.

Gonector_Register( "unregister" )
This function will unregister every serial number related to plugin

Gonector_Get( selector ; { option { ; additionalData } } )

Get value specified by the selector parameter

Parameters

Possible values for the selector

Description

This function is used to get value specified by the selector.

Result

Function returns required parameter. In case of error the function will return "?". Use Gonector_Get( "lastError" ) to get the specific error code.

Gonector_Set( selector ; option { ; newValue { ; oldValue } } )

Set value or parameter

Parameters

Possible values for selector.

Note: Disconnecting the device will reset all settings in plugin to default.

Description

By this function values or parameters can be set

Result

Function returns 0 in case of success. In case of error the function will return "?". Use Gonector_Get( "lastError" ) to get the specific error code.

Examples

Gonector_Set( "inlineDocumentation" ; "on" ; "notImplemented" )
This command turns on inline documentation. inline documentation doesn't work on iOS

Gonector_Set( "deviceStripeKey" ; "LineaInfinea" ; "12345678123456781234567812345678" ; "00000000000000000000000000000000" )
This changes the stripe key in the Linea or Infinea device.

Gonector_Set( "connectionStripeKey" ; "LineaInfinea" ; "12345678123456781234567812345678" )
This sets the stripe key in the Linea or Infinea device.

Gonector_Set( "fontAlignment" ; "MYPrinterA_1" ; "center" )
This makes the device MYPrinterA_1 print the next text in the middle of the row.

Gonector_Set( "barcodeAlignment" ; "MYPrinterA_1" ; "center" )
Sets the barcode alignment to the center.

Gonector_Set( "barcode2dWidth" ; "MYPrinterA_1" ; 100 )
Sets the barcode width to 100.

Gonector_Set( "barcodeHeight" ; "MYPrinterA_1" ; 100 )
Sets the 1D barcode height to 100.

Gonector_Set( "barcodeHri" ; "MYPrinterA_1" ; "bottom" )
Sets the human readable interpretation of the barcode to the bottom.

Gonector_Set( "scaleReadCommand" ; "MIN-7943" ; "R" ) & ¶ &
Gonector_Set( "scaleWeightPattern" ; "MIN-7943" ; "(ST|US),[^\s-]*([-]?[ ]*[\d\.]+)([\D]+)" )
Sets the basic configuration for the LESAK J1-RWP scale.

Gonector_Set( "scaleReadCommand" ; "MIN-7943" ; "P" ) & ¶ &
Gonector_Set( "scaleWeightPattern" ; "MIN-7943" ; "[ ]*([-])?([\d\.]+)[ ]([^ ]+)[ ]?[ ]?([\?| ])?[ ]?([0-9]+\:[0-9]{2}\:[0-9]{2})?" )
Sets the basic configuration for the Traveler TA301 OHAUS scale.

Gonector_Set( "scaleReadCommand" ; "MIN-7943" ; "P" ) & ¶ &
Gonector_Set( "scaleWeightPattern" ; "MIN-7943" ; "[ ]*([-]?[\d\.]+)[ ]([^ ]+)[ ]?[ ]?([\?| ])?[ ]?([0-9]+\:[0-9]{2}\:[0-9]{2})?" )
Sets the basic configuration for the Traveler TA301 OHAUS scale.

Gonector_PrintImage( deviceName ; imageContainer )

Prints png or jpeg image from container. Sends a text to be printed, works with Custom MyPrinter and Custom MY3.

Parameters

Note: Custom Printer prints transparent color as black.

Description

This function uses a printer to print an image. Various font settings can be changed using Gonector_Set function

Result

Function returns 0 in case of success. In case of error the function will return "?". Use Gonector_Get( "lastError" ) to get the specific error code.

Examples

Gonector_PrintImage( "MYPrinterA_1" ; table::container )
This prints an image on the device MYPrinterA_1.

Gonector_SetScriptEvent( deviceName ; event ; scriptName )

Tell the plugin to launch the script when specified event occurs

Parameters

Possible values for event.

Some scales (such as tested LESAK J1-RWP) have to be manually configured to enable this feature.

Description

Plugin calls the script on the first occasion when the FileMaker enters "idle" state. Increase speed of event callbacks the plugin can also call itself through an URL. To setup this please check following guide.
The plugin has a buffer of one event per category and device. In case the device sends more data then the operation system can handle into the same category the incoming data is deleted. As soon as the queue is emptied by the script performer the next incoming data is stored for an event again.
For every event the deviceName will be sent back as a first script parameter "MIN-7943¶".

Result

Function returns 0 in case of success. In case of error the function will return "?". Use Gonector_Get( "lastError" ) to get the specific error code.

Examples

Gonector_SetScriptEvent( "000666D0252F" ; "onTagAttach" ; "My FileMaker Script" )
FileMaker script "My FileMaker Script" is called every time a tag approaches RFID sensor. You can get the ID of the tag by using FileMaker function Get(ScriptParameter) in the script.

Gonector_SetScriptEvent( "LineaInfinea" ; event ; "" )
This removes an event.

Gonector_SetScriptEvent( "LineaInfinea" ; "" ; "" )
This removes all events.

Gonector_SetScriptEvent( "MIN-7943" ; "onDataReceived" ; "myScript" )
This installs an event to call the script myScript with data events.

Gonector_SetScriptEvent( "MIN-7943" ; "onWeightReceived" ; "myScript" )
This installs an event to call the script myScript with weight events.

Gonector_Read( deviceName { ; selector { ; options { ; extra } } } )

Reads data from a device.

Parameters

deviceName	Unique name of the device
selector	Used to specify the request
options	Additional selector for some requests
extra	For Infinea mPos only, enter total amount (in cents e.g.: 5.00 has to be entered as 500)

Possible values for selector:

Selector	Supported device	Description
"single"	qIDMiniqIDmini Scale iPhone LineaInfinea (barcodes, RFID cards, magnetic stripes)	Read dialog will be shown for iPhone and Linea or Infinea device. This dialog closes after one item read. This is the default
"single"	qIDMiniqIDmini Scale iPhone LineaInfinea mPosInfinea	Read dialog will be shown for iPhone and Linea or Infinea device. This dialog closes after one item read. This is the default Note: Read dialog for iPhone will close after 60 seconds of inactivity and return all read cards
"multiple"	qIDMiniqIDmini iPhone LineaInfinea (barcodes, RFID cards)	Read dialog will be shown for iPhone and Linea or Infinea device. This dialog closes when "Done" button is hit
"multiple"	qIDMiniqIDmini iPhone LineaInfinea mPosInfinea	Read dialog will be shown for iPhone and Linea or Infinea device. This dialog closes when "Done" button is hit Note: Read dialog for iPhone will close after 60 seconds of inactivity and return all read cards
"unique"	qIDMiniqIDmini iPhone LineaInfinea (barcodes, RFID cards)	Read dialog will be shown for iPhone and Linea or Infinea device. This dialog closes when "Done" button is hit. The plugin guarantees that no value will be returned twice
"unique"	qIDMiniqIDmini iPhone LineaInfinea mPosInfinea	Read dialog will be shown for iPhone and Linea or Infinea device. This dialog closes when "Done" button is hit. The plugin guarantees that no value will be returned twice Note: Read dialog for iPhone will close after 60 seconds of inactivity and return all read cards
"last"	qIDMiniqIDmini Scale iPhone LineaInfinea (barcodes, RFID cards, magnetic stripes) mPosInfinea	Returns the last value received from the device Data from magnetic stripe is only kept for 10 seconds to match the PCI compliance

Some scales (such as tested LESAK J1-RWP) have to be manually configured to enable this function.

Possible values for options:

Options	Supported device	Description
"stripe"	LineaInfinea mPosInfinea	Reads a magnetic stripe. To successfully read the magnetic stripe, a stripe key must be set
"rfidCard"	LineaInfinea mPosInfinea	Reads an RFID card
"barcode"	LineaInfinea mPosInfinea	Reads a barcode
"smartCard"	mPosInfinea	Reads a smart card. Returns data which has to be sent to payment processor to complete a payment. This option can be used only with selector "single".

Read dialog example:

Description

Plugin sends a request to one of the supported devices to respond with data.

Result

Function returns JSON string if everything is OK. In case of error the function will return "?". Use Gonector_Get( "lastError" ) to get the specific error code.
The JSON string contains an array of items read (cards, tags…). The items are wrapped in arrays which contain one or more objects. Each object represents one chunk of items data (e.g. in case of localised rfid cards one object would be for data in English and another object for data in German). Each object has at least “type” and “data” or “base64Data” properties.

Examples

Gonector_Read( "qIDMiniqIDmini R1170" ; "multiple" )
This returns a JSON string such as [ [ { "type": "qIDMiniqIDminiTag", "data": "123456" }, { "type": "qIDMiniqIDMiniTag", "data": "654321" } ] ] or "?" in case of an error.

Gonector_Read( "MIN-7943" )
This returns a JSON string such as [ [ { "type": "weight", "data": "0.05¶g" } ] ] or [ [ { "type": "rawData", "data": "ERROR 2" } ] ] or "?" in case of an error.

Gonector_Read( "LineaInfinea" ; "single" ; "stripe" )
This returns a JSON string such as [ [ { "type": "stripe", "data": "cardholderName¶cardholderFirstName¶cardholderLastName¶accountNumber¶serviceCode¶discretionaryData¶expirationMonth¶expirationYear" } ] ] or "?" in case of an error.

Gonector_Read( "LineaInfinea" ; "last" ; "rfidCard" )
This returns a JSON string such as [ [ { "language": "en", "type": "ndefText", "data": "Hello", "deviceName": "LineaInfinea" }, { "language": "cs", "type": "ndefText", "data": "Vítejte", "deviceName": "LineaInfinea" } ], [ { "type": "image/jpeg", "base64Data": "SGVsbG8=" } ] ] or "?" in case of an error.

Gonector_Read( "LineaInfinea" ; "unique" ; "barcode" )
This returns a JSON string such as [ [ { "deviceName": "deviceName", "type": "barcode", "barcodeType": "CODE128", "data": "Hello 1d code" }, { "deviceName": "deviceName", "type": "barcode", "barcodeType": "QRCODE", "data": "Hello 2d code" } ] ] or "?" in case of an error.

Gonector_Read( "iPhone" )
This returns a JSON string such as [ [ { "type": "text/plain", "data": "Hello" } ] ] or "?" in case of an error.

Gonector_Read("mPosInfinea" ; "single" ; "smartCard" ; "5000")
Attempts to read from card. After entering PIN code (if required) card will return following data: "[ [ {"AMOUNT_AUTHORISED_BINARY":"00003039", "AMOUNT_AUTHORISED_NUM":"0000000012345", "APP_CRYPTOGRAM":"D37F0B7FA01FD5F2", "AIP":"3C00", "ATC":"008A", "PAN_SEQUENCE_NUMBER":"01", "ISSUER_APP_DAT":"06010A03A0E800", "TERMINAL_COUNTRY_CODE":"0100", "TVR":"08C0248000", "TRANSACTION_DATE":"181127", "TRANSACTION_TYPE":"00", "UNPREDICTABLE_NUMBER":"6AFAA376", "RISK_AMOUNT":"00003039", "TERMINAL_CAPABILITIES":"", "CRYPT_INFO_DATA":"80", "EXPIRY_DATE":"170228", "TRANSACTION_CURR_CODE":"0840" } ] ]"

Gonector_StartTransaction( "Infinea mPOS" ; "5.23" )
This function call issues a command to the terminal to make a payment of 5,23 USD on the Infinea mPOS terminal.

Gonector_ResizeImage( imageContainer ; width ; height { ; options } )

Resize PNG image Support function - not dependent on any device. Works with Ingenico device only.

Parameters

Description

This function is used to resize images. Use this function to resize image to size expected by Gonector_UpdateTransactionSubmit function

Result

Function returns FileMaker container with resized image in case of success. In case of error the function returns "?". Use Gonector_Get( "lastError" ) to get the specific error code.

Examples

Gonector_ResizeImage( test::signature ; 300 ; 200 )
This will resize image in test::signature container to 300x200 size maintaining its proportions.

Gonector_UpdateTransactionSubmit( "Link/2500-163637313071041701279653" ; "signature" ; Gonector_ResizeImage( test::signature ; test::expectedWidth ; test::expectedHeight ) )
This will resize signature image in test::signature container to expected size and then it will submit it to the terminal.

Gonector_EncodeTLV( type ; value )

Support function - not dependent on any device. Works with Ingenico device only.

Parameters

Description

This function will TLV encode provided data. This function can be used to encode data for Gonector_StartTransactionDoTransaction function

Result

Function returns a FileMaker container with TLV encoded data in case of success. In case of error the function returns "?". Use Gonector_Get( "lastError" ) to get the specific error code.

Examples

Gonector_EncodeTLV( 12 ; "INVOICENUM=0|ADDTEXT01=HELLO" )
This will encode value "INVOICENUM=0|ADDTEXT01=HELLO" and type "12" into TLV data.

Gonector_DecodeTLV( tlvContainer )

Decode TLV encoded container based on X.690 Support function - not dependent on any device. Works with Ingenico device only.

Parameters

Description

This function will decode TLV data. This function can be used to decode data generated by setScriptEvents "onTransactionEnd" and "onTerminalMessage" from same Terminals

Result

Function returns a JSON with data and type representing the TLV extracted data based on X.690 in case of success. In case of error the function returns "?". Use Gonector_Get( "lastError" ) to get the specific error code.

Examples

Gonector_DecodeTLV( Example::tlvContainer )
This will return JSON with decoded TLV data from "Example::tlvContainer" container .

6. Guides

Setup to send data for SetScriptEvent faster

• Open the Info.plist file in Your Xcode project
• Go to the bottom and click on "+" to insert a new row
• Select "URL types"
• Click at the small arrow to uncollapse the list
• Click at the small arrow next to the Item 0 to uncollapse
• Double click the empty field next to the "String" and insert "com.24usoftware.plugin" as the URL identifier
• Click at "+" and select "URL Schemes"
• Click at the arrow next to the "URL Schemes"
• Double click the empty field next to the "String" and insert uniqueString (e.g. Your application name) as the URL identifier
• Build Your Application as usually
• Set Your uniqueString via Gonector_Set( "urlScheme" ; uniqueString )