How to Create a RAP File

If you want to integrate your own device into PiCtory you have to create a device description file which tells PiCtory the properties of your device. We call this file “RAP file”.

You need the following tools to create your own RAP file:

  • Text editor for creating the RAP file (e.g. Notepad++)
  • JSONLint to validate the file contents. JSONLint is a freely available online tool. (http://pro.jsonlint.com)

We recommend to copy an existing RAP file and use it as a template for your own file. In the following tutorial we proceed in the same way.

Let”s go!

  • Open the subdirectory “/var/www/pictory/resources/data/rap” on your .
  • Copy a RAP file to your PC (using FTP or a USB stick). For example, these: Virtual01_20160818_1_0.rap
  • Rename the copied file. There are some rules you have to follow.

Structure of the file name:

[Name]_[Timestamp]_[Major Version]_[Minor Version].rap

Example: Toaster_20170519_1_0.rap

  • Open the RAP file in your text editor.

If you use Notepad++, you can set the source language to JSON. Menu -> Languages -> JSON.

  • Go to JSONLint website.
  • Copy the contents of the file from the text editor to the browser window.
  • Click on the checkbox icon in the upper right corner to start the syntax check.

The checkbox icon turns green. This means that the RAP file has no syntactical errors. You can introduce an error by deleting a bracket, for example, and clicking on the checkbox icon again. An error message should appear.

We recommend to carry out this validation every time you change the RAP file. Otherwise, many errors may occur and it takes a long time to find them.

  • Change -> validate -> correct -> validate -> error-free

Syntax

The syntax, i.e. the grammar, of RAP files is the JSON format.

The attributes available can be found in the “List of all JSON attributes of a RAP file“.

Adjusting Attributes

Change the following attributes in order to avoid duplicates and related errors.

  • Id
    is a name that has not yet been assigned in PiCtory (e.g. “MyToaster”)
  • Producttype (e.g.: 32769)
    Change the product type to a number higher than or equal to 32769. This area is intended for RAP files written by yourself and not provided by us. This number must not yet be assigned in PiCtory. So if you write multiple RAP files, just increment this number by one for each RAP file.

Example RevPiTimer

In PiCtory there is a virtual device called “RevPiTimer” which allows you to easily switch things on a weekly basis. The following tutorial provides a basic guideline for your own RAP file: Tutorial “How to Create a RAP File using RevPiTimer”.

Adding a File to the Device Catalog

PiCtory has a tree structure on the left side listing all known devices. You have to extend the following file to include the new device:

/var/www/pictory/resources/data/catalog.json

Copy this file e.g. to a USB stick and open it by an editor.

  • Duplicate a line of the virtual devices, e.g. this one:

{“key”: “Virtual01_20160818_1_0”, “title”: “Virtual Device 32 Byte”, “tooltip”: “Virtual Device for user application with 32 Byte inputs and 32 byte output”, “icon”: “##GSD_ICON_PATHNAME##” },

  • Adjust this line to match your RAP file, e.g.
  • key:
    File name of your RAP file without extension
  • title:
    appears in the list of configured devices
  • tooltip:
    appears when you point the mouse to the device
  • icon:
    leave as it is

{“key”: “Toaster_20170519_1_0”, “title”: “My Toaster”, “tooltip”: “Virtual Toaster”, “icon”: “##GSD_ICON_PATHNAME##” },

  • Save the file and and validate it by using JSONLint.

You can add a nice icon to your virtual device, which will appear in PiCtory. For this purpose you can use the following file as a template:

/var/www/pictory/resources/images/devices/Virtual01.png

  • Copy this file e.g. to a USB stick, open it by an editor and save it under a file name that corresponds to the “id” attribute of your RAP file, e.g. “MyToaster.png”.

Importing Modified Files

Important: Please make a backup of the files or your system now, so that you can restore an executable system in case of error.

If the files are syntactically correct, you can copy them back to your RevPi. In our example, these three files are:

-/var/www/pictory/resources/images/devices/MyToaster.png

-/var/www/pictory/resources/data/catalog.json

-/var/www/pictory/resources/data/rap/Toaster_20170519_1_0.rap

Testing your Device

Open PiCtory and check the list of devices. You should now see your new virtual device.