Is the Chicago meeting room available? How many time a year do you ear this kind of question in your organization? On top, it is frequent you need a free meeting room for something not planned in advance and your are checking physically all the rooms in the building! In this article we present a solution, based on Asterisk, able to manage the free status of a meeting room with your PBX and line supervision feature.

Principle

The main components of our solution are: an IVR for managing presence (here room occupancy), the internal Asterisk database to keep track of the status. The room supervision (kind of busy lamp over the door) is available either through a phone call or through a SIP subscription, this last feature allows to have a lamp on your phone showing the room free status in real time, cool isn’t it?

How it works

Here are the main points on how it works:

• we create a specific extension for each room, this extension will be used to manage the room and get the status through BLF¹.
• when calling the room extension, if this one is free, a security code is asked to the user. This code will protect any further operation performed during the reservation period. The next information asked for is for how long the room is reserved, this value is entered in minutes. Both information will be stored in the Asterisk internal database.
• once the room is reserved, we change the status of the supervision field (BLF) and create an automatic call (placed in the Asterisk outgoing spool) which will free the room when reservation period will be expired.
• if ongoing reservation needs to be changed (either to free the room sooner or later), one can redial the room extension, re-enter the security code and specify a new number of minutes for the reservation period. If 0 is entered, the room is freed immediately.
• if one calls the extension when the room is already busy, he would not have the security code, by pressing # he will get an announce of the time when the room will be free.
• when reservation period expires, the automatic call is placed and the room status is changed to free as well as the BLF indicator, everybody supervising this status could thus be informed about the new status.

Room busy lamp

We already have talked about the BLF in a previous article, for more information please see “Asterisk and line supervision“. Here we are not supervising a phone line but someting virtual. For this purpose we are using the DEVSTATE function developed by Russell Bryant.

This function is available in the 1.6 Asterisk release, it is necessary to install it manually for the actual 1.4 release. This installation is easy but requires a recompile, the make menuselect will prepare the compile after the function source has been installed in the function directory. Source file is available directly at Digium.

Code

The proposed application is mainly based on the dial plan of Asterisk. We have created a specific extension file with this application, it is thus easier to manipulate an include in your dial plan if you want to test it.

Dial plan

In order to insert the application in your dial plan, you can simply include the following lines in your extensions.conf file:

; ------ MEETING ROOM START
#include conf/meeting-room-status.conf
include => meeting-room
exten => 638,1,Set(_ROOM=room_chicago)
exten => 638,2,Goto(meeting-room,s,1)
; ------ MEETING ROOM END

Here we set the ROOM variable to the name of the meeting room associated to the extension 638. The room name will be used as key for the internal database and as the name of the virtual lamp to be monitored (hint) by SIP phones.

Line supervision

Since we are not supervising a standard line, we need something special. Here we are using a custom hint, provided with the DEVSTATE function, the syntax to add to your extensions.conf file is the following:

exten => 638,hint,Custom:room_chicago

The name of the room should math the ROOM variable seen previously. The extension is the one used to access the application.

How to install

First you need to download the package we propose, see at the end of this article for the link. Untar the package on your Asterisk server and proceed with the following actions:

• copy the directory sounds/meeting-room into /var/lib/asterisk/sounds
• copy the directory conf in /etc/asterisk, it contains the specific dial plan in the file called meeting-room-status.conf
• copy the shell script agi/meeting-clean-at.sh in the directory /var/lib/asterisk/agi-bin. This script is creating the .call file allowing the automatic room cleaning at the end of the reservation period.

Room IVR manager

If you are interested in how the dial plan is working for our application, here are some information. The format used is from Asterisk::Configure but does not require any particular knowledge but Asterisk one. The code is not complete, you can look at the one provided with the package for the full version, in the src directory.

Reservation

file meeting-room-status.conf {
     context meeting-room {
          exten s {
             Answer()
             GotoIf($[${DEVSTATE(Custom:${ROOM})} = BUSY]?%%RESET%%)
             Playback(meeting-room/this_room_free)
             Playback(meeting-room/enter_code_to_lock)
             Read(lock,,8,1)
             Set(DB(meeting-room-reservation/${ROOM}/lock)=${lock})
%%RESERVE%%  Playback(meeting-room/minutes_room)
             Read(min,,3,,1)
             GotoIf($[${min} == 0]?%%CLEAN%%)
             Set(DB(meeting-room-reservation/${ROOM}/endtime)=
  ${MATH(${EPOCH}+${MATH(${min}*60,i)},i)})
             System(/var/lib/asterisk/agi-bin/meeting-clean-at.sh ${ROOM}
  ${STRFTIME(${DB(meeting-room-reservation/${ROOM}/endtime)},,%m%d%H%M)}
  ${lock})
             Playback(meeting-room/you_reserve_room_until)
             DateTime(${DB(meeting-room-reservation/${ROOM}/endtime)},,R)
             Set(DEVSTATE(Custom:${ROOM})=BUSY)
             Hangup()

This first part is about managing the room reservation. First we verify this one is currently free, then ask for a security code stored in lock. We then ask for the reservation period, this value is expressed in minute and stored in min. These values are stored in the Asterisk internal database, the end time is calculated from the actual time incremented with the minutes entered.
The script meeting-clean-at.sh is called, it will prepare a .call file that will generate a call to clean the room reservation at the end of this one. In order for this call to be placed at the appropriate time, we change the unix time of the file prior placing it in the outgoing directory.
We indicate to the calling user what is the ending reservation time and set the busy lamp indicator for this room. Any supervising phone will be informed the room is now busy.

Modifying or checking reservation

%%RESET%%    Playback(meeting-room/room_busy)
             Playback(meeting-room/consult_code)
             Playback(beep)
             Read(lock,,8,1)
             GotoIf($["${lock}" != "${DB(meeting-room-reservation/${ROOM}/lock)}"]
  ?%%BADCODE%%:%%RESERVE%%)
             Hangup()
%%BADCODE%%  Playback(meeting-room/room_reserved_until)
             DateTime(${DB(meeting-room-reservation/${ROOM}/endtime)},,R)
             Hangup()

If the room is currently occupied, when calling the room extension, the security code is asked for. If you have it, we consider you can change the reservation and use the same process as expressed previously. If you don’t have the security code, the IVR will announce the ending time of the reservation.

Automatic clearing

          exten clean-room {
             GotoIf($["${lock}" != "${DB(meeting-room-reservation/${ROOM}/lock)}"]
  ?%%RCLEAN%%)
             GotoIf($[${DEVSTATE(Custom:${ROOM})} != BUSY]?%%RCLEAN%%)
             GotoIf($[${MATH(${EPOCH}+60)}>
  ${DB(meeting-room-reservation/${ROOM}/endtime)}]
  ?%%CLEAN%%)
             Hangup()
%%CLEAN%%    Set(DEVSTATE(Custom:${ROOM})=NOT_INUSE)
             Set(foo=${DB_DELETE(meeting-room-reservation/${ROOM}/endtime)})
             Set(foo=${DB_DELETE(meeting-room-reservation/${ROOM}/lock)})
             System(rm -f /var/spool/asterisk/outgoing/call-meetingroom-${ROOM}-${lock}-*)
%%RCLEAN%%   Hangup()
          } 

From the .call file place in the outgoing directory, a call is placed at the end of the reservation period to the clean-room contexte. This one will check the security code (passed as a parameter in the call) and the current time that should be after the reservation end time. If these tests are successful, the busy lamp for the room is cleared as well as the database. The room is now free.

Download

Our solution is available here. If this application was helpful, please let us know through an email or a comment.

Conclusion

Once more a small Asterisk application, using only dial plan and standard Unix commands, can help a lot in the real world. For sure you can modify the concept for any other usage that you may have in your organization.

1. Busy Lamp Field [↩]