How to Create a RAP File using RevPiTimer

RAP file – what’s that and what do you need them for?

RAP stands for RevolutionPi Adapter Profile. These files are used by PiCtory to describe devices.

Using the example of the “RevPiTimer” we show you here how to create your own RAP files and what you should consider.

Project Approach

Before hitting the keys, you should give some thought to your project and define a goal. What should our device do and what should it not do.

Define your Goal

Which device do you need?

  • We need a timer.

What should this timer do?

  • It should manage repetitive on and off times on a weekly basis.
  • It should support multiple switching times.
  • The switching times should be exact to the minute.
  • The switching times should be able to be switched active and inactive.

What should this device not do?

  • Send e-mails

What do you want to achieve with this actually?

I would like to

  • turn on something at 7:15 and turn it off at 4:45, Monday through Friday.
  • turn something on at 00:00 every Tuesday but don”t turn it off.
  • be able to deactivate switching times manually.
  • turn off something at 12 on Saturdays.

Requirements

In this step, we derive the requirements that result from the goals.

  • Create a timer clock on a weekly basis.
  • Timer clock should have 16 switching times.
  • Each switching time consists of a switch-on time and a switch-off time.
  • The switch-on and switch-off times consist of:
    • All weekdays Mon, Tue, … Sun.
    • Time in hours and minutes.
    • Enabling/Disabling
  • The status of the 16 switching times can be queried (is the timer on or off?).

Implementation

Now that we have defined all requirements, we can go into the implementation. First of all, we determine the input and output data we need. These will appear in the process image. The less space the data takes up in the memory image, the more efficiently our device can process it.

In this example we need the following data:

Input data

  • Timer status of the 16 switching times

Output data

  • 16 switching times

This might sound strange, as you might actually think it should be the other way round. From the point of view of the process chain, the timer status serves as an input for further processing.

Data Modeling

Now we”re getting down to the nitty-gritty! Which data types do we need? Bit fields, bytes, etc…

Input data

  • Timer status 16 binary values
    • 1: Timer has the status On
    • 0: Timer has the status Off

Bit

7

6

5

4

3

2

1

0

Timer No.

8

7

6

5

4

3

2

1

Bit

15

14

13

12

11

10

9

8

Timer No.

16

15

14

13

12

11

10

9

Total input data: 2 bytes

Output data

For each timer we have two events (switch-on and switch-off time). In the process image it looks like this:

Timer 1: Switch on time

Timer 1: Switch off time

Timer 2: Switch on time

Timer 2: Switch off time

Timer 16: Switch on time

Timer 16: Switch off time

A time consists of:

  • Weekday and activation. We summarize these in one byte:

Bit no.

7

6

5

4

3

2

1

0

Value

Active

Sun

Sat

Fri

Thu

Wed

Tue

Mon

  • Hours: values 0-23
    • 1 byte
  • Minutes: values 0-59
    • 1 byte

So we need data

  • per time 1+1+1 = 3 bytes
  • per timer 2 times = 2*3 bytes = 6 bytes
  • per timer clock 16 timers = 16*6 bytes = 96 bytes

Total output data: 96 bytes

Realization of the RAP File

You can find the completed file of our RevPiTimer on your RevPi under:

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

Here is an excerpt from that file:

{

    “id”: “VirtTimer”,

    “version”: “1.0”,

    “comment”: [

        “=1= If -range- is empty, original datatype range is used”,

        “=2= -edit- maps whether name and/or value can be edited:”,

        “0: no editing, 1: value editable, 2: name editable, 3: both editable “

    ],

    “screencomment”: “This is a weekly based timer”,

    “size”: “1”,

    “devicetype”: “VIRTUAL”,

    “producttype”: 28673,

    “output”: [

        {

            “name”: “T1_ON_active_day”,

            “type”: “BYTE”,

            “offset”: 2,

            “range”: {

                “type”: “tooltip_loop”,

                „values“: [

                    0,

                    255,

                    1

                ]

            },

            “default”: “0”,

            “unit”: “”,

            “tags”: “output, byte”,

            “edit”: “3”,

            “order”: 10,

            “description”: “weekdays and activeflags”,

            “active”: true,

            “export”: true

        },

        {

            “name”: “T1_ON_hour”,

            “type”: “BYTE”,

            “offset”: 3,

            “range”: {

                “type”: “tooltip_loop”,

                „values“: [

                    0,

                    23,

                    1

                ]

            },

            “default”: “0”,

            “unit”: “”,

            “tags”: “output, byte”,

            “edit”: “3”,

            “order”: 11,

            “description”: “hour”,

            “active”: true,

            “export”: true

        },

        {

            “name”: “T1_ON_minute”,

            “type”: “BYTE”,

            “offset”: 4,

            “range”: {

                “type”: “tooltip_loop”,

                „values“: [

                    0,

                    59,

                    1

                ]

            },

            “default”: “0”,

            “unit”: “”,

            “tags”: “output, byte”,

            “edit”: “3”,

            “order”: 12,

            “description”: “minute”,

            “active”: true,

            “export”: true

        },

        {

            “name”: “T1_OFF_active_day”,

            “type”: “BYTE”,

            “offset”: 5,

            “range”: {

                “type”: “tooltip_loop”,

                „values“: [

                    0,

                    255,

                    1

                ]

            },

            “default”: “0”,

            “unit”: “”,

            “tags”: “output, byte”,

            “edit”: “3”,

            “order”: 13,

            “description”: “weekdays and activeflags”,

            “active”: true,

            “export”: true

        },

        {

            “name”: “T1_OFF_hour”,

            “type”: “BYTE”,

            “offset”: 6,

            “range”: {

                “type”: “tooltip_loop”,

                „values“: [

                    0,

                    23,

                    1

                ]

            },

            “default”: “0”,

            “unit”: “”,

            “tags”: “output, byte”,

            “edit”: “3”,

            “order”: 14,

            “description”: “hour”,

            “active”: true,

            “export”: true

        },

        {

            “name”: “T1_OFF_minute”,

            “type”: “BYTE”,

            “offset”: 7,

            “range”: {

                “type”: “tooltip_loop”,

                „values“: [

                    0,

                    59,

                    1

                ]

            },

            “default”: “0”,

            “unit”: “”,

            “tags”: “output, byte”,

            “edit”: “3”,

            “order”: 15,

            “description”: “minute”,

            “active”: true,

            “export”: true

        },

        […]

    ],

    “input”: [

        {

            “name”: “TimerStatus”,

            “type”: “WORD”,

            “offset”: 0,

            “range”: {

                “type”: “tooltip_loop”,

                „values“: [

                    0,

                    255,

                    1

                ]

            },

            “default”: “0”,

            “unit”: “”,

            “tags”: “input, word”,

            “edit”: “2”,

            “order”: 5,

            “description”: “Timer active flags”,

            “active”: true,

            “export”: true

        }

    ],

    “memory”: [],

    “lang”: {

        “de”: {

            “INPUT”: “Eingang”,

            “OUTPUT”: “Ausgang”

        },

        “en”: {

            “INPUT”: “Input”,

            “OUTPUT”: “Output”

        }

    }

}

Further Information

In this tutorial we will show you how to create your own RAP file:

Here you will find an overview of the structure of a RAP file: