Table of Contents

Getting Started - Xamarin

Overview

  • Create a new Xamarin project
  • Add the Tsl.AsciiProtocol.Std nuget package
  • Set platform specific permissions (see below)
  • Determine which option to use to connect to the readers
    • Using the ASCII Transports API
    • Using the Legacy reader connection manager
  • Determine which option to use to communicate with the readers
    • Using Reader Operations
    • Using the ASCII Protocol

Create a normal Xamarin Project of your choice and reference the Tsl.AsciiProtocol.Std nuget package. You need to add the nuget package to each project in your solution, the common .NET Standard code and the platform specific code projects. We currently support Android, iOS, UWP, and WPF

Platform Specifics

Android

You need permissions for Bluetooth. Use one of the following options:

  • Open the AndroidManifest.xml and add the following permissions:
    <uses-permission android:name="android.permission.BLUETOOTH" android:maxSdkVersion="30"/>
    <uses-permission android:name="android.permission.BLUETOOTH_ADMIN" android:maxSdkVersion="30"/>
    <uses-permission android:name="android.permission.BLUETOOTH_SCAN" />
    <uses-permission android:name="android.permission.BLUETOOTH_CONNECT" />

  • Open the Android AssemblyInfo.cs and add:
    [assembly: UsesPermission(Android.Manifest.Permission.Bluetooth, MaxSdkVersion = 30)]
    [assembly: UsesPermission(Android.Manifest.Permission.BluetoothAdmin, MaxSdkVersion = 30)]
    [assembly: UsesPermission(Android.Manifest.Permission.BluetoothScan)]
    [assembly: UsesPermission(Android.Manifest.Permission.BluetoothConnect)]
  • Open the Android project Properties -> Android Manifest and ensure the BLUETOOTH, BLUETOOTH_ADMIN, BLUETOOTH_SCAN and BLUETOOTH_CONNECT options are ticked.

From Android API Level 31 onwards, the newer BLUETOOTH_SCAN and BLUETOOTH_CONNECT permissions must be both declared in the manifest, as shown above, and obtained from the user at runtime - see the SDK sample project for an example of how to do this.

If you want your App to be launched when an ePop-Loq device is attached, or when a USB OTG connection is made, then add the following to your launch Activity (e.g. MainActivity.cs)

    [IntentFilter(new[] { UsbManager.ActionUsbDeviceAttached, UsbManager.ActionUsbDeviceDetached })]
    [MetaData(UsbManager.ActionUsbDeviceAttached, Resource = "@xml/device_filter")]
    [MetaData(UsbManager.ActionUsbDeviceDetached, Resource = "@xml/device_filter")]

Be aware that, when an ePop-Loq/USB OTG device connects, it will cause a new Activity to be created unless you specify Single Task mode in the Activity annotation, for example:

    [Activity(Label = "My Great App", Icon = "@drawable/ic_tab", Theme = "@style/MainTheme",
        MainLauncher = true,
        ConfigurationChanges = ConfigChanges.ScreenSize, ScreenOrientation = ScreenOrientation.Portrait, 
        LaunchMode = LaunchMode.SingleTask
        )]

For the @TechnologySolutions.Rfid.AsciiProtocol.Extensions.AsciiTransportsManager to operate correctly on Android it need to be informed as your Activity pauses and resumes. To achieve this we have provided a simple interface @TechnologySolutions.Rfid.AsciiProtocol.Extensions.IAndroidLifecycle.

using System;

using Android.App;
using Android.Content.PM;
using Android.Runtime;
using Android.Views;
using Android.Widget;
using Android.OS;
using TechnologySolutions.Rfid.AsciiProtocol.Extensions;
using TechnologySolutions.Rfid.AsciiProtocol.Transports;

namespace Sdk.Example.Droid
{
    [Activity(Label = "Sdk.Example", Icon = "@mipmap/icon", Theme = "@style/MainTheme", MainLauncher = true, ConfigurationChanges = ConfigChanges.ScreenSize | ConfigChanges.Orientation)]
    public class MainActivity : global::Xamarin.Forms.Platform.Android.FormsAppCompatActivity
    {
        /// <summary>
        /// Holds a reference to be notified when the Activity pauses and resumes
        /// </summary>
        private IAndroidLifecycle lifecycle;

        protected override void OnCreate(Bundle savedInstanceState)
        {
            TabLayoutResource = Resource.Layout.Tabbar;
            ToolbarResource = Resource.Layout.Toolbar;

            base.OnCreate(savedInstanceState);
            global::Xamarin.Forms.Forms.Init(this, savedInstanceState);
            LoadApplication(new App());
        }

        protected override void OnResume()
        {
            base.OnResume();

            // On first resume lifecycle has not been set. Subsequent calls it will already but initialised.
            if (this.lifecycle == null)
            {
                // AsciiTransportsManager should be a singleton in your applcation.
                // Bait and switch will mean that you can Instantiate it in your .Net Standard portable code 
                // but it will be the Android platform specific version when referenced here.

                // Get a reference to the AsciiTransportsManager singleton with your DI 
                // or global reference of choice. Here we use our Locator class
                AsciiTransportsManager transportsManager;
                transportsManager = Locator.Locate<IAsciiTransportsManager>() as AsciiTransportsManager;
                this.lifecycle = transportsManager;

                // Other components that require lifecycle calls can be registered with the AsciiTransportsManager
                // Here the HostBarcodeHandler is registered.
                HostBarcodeHandler hostBarcode = Locator.Locate<IHostBarcodeHandler>() as HostBarcodeHandler;
                transportsManager.RegisterLifecycle(hostBarcode);
            }

            // Now we have the lifecycle setup, call OnResume passing the activity context each time we resume 
            this.lifecycle.OnResume(this);
        }

        protected override void OnPause()
        {
            base.OnPause();

            // Call OnPause to notify each time we pause
            this.lifecycle.OnPause();
        }
    }
}

To enable the Honeywell terminal Barcode Scanner support Open the Android AssemblyInfo.cs and add:

   [assembly: UsesPermission("com.honeywell.decode.permission.DECODE")]

iOS

You need to add com.uk.tsl. to the pList. Open the info.plist using “Open with” and the “XML (Text) Editor” - add the following to the <dict> element:

    <key>UISupportedExternalAccessoryProtocols</key>
    <array>
    <string>com.uk.tsl.rfid</string>
    </array>

UWP

You need to add USB and Bluetooth device capabilities to the appx manifest

Open the Package.appxmanifest using the View Code option to edit the raw XML and ensure the capabilities section contains the following:

    <Capabilities>         
        <DeviceCapability Name="bluetooth.rfcomm" />
        <DeviceCapability Name="serialcommunication">
          <Device Id="any">
            <Function Type="name:serialPort" />
          </Device>
        </DeviceCapability>
    </Capabilities>

WPF

There are no additional permissions to configure. To setup a Xamarin Forms project that works with WPF follow the guide below: https://docs.microsoft.com/en-us/xamarin/xamarin-forms/platform/other/wpf