OPOS HardwareStationDeviceActionRequest documentation

[juergenkmsft]

Hi Team,

This is a request reg. OPOS HardwareStationDeviceActionRequest documentation.

Put in a nutshell, what we need is just a list of the actions and how we feed the actions with data( json structure) for all the devices shown in the Hardware Profile of D365 FO, so we can use the standard POS request -> HardwareStationDeviceActionRequest.

More information:
We need documentation of the OPOS commands/actions for the different hardware devices connected to the Store commerce app so we can control these devices.

The Store commerce app makes use of the OPOS technique e.g.,

1. To show text in the Line Display device
2. Send timeout info to the Barcode Scanner device.

Examples of requests store commerce sends to the OPOS driver when the app starts up:
For 1.
action: "Lock"
requestBody {"DeviceName":"MockOPOSLineDisplay","DeviceType":"OPOS","CharacterSet":0,"BinaryConversion":false}"
targetHardwareStationRequestUri: "IPC://LOCALHOST/LineDisplay/Lock"

action: "DisplayText"
requestBody: {"DeviceName":"MockOPOSLineDisplay","DeviceType":"OPOS","Lines":["",""],"Clear":true}"
targetHardwareStationRequestUri: "IPC://LOCALHOST/LineDisplay/DisplayText"

For 2.
action: "Lock"
requestBody:
"{"DeviceName":"MockOPOSScanner","DeviceType":"OPOS","DecodeData":false}"
targetHardwareStationRequestUri: "IPC://LOCALHOST/BarcodeScanner/Lock"

action: "GetBarcodes"
requestBody: "{"TimeoutInSeconds":30}"
targetHardwareStationRequestUri: "IPC://LOCALHOST/BarcodeScanner/GetBarcodes"

We would like to do the same but there's missing documentation of the available device names and actions and how the requestBody should be structured etc.

We have already written our own text to the LineDisplay device successfully by using the following classes
HardwareStationDeviceActionRequest/HardwareStationDeviceActionResponse because of the output above.

The HardwareStationDeviceActionRequest needs a 'device' and an 'action' as text plus Data in jsonformat like shown below.

var data = { DeviceName: "MockOPOSLineDisplay", DeviceType: "OPOS", Lines: ["Test OPOS Line Display", "123456"], Clear: true}
var request = new HardwareStationDeviceActionRequest("LineDisplay", "DisplayText", data);

Thank you in advance.

[madyke]

Hi @juergenkmsft - for the most common requests for OPOS device actions, customers can instead use the list of Peripheral Requests in the "PosApi/Consume/Peripherals" module of the Pos.Api.d.ts file available on the SDK. These requests serve as a wrapper for the HardwareStationDeviceActionRequest so that customers don't have to figure out the action name and required JSON format for every action.

For devices or actions that do not have an associated Peripheral Request in that list, customers will need to create a Hardware Station extension that contains a controller that they can call using HardwareStationDeviceActionRequest, as described in this documentation:

Integrate the POS with a new hardware device and generate the extension installer - Commerce | Dynamics 365 | Microsoft Learn

[cboconsult]

Thank you for your help
In our situation, we just want to send some commands to a barcode scanner. No wrapper exists. We know there is an open and close action because Storce Commerce makes use of it. We dont want to create a new extension. Making a new hardware extension also requires knowing the device name and the actions, etc.?

To get more control, we can use the HardwareStationDeviceActionRequest, but that requires knowing the individual device names and their actions plus the data they like. With LineDisplayDisplayLinesRequest, we don't have the option to set "Clear" just to take an example?

What we want is just a list of the OPOS device names that can be set up in the hardware profile and their actions and how these actions should be called and what they do. It will be a great help.

[madyke]

Hi @cboconsult - the list of controllers and actions that are exposed by the Hardware Station service are not part of the public contract, which is why they aren't documented. If you want to send a custom command that isn't provided out-of-the-box by the PosApi, our recommendation would be either:

1. Create an extensibility request to the expose the API you want to access.
2. Create a Hardware Station extension that exposes a controller for the action you want to use and use ExecuteOposDeviceMethodRequest to send the message from the controller to the OPOS device. That method (along with GetOposDevicePropertyValueRequest and SetOposDevicePropertyValueRequest) call the corresponding methods supported by the OPOS device, using a universal contract for OPOS devices: OPOS & Microsoft .NET (monroecs.com). This sample shows how to use these methods: Dynamics365Commerce.InStore/src/HardwareStationSamples/PeripheralCustomizations/Printer/CustomOposPrinterDevice.cs at release/9.47 · microsoft/Dynamics365Commerce.InStore (github.com)

p.s. Not sure if you were actually interested in clearing the line display or just using that as an example, but our team's OPOS expert also says you can do that by calling LineDisplayDisplayLinesRequest with an empty string.

[cboconsult]

If the list of controllers and actions don't exist why do we then have the option to use the class HardwareStationDeviceActionRequest?
For some devices like the scanner is this the only option? Well, we have solved our problem with a little bit of luck.
Thank you for your input.

[madyke]

Hi @cboconsult - If you go with option 2 that I mentioned above (creating HWS extension to expose custom controller for the device or action), then you'll use HardwareStationDeviceActionRequest to call that HWS extension from your POS extension code.

And yes, for any devices (like scanner) or actions that aren't implemented with a Peripheral wrapper out-of-the-box, you'll have to use one of the options I mentioned above.