1. What we set out to do

The overall goal of the project was to perform fax routing. Fax routing is the process of determining whom the incoming fax is intended for and sending that fax to them. The current technologies in this field use OCR (optical character recognition), or T.30 sub-addressing to perform the determination of the intended recipient. From the material we were able to find we determined that OCR was not reliable enough to base our system on. Therefore we turned to T.30 sub-addressing. T.30 sub-addressing is a standard that allows receiving faxes to know who the fax was intended for through the use of additional numbers. This works much like an extension number for a phone line. We have gone through several iterations of our project, always with the goal in mind of performing something akin to T.30 sub-addressing.

The idea was to be able to take a fax into our system, convert the files to GIF and transmit them to the user of our service, wherever they might be. This way our subscribers could receive faxes no matter where they happen to be. This could be useful for businessmen who travel a great deal, and still need to receive faxes. In addition to forwarding faxes through email our original specification was to have a series of audio menus that a person sending a fax could navigate through to ensure they were sending the fax to the correct person. This would include searching for the person’s name in a directory listing as well as checking with the sender to ensure that they wished to send the fax to that particular person. This was all to be done by first establishing a voice connection to the person sending the fax. We planned to use the same channel as the fax and just switch the status of the channel from voice to fax after the user had successfully negotiated the menus. To implement this we would need to use text to speech and directory services. If a fax machine were to call our system without first allowing a voice connection we would automatically drop to fax mode and simply post the fax to a web page. We did not specify whether the web pages would be secure or if they would be publicly accessible.

We realized that we could implement the entire faxing system with the fax modem within the provided computer, but this would keep us isolated from the rest of the teams. We wanted to be able to use the other teams’ functionality and to build an application that was unique, i.e. not a modification of commercial faxing software, and that ran on top of the infrastructure built by the first four teams. With this in mind we tried to find a way to perform all of the faxing operations over the internet voice channel. This would allow us to use all of the underlying code written by the Signaling, Gateway, Directory Services, Data Exchange, Management and Billing teams. To do this we knew that we would have to implement a fax machine in software. We briefly presented our problem to the course staff who suggested we look for shareware or freeware to help with this. There was apparently some confusion about just what our project was. We believed that the staff understood our proposed project so we scoured the web looking for some kind of software modem. Quickly we realized that there had been some misunderstanding and approached the staff again. This time it was suggested that the Dialogic card could do faxing.

Unfortunately we did not investigate the properties of the Dialogic card beyond finding the relevant sections of the API for the gateway team. Therefore, we put a lot of time into this section of the project. In this version of our project we would inform signaling that we were ready and waiting for a fax connection. Then when we received a phone call we would send our greeting over the data connection. To receive the Dual–Tone Multi–Frequency (DTMFs) we arranged to have the Signaling team pass them to us as they got them from the Gateway team. This would have allowed us to perform all of the menu operations. Then when we were done with the menus we would signal the Signaling team who would inform the gateway to change the type of connection to fax and receive a file. When a file was saved the gateway was to open a connection to our server and we would download the file using a TCP connection. We negotiated with the Signaling team and the Gateway team to get extension numbers that users would type in. We also arranged to open a TCP connection with the gateway team to download the fax file that the Dialogic card was to create. Then everything would proceed as before with posting to the web or emailing the fax file. When we learned that the Dialogic card did not support faxing, we had to change our approach again.

With this announcement we looked over the remaining options that we had to be able to simply receive a fax. The one option we had left that was able to do the fax handshaking for us and to negotiate the faxing for us was vgetty. vgetty is a freeware software package that runs on unix platforms to allow you to control the modem, receive and send faxes. It also allows you to control the voice features of a voice/fax/modem. With this package we planned to have the fax come through the PBX into the voice modem where we would send out a voice message. Then we would have the PBX grab the DTMFs and send them to us. That way we could implement our menus and routing of the faxes. With this implementation we would have used the directory services and the Signaling team. This would have been similar to our other approaches except for using vgetty and receiving the fax through the voice/fax in the machine. This method of doing our project was dropped when the Signaling team informed us that they would not be able to get the DTMFs for us. After working with vgetty for a while we knew that it was supposed to allow the ability to grab DTMFs. This was our final approach to the problem that we implemented.

Throughout all of the approaches we considered, planned, and negotiated interfaces for, we kept the common goal of being able to route faxes based on the extension number the sender could enter. This was the basis for our project and one that we carried throughout all of the incarnations of the project.

 

2. What we accomplished

The final incarnation of our system has the following functionality: after playing a brief greeting message, it receives faxes and routes them through email as attachments or posts them on a public web page, depending on the extension number it is given. The extension number is hard–coded in a shell script, since we could not get the modem to give us DTMF tones sent by the user.

The system is mainly based on vgetty, an extension to mgetty. This program interacts with voice/fax modems, and allows building of voice mail systems that can also handle fax and data if so desired. The way vgetty is set up has forced us to split our custom code into two parts. This is what happens during a typical call:

• vgetty runs and listens for a call
• when a call is answered, vgetty calls a pre–defined shell script (written by us)
• the shell script sets up the necessary environment, plays a brief greeting, and runs one of our Java applications which takes an extension number, looks it up using Directory Services, and returns the full name and email address of the person corresponding to the extension number, if such a person exists. The extension number is hard–coded in the application call, because we encountered what seemed to be a bug in vgetty. Ordinarily, instead of a static assignment, this shell script is supposed to be able to receive DTMF tones from the modem.
• when the shell script exits, vgetty answers as a fax and receives a fax from the user
• after receiving a fax, vgetty runs a pre–defined program to handle that fax, which in this case is another Java application written by us, which takes the fax and the user information determined earlier and either mails the fax as an attachment, or moves it to a web directory and updates its index
• vgetty exits. To repeat, it needs to be run again, or put into the inittab to respawn

Please see the figure on the next page for a diagram of the system. Note that it is the hand–drawn diagram we used during our presentation, and that the image is actually a fax we sent to one of our email accounts (we did not have a scanner, and using our own service was convenient).

The major difference between the end result and what we envisioned at the beginning of this project is the lack of a voice menu system in our fax gateway. We originally wanted to have at least the functionality of telling the user whom the fax will be sent to, and maybe have the user confirm it or choose another extension. More elaborate menu systems would be the logical continuation, such as looking for extension numbers by browsing through the directory, or choosing a recipient from an ambiguous set of letters or digits (such as the first three letters of the person’s name or initials). Unfortunately, every method of getting DTMF tones from the user we tried to use ended up either impossible, or infeasible in the timeframe we were given. The next section describes our problems in more detail.

Another deviation from our original intentions is our usage of vgetty and the voice/fax modem. Originally, we wanted our service to use as much of the IP telephony system as possible, which to us meant going through the Gateway to get the fax and the DTMF tones, using Signaling to establish calls, and calling Directory Services. However, as we explored the possible solutions with those groups, it became apparent that we would not be able to use those services. We ended up having to use the built–in modem in the cs519g1 machine, which means that what we get are regular phone calls just going through the PBX like any other phone–to–phone connection. The only service from our group we used at the end is the Directory Service.

1. Problems we encountered

We did in fact accomplish most of what we intended to do as we have a working internet faxing program which takes a normal user fax and can email the recipient and/or post it on a WWW page. The only major things we left out in the project were the menu system and many of the WWW page details. But with all group-related work, organizing and collaborating with each individual team was very difficult. To create a seamless and integrated Internet telephony package required a lot of effort from all the teams within the group despite hardware and software limitations.

One of the problems that we encountered was the problem of being able to call other functions from other teams. Signaling, for instance, was a factor in one of our designs because in order to have a voice menu based front end, we needed an extension number, retrieved from the gateway sent to signaling and then sent to us. This extension number was to be used with Directory Services to properly distribute the incoming fax to the appropriate directory or user. The fax itself was to be negotiated and saved by the Dialogic card. The Dialogic card provided did not have the fax daughterboard, so we couldn’t use it to perform the fax negotiation. Thus, we only had the voice/fax/modem to perform the negotiation and saving of the incoming faxes.

This left us with trying to get the DTMFs from the Signaling team as the phone call passed through the PBX. Unfortunately, the Signaling team could not provide the resources to us. With that we looked to do it ourselves. These numerous setbacks pushed our effort until almost the deadline, when we were forced to use the built–in fax/modem card in the cs519g1 machine, and vgetty to circumvent both Signaling and Gateway teams.

Along those lines, time was also a crucial factor in implementing the faxing package we intended to produce. We had to wait for the Signaling and Directory Services teams to implement API’s so our skeleton code would be able to work without any problems. With group projects though, it is about teamwork and getting everything integrated with one another so we coded assuming several things such as Signaling giving us the extension number. This worked to our disadvantage though because we ended up removing the menu feature in the end.

Also, another problem that we faced was the fact that trying to make workarounds for the modem card (the Dialogic substitute) required a lot of time consuming code restructuring to accommodate for the new instructions and file formats that the modem would take. Things such as using the G3 file format instead of the TIFF format that Dialogic automatically saved hampered the development of the final product. Converters had to be used to implement the voice greeting to properly stream data that the modem understood; others were used to convert the incoming G3 file into a more convenient GIF file. The similarities between using the Dialogic card and the USR Sportster Fax/Modem were rare. Things such as accessing the port on the card were different and also setting up communications (i.e. switching from voice to fax mode) proved to be a challenge without the help of vgetty. Dialogic was a standalone product that could be accessed and controlled via the hard coded command interface. This made programming the faxing package more straightforward. Additionally, since the Gateway team was responsible for controlling the card, they would do most of the programming, since they were reluctant to let us write code that would also control the card and integrate with their code. With the USR Sportster Fax/Modem we had to use a modem driver, vgetty, to deal with the problem that the modem had no easy way to execute commands from our Java code.

However, vgetty itself turned out to have a bug. During its operation, it calls a shell script when it answers a call. The script can then interact with the modem through special file descriptors and perform actions such as playing a file over the phone line, recording a message, or detecting DTMFs. After following the examples and writing a script which we thought would get the DTMFs for us, we found that it mysteriously exited between two statements that were completely trivial. vgetty noticed this and left a notice in its log. We could not get our script to recognize DTMFs no matter what we tried. After searching DejaNews, we found that a few other users had the same problem (manifested by identical lines in the vgetty log), but we did not find any replies to those messages. Since we encountered this problem at the very end of the project, we did not have time to investigate possible solutions to this problem fully.

Group dynamics and interaction were another source of problems for us. We believe many of the problems we had as a group came from the lack of group meetings. We had one meeting three weeks into the project and then another after Thanksgiving break. This did not give us sufficient interaction time with all of the groups to discuss common problems and try to find solutions that would serve all of the teams. We met with teams individually many times to discuss problems. In some situations we would negotiate a solution to our problem with one team such as Gateway, while another team would be negotiating basically the same problem with another core team, such as Signaling. We think this could have been avoided if more meetings had been called as we requested. The other non–technical problem was that of the interfaces supplied by the core teams. Many of these interfaces were not finalized until report three was due. While this is fine for the core teams it left the application teams with very little idea of the functionality that could be provided by the core groups. Once the interfaces were finished several of the teams did not update their reports on our group web site for weeks, again leaving the users of the code with little support. The final problem that we had was with developing code in a large group. We believe that part of the concept of the project was that the application teams would write part of the core teams’ code, which would provide specific functionality to them. This was very hard to do. First, none of the teams realized that this would be how project would end up, with different teams writing parts of other teams’ code, and therefore the code was not written in a way that allowed for easy extension. On two occasions we offered to write part of other teams’ code that would extend their functionality so we could meet our goals. On both occasions the teams were reluctant to have anyone else modify their code. We think this is reasonable, but if we had planned for this from the beginning it would have made the core teams’ projects more manageable.

 

2. What we learned

This project allowed us to learn a great deal about group interactions and large project development. We also learned about the tools that we needed to complete our project. The importance of group interactions and management was made clear during this project. Coalescing code from 10 different teams, into one functional unit, required this interaction at both the code and personal level. In order to have a successful end product many sacrifices were made in order for our code to conform to the standards agreed upon by the group members. Compromising and changing code development required a lot of effort in that we had to find new ways to implement our faxing software. This is most obvious in the evolution of our four revisions into the final faxing program. With that in mind, we now appreciate the non-technical problems associated with software development.

Our project used several different sets of standards and protocols to enable us to reach our goal, which included receiving faxes, mailing faxes to a recipient and a WWW post of undefined faxes. For the task of receiving and sending faxes we needed to learn the scripting language for vgetty, the fax communication suite we used. By understanding vgetty we were able to setup different scripts to integrate our faxing code into a usable package. To mail the fax we needed to be able to send a mail file. Since we were running our application on Linux, we decided to use sendmail as our mailing interface. To do this, we had to investigate the structure of sendmail messages and how to build them from the information we produced. For instance, in order to include attachment files in the emails, we had to investigate Multipurpose Internet Mail Extensions (MIME) attachments and the various standards on them. The information we researched for MIME attachments helped us understand how to format the fax data into usable data. The way we ended up implementing the email attachments was to convert the faxed G3 formatted files to the GIF file format and then finally, using base64 encoding, created our MIME attachment.

 

3. What we would do differently

The changes we would make if we were to do a similar project again almost all revolve around the group dynamic and cooperation. We now realize how important group meetings are for discussing interfaces and features that are to be utilized and provided by different teams, and so we would put much more pressure on the management team to organize those meetings. If the management team would not be able to provide that impetus, we would try to get people together ourselves. Having a central place to talk to everyone who provides a service we want is very useful.

On a related note, group meetings would also be a place for all the application teams to discuss what services from lower–level teams they need in common. That is something we did not really do at all. A more coherent system requirements specification from the application teams would decrease the amount of work for the low–level teams and create a more coherent system overall.

Having earlier meetings would also be necessary if it turned out that the most convenient course of action would be for us to write part of some other team’s code. After the APIs become more solidified and actual code is already written, people are very reluctant to let other teams "play" with their code. If we approached the teams in the formative stages of their part of the project, we would probably have a much better chance of getting the functionality we needed even if we had to write it ourselves.

Finally, we would make sure to conduct a "feasibility study" of sorts. We would find out what exactly we could and could not do given the equipment we had, which would also require us to find out exactly what equipment we had in the first place. Although we tried to do it, apparently we were not persistent enough to find out the exact details. Now we know how much effort is required to determine our resources. If we had done this at the outset we could have spent a great deal more time developing features such as faxing multiple people, or a way to authenticate an email and then send the attachment of the email as a fax. Unfortunately we spent a great deal of time rearranging our project to fit within the constraints of the system.

 

4. Interfaces used

Due to the final configuration of out project we only ended up using one team’s interface. We used the Directory Services to associate an extension number with a name and email address. The name was to be used with text to speech to query the sender about their choice of recipient. We wanted our project to use the system, but in order to perform faxing we were constrained to using the voice/fax/modem. We also used a package called vgetty to perform voice operations with the modem. We have also listed that interface below.

 

Directory Services:

 

import telephony.directory.*;

Digits ext = new Digits(args[0]);

DirectoryStub directory = new DirectoryStub();

Name ourName = new Name("fax");

Name name;

FullName full;

String email;

 

try {

directory.DeclareIdentity(ourName,"askhaye");

}

catch (AuthenticationException e) {

System.err.println("Could not log in to Directory Services");

}

 

try {

name = directory.GetNameByExt(ext);

}

catch (AccessDeniedException e) {

System.err.println("Access denied");

return;

}

catch (RecordNotFoundException e) {

System.err.println("Extension not found");

return;

}

 

try {

full = directory.GetFullName(name);

}

catch (Exception e) {

System.err.println("Could not get full name");

return;

}

 

try {

email = directory.GetEmail(name);

}

catch (Exception e) {

System.err.println("Could not get email");

return;

}

 

vgetty has an interface for the shell script it invokes to handle the voice calls. The script operates with two special file descriptors passed to it by vgetty, which communicate with the library that controls the voice modem. Simple commands such as "SEND filename" or "RECORD filename" are available, as well as the ability to receive events from the modem, such as "DTMF_DETECTED" or "FAX_CALLING_TONE." The exit status of the script tells vgetty what to do with the call (e.g., exit status 2 means switch to fax mode and try to get a fax). See vgetty documentation for more details.

 

5. Advice for course staff

There are several things that could have made the project much more successful. The first would be a sort of feasibility study. This may not be useful for the teams that have a well defined set of requirements such as the core teams, but for the application teams we think it would be a huge help. Another thing that may help is to prepare the core teams to have the application teams write part of their code. This would allow them to write their code in a way that is easily extendable. The last suggestion that we have is to allow more time for the project. A major problem we had was that the core teams did not have the hardware to write their code for. Therefore we had to wait until they had gotten the hardware and then written at least some specification of their interface. This kept the application teams without a lot of time to implement the applications on top of the core teams’ infrastructure.

 

6. References

http://www.lib.ox.ac.uk/internet/news/faq/archive/fax-faq.mgetty+sendfax+vgetty.html

http://www.cs.croenll.edu/cs519

file://amd/babbbage/a/cs519g1/reports

http://www.w3.org/PICS/refcode/Parser

http://support.dialogic.com/Documentation/winnt/faxapiwn.pdf

http://www.dejanews.com/

http://www.hunnysoft.com/mime/