adding_custom_command

How To Add A Custom Command

The LINX packet architecture provides commands for many common operations such as accessing device IO and configuring and controlling sensors. However, it can be useful to add a custom function to the device firmware and then call that function from LabVIEW. LINX provides an easy method to do just that using Custom Commands.

It is recommended to add new functionality in LabVIEW whenever possible rather than using custom commands. New functionality added in LabVIEW will work with all devices, while custom commands may only work on the single device they were designed for. If you have questions about custom commands please ask in the LINX Forums.

Prerequisites

Getting Started with LINX

Hardware

Any LINX Device.

Software

Firmware IDE

Device Family	IDE
Arduino	Arduino IDE
chipKIT	MPIDE

Note: Before attempting to build custom LINX Firmware it is a good idea to get familiar with the IDE by running some examples and developing some simple test applications._

Procedure

LINX custom commands allow you to pass a U8 array from LabVIEW to the device which will process the custom data and return a U8 array response.

1. Make sure you're using LINX 1.2 or later.

2. Generate the LINX firmware libraries in the appropriate location for your device's IDE by opening LabVIEW and under the Tools tab go to MakerHub –> LINX –> Generate Firmware Libraries.

3. Generally for MPIDE you want to generate the firmware library in C:\users\*your name*\My Documents\mpide\libraries)

4. Restart the device IDE

5. In the device IDE open the LINX example for the device and interface you're using. (ex. File»Examples»LINX»Arduino_Uno_Serial)

6. The examples are read only so save a copy somewhere. This will be your custom firmware.

7. At the bottom of the firmware, after the void loop, add your custom function. The function must return an int and must have 4 parameters: unsigned char, unsigned char*, unsigned char*, unsigned char*. Below is an example function prototype.

 int myCustomCommand(unsigned char* numInputBytes, unsigned char* input, unsigned char* numResponseBytes, unsigned char* response)
 {

 }

1. numInputBytes is the number of bytes in the input array (from LabVIEW)

2. input is a U8 array which contains the data bytes sent from LabVIEW using the Custom Command VI.

3. numResponseBytes needs to be set to the number of bytes you want to send back to LabVIEW.

4. response is a U8 array. Fill this with the data bytes you want to send back to LabVIEW.

5. The function should return 0 (or use the L_OK constant) if everything went well, or an error number otherwise.

6. The following example custom command increments every byte in the input array by 1 and returns it to LabVIEW

 int myCustomCommand(unsigned char numInputBytes, unsigned char* input, unsigned char* numResponseBytes, unsigned char* response)
 {
  
  for(int i=0; i<numInputBytes; i++)
  {
    response[i] = input[i] +1;
  }
  
  *numResponseBytes = numInputBytes;
  
  return 0;
 }

1. Now the custom command function needs a forward declaration. Above void setup(), add “int myCustomCommand();”

2. Next, custom commands need to be attached to a LINX Listener so they can be called from LabVIEW. This is accomplished using the AttachCustomCommand() function of the LINX Listener.

3. The AttachCustomCommand() takes two arguments:

   1. The first is the custom command number (0-15). This is the number you'll use in LabVIEW to call this command.

   2. The second is the custom function.

4. Add the following code to the setup() function to attach the custom command to the LINX Listener (in this case called LinxSerialConnection)

 LinxSerialConnection.AttachCustomCommand(0, myCustomCommand);

1. Build and deploy/upload the firmware to the device.

2. Use the Custom Command VI (Functions Palette»MakerHub»LINX»Utilities»Custom Command) to call the custom function.

3. Below are the resulting block diagram and front panel for the given code above.

Summary

This tutorial describes the process for adding a custom command to a LINX device. It's important to remember that deploying the firmware from the firmware wizard will overwrite the device firmware with the stock version which will not contain your custom commands. If you have any questions about adding customs commands please post on the LINX forums. If you've successfully added a LINX command, consider sharing your work with the community in the forums.

Related Links and Example

Custom Command Example: PmodCLP

LINX Main Page