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: