Master of Science Thesis Department of Computer Science Lund Institute of Technology
Implementing the PalCom protocol in an Axis network camera
Brice Jaglin
January 2007
Master of Science in Computer Science Engineering
Supervisors: David Svensson, Lund Institute of Technology Daniel Elvin, Axis Communications, Lund Examiner: Boris Magnusson, Lund Institute of Technology
Abstract The thesis goal was to implement the PalCom protocol in a network camera, in order to offer the camera’s existing features via the PalCom architecture. A pro- totype has been successfully developed in C, showing that it is possible to port the PalCom communication model into an embedded device. PalCom is a research project with the goal to integrate computation in our day- to-day life. It aims at improving the user experience by easing communication between electronic devices. A way to achieve this is to develop a flexible archi- tecture that can facilitate interaction and communication between independent systems. A communication model is being designed within the PalCom project, and several PalCom-compliant emulated devices have already been developed within a Java implementation. The AXIS 207W network camera is a commercial product used mainly for video surveillance. Thanks to its fully-documented API and its Linux embedded sys- tem, it is an open system, very suitable for developers to extend.
Keywords: PalCom, Palpable Computing, Axis, Implementation, C, Server. Acknowledgements
First of all, we would like to thank the people involved in the PalCom project at LTH, Boris Magnusson and David Svensson for introducing us to the PalCom project and listening to our suggestions. Sven Gestegård Robertz answered our questions about thread design. We also wish to thank Axis Communications for lending the 207W network cam- era. Our supervisor at Axis, Daniel Elvin, introduced us to the workings of the camera and finally solved the mysterious four fragment problem. A special thank goes to Kristina Sten who though not appointed as supervisor answered our questions well and helped us forward when we were stuck.
ii Contents
1 Introduction 1 1.1 Intended readers ...... 1 1.2 Internet resources ...... 2 1.3 Report outline ...... 2
2 PalCom 3 2.1 Overview ...... 3 2.1.1 A Scenario - major traffic accident ...... 4 2.1.2 Possible use of Axis camera in major traffic accident . . . . . 5 2.2 PalCom architecture ...... 5 2.2.1 Devices ...... 6 2.2.2 Discovery ...... 7 2.2.3 Services ...... 7 2.2.4 Connections ...... 8 2.2.5 Information exchanged ...... 9 2.2.6 The x-palcom-control MIME type ...... 9 2.2.7 Assemblies ...... 9 2.3 Communication model ...... 10 2.3.1 Network ...... 10 2.3.2 Message format ...... 11
3 AXIS 207W Network Camera 15 3.1 Overview ...... 15 3.2 Features ...... 15 3.2.1 Network camera ...... 15 3.2.2 Image features ...... 16 3.2.3 Web server user interface ...... 16 3.2.4 Triggers and services ...... 17 3.3 Technical aspects ...... 17 3.3.1 Hardware ...... 17 3.3.2 Software ...... 18 3.3.3 API ...... 18
4 A PalCom server prototype on the AXIS 207W 21 4.1 Services ...... 21 4.1.1 PingService ...... 22 4.1.2 PictureService ...... 23 4.1.3 TimeService ...... 24 4.1.4 MJpegService ...... 25
i Contents
4.1.5 TriggerService ...... 26 4.2 PalCom implementation ...... 27 4.2.1 Discovery ...... 27 4.2.2 Selectors ...... 27 4.2.3 Connections ...... 28 4.2.4 Timeouts ...... 28 4.3 Module architecture ...... 28 4.3.1 PalCom base modules ...... 28 4.3.2 Services modules ...... 32 4.3.3 VAPIX module ...... 33 4.4 Thread architecture ...... 33 4.4.1 Inter-process communication ...... 33
5 Development 35 5.1 Testing ...... 35 5.1.1 Debugging ...... 36 5.1.2 Valgrind ...... 36 5.2 Design choices ...... 36 5.2.1 Camera-specific features ...... 36 5.2.2 Video features ...... 37 5.3 Impact of the prototype development on the PalCom protocol . . . 38 5.3.1 Improvements ...... 38 5.3.2 Open issues ...... 39 5.4 Evaluation ...... 41 5.4.1 Developing a server for an AXIS Camera ...... 41 5.4.2 PalCom in a small device ...... 41
6 Conclusions 43 6.0.3 Evaluation of the prototype ...... 43 6.0.4 Comparison with the built-in HTTP server ...... 43 6.1 Future work ...... 44 6.1.1 Maintaining the prototype ...... 44 6.1.2 Alternative implementation based on PalVM ...... 44 6.1.3 Reusing the prototype’s PalCom modules ...... 44 6.1.4 Develop an MPEG4 service ...... 44
A User Manual 45 A.1 AXIS 207W Quick Guide ...... 45 A.1.1 Hardware Overview ...... 45 A.1.2 Network ...... 46 A.1.3 HTTP server and root password ...... 47 A.2 Install the PalCom server ...... 47 A.2.1 Requirements ...... 47 A.2.2 Step by step ...... 47 A.3 Using the services ...... 48 A.3.1 Ping Service ...... 48 A.3.2 Time Service ...... 49 A.3.3 Picture Service ...... 49 A.3.4 MJPEG Service ...... 52 A.3.5 Trigger Service ...... 53 A.4 Known limitations ...... 55
ii Contents
B How to reuse our code for another PalCom server 57 B.1 Active and passive services ...... 57 B.1.1 Passive services ...... 57 B.1.2 Active services ...... 57 B.2 Check-list ...... 58
C How to develop on the camera and tools needed 59 C.1 Build the ARM cross compiler on your host ...... 59 C.2 Cross compilation ...... 59 C.3 Transfer a file to the camera ...... 60 C.4 Telnet ...... 60
D Tools used 61 D.1 Libraries used ...... 61 D.1.1 XML-parser: Expat ...... 61 D.1.2 Pthreads ...... 61 D.2 Software used ...... 62 D.2.1 Eclipse SDK ...... 62 D.2.2 Doxygen ...... 63
iii
Chapter 1
Introduction
The aim of this project is to see if it is possible to implement the PalCom protocol in a small device. From a PalCom perspective, this project was about showing if it is possible to port the PalCom communication model into an embedded de- vice. From another perspective, this project is about implementing an alternative way to set up and control the Axis camera as opposed to using the built-in web interface. PalCom is an ongoing European research project aiming at integrating computa- tion in our day-to-day life. This is achieved by developing a flexible architecture for interaction and communication between electronic devices. What makes Pal- Com special is that it focuses on unplanned connections. The protocol is designed so that devices not previously thought of to have a need to communicate should be able to do so when the need arises. A number of emulated devices have al- ready been developed and implemented in Java. The AXIS 207W network camera is developed by Axis Communications in Lund and is mainly used for surveillance. It is an open system with publicly docu- mented API, and has Linux as operating system. It is thus very suitable for non Axis people to develop and extend.
1.1 Intended readers
The report is intended to have several categories of readers. This section describes what you should read depending on your background and/or your motivation. Computer Scientist, Student You have a Master of Computer Science or equiv- alent, and you are interested in new perspectives to facilitate connections between devices, and the way it could be implemented. You should read chapters 2, 3, 4, and 6. You can also be interested in Chapter 5 and Appendix D if you want to know more about the development. PalCom User You have already used other PalCom devices and want to use an AXIS 207W camera with them. You should read Appendix A. Chapter 3 is also relevant if you want to know more about the camera.
1 Chapter 1. Introduction
AXIS 207W User You are familiar with the AXIS 207W network camera, and you want to explore the possibilities offered by the PalCom server. Start by read- ing Chapter 2 and Appendix A. PalCom Developer You are familiar with the PalCom communication model and you want to understand how the C implementation works. Please read Chapter 4, 5, 6. Appendix B will be also valuable if you want to port the implementation to another device.
1.2 Internet resources
You can find this report, as well as the source code and other useful information at http://www.lucas.lth.se/axis-palcom/.
1.3 Report outline
The report is structured as follows: Chapter 2, PalCom gives an overview of the PalCom protocol. Chapter 3, Axis 207W Network camera describes the Axis camera. Chapter 4, A PalCom server prototype on the AXIS 207W describes our imple- mentation of the PalCom protocol on the Axis camera. Chapter 5, Development describes why the final prototype is as it is. Chapter 6, Conclusions contains a summary of our results and suggestions for further work. Appendix A, User Manual consists of a user friendly manual of how to use the prototype. Appendix B, How to reuse our code for another PalCom server is intended for PalCom developers who want to use our prototype as a base for another implementation in a new device. Appendix C, How to develop on the camera and tools needed is intended for some- one who wants to develop on an Axis 207W camera. Appendix D, Tools used describes tools used during development of the proto- type.
2 Chapter 2
PalCom
PalCom1 is a 4-year EU project started in 2004, aiming to research and develop a new perspective on ambient computing. Ambient computing, which is a synonym of ubiquitous computing, does not consider computers as distinct objects, but rather as active parts of the environment itself. PalCom stands for Palpable Computing, which denotes that systems are capable of being noticed and mentally appre- hended. A non-technical overview of the PalCom project is presented in section 2.1. Tech- nical aspects, such as the architecture and the communication model are de- scribed in sections 2.2 and 2.3.
2.1 Overview
Imagine a landscape architect taking hundreds of photos of a particular place and needing to store the information of exactly where those photos where taken. The information from his digital camera and his GPS need to be merged somehow. This merging does not necessarily have to be done by a human being. The dif- ferent devices could as well communicate with each other without any human interaction. However, in some situations, human interaction could of course be needed. This situation could arise for other groups of devices as well. You could for ex- ample want to control your stereo from you mobile phone. Or in a professional situation, for example in a hospital you can think of several ways the different devices might need to communicate. A scenario from the health care system is the site of a traffic accident where the information exchange of different devices could help the medical personnel get a quicker overview of the situation. A more detailed description of this scenario is found in section 2.1.1 In the PalCom project a new concept called palpable computing is being researched and developed. An objective is to design an open architecture for unplanned connection of devices. The design process is based on real life scenarios (see fig- ure 2.1). The landscape architecturing and the traffic accident mentioned above
1http://ist-palcom.org/
3 Chapter 2. PalCom are two of them. Other scenarios include IT-support for pregnancies and rehabil- itation support.
Figure 2.1: PalCom development cycle
In palpable computing, invisibility is complemented with visibility. With the de- velopment of embedded systems, computers become more and more invisible in our day to day life. In some cases it is desirable that the computers are not visible and just do what they should. In other cases you want them to be seen. You want to know what they are doing, what they may do and what other devices they might connect with. Palpable devices should be able to handle changes in their immediate environ- ment. Other devices may be moved from or entered into the environment. As the environment changes a device must sense the presence of other devices and understand what services the other devices can provide. A device should both be able to choose in what way to connect, since the user otherwise will have an overwhelming amount of decisions to make, and always give the user the chance to make the final decison.
2.1.1 A Scenario - major traffic accident
This section is meant to give an idea of how PalCom implemented devices can help in real life situations. A scenario from major traffic incidents is described. This example is found in [2]. However, the PalCom implemented AXIS camera described in this report has not yet been used in any scenario. The PalCom design process is based on scenarios. One of those scenarios is a major traffic accident. Field studies have been conducted in order to understand how palpable computing can be a support in major accident situations. This is a good example of where coordination of activities cannot be planned ahead with experience from identical situations. An emergency situation requires fast and effective collaboration between rescue personnel. In a major accident there are many different categories of professionals involved. The different groups of professionals have different roles and responsibilities. They work at the incident site, in the emergency vehicles, at the dispatch centers
4 Chapter 2. PalCom and in hospitals. At the incident site the police and the fire-fighters are respon- sible for different physical areas and the medical and ambulance personnel are responsible for the treatment of injured persons and the transportation to hospi- tals. Collaboration and coordination would be made easier if there were maps or images to support communication with personnel not yet on the incident site and if there were support to show and interact with such information. Injured persons are categorized according to the severity of their injuries. The status of victims is likely to change and is therefore periodically monitored by a paramedic2. This makes it extremely difficult for any person to always have an up-to-date overview of the situation. Every injured person should have an accident card describing his identity and injuries. This card should be attached to the person and follow him to the hospital to inform the hospital personnel of his condition. However, filling in this card is seldom a high priority in an accident situation and this information may be lost. Another problem is the use of biomonitors such as the measuring of ECG and oxygen saturation. The signals from those measurements can only be seen if you are next to the display, that is, next to the patient. Biomonitors are hardly used in major incidents both because of this lack of portability and because of lack of equipment and time.
2.1.2 Possible use of Axis camera in major traffic accident
The Axis camera could for example support the lack of maps and images at an accident site. It can send pictures to rescue coordinator and personnel not yet on the site. It could for example be used by personnel at the dispatch center to help them decide how many injured people there are at the site to know how many ambulances to send. If injured persons are clearly labeled the camera could probably also help in de- termining the location of a specific person. It could also be used to determine the location of different groups of rescue personnel. Monitoring several cameras at the same time can be a difficult task, especially at an accident site. However, the motion detection feature of the camera can be used to get only relevant images, so that people in charge of coordination do not need to watch static, worthless images. Thus, they can be more effective and focus on areas where there is action.
2.2 PalCom architecture
This section describes the current working architecture of PalCom and defines the entities involved, without entering into technical considerations. We will il- lustrate our description with a scenario presented in figure 2.2. This scenario is a sub-scenario of the scenario presented in section 2.1.1. Note that the storage unit is not implemented yet, and is just used to provide an understandable scenario in this report.
2emergency medical technician
5 Chapter 2. PalCom
From her personal digital assistant, a user should be able to set up devices so that a stream recorded by a video camera is saved on disk by a storage unit, and so that she can consult videos grabbed at any moment. This scenario makes sense especially if none of the original devices shared a common protocol or standard to communicate with each other.
Figure 2.2: A PalCom scenario with 3 devices
The corresponding PalCom architecture is sketched in figure 2.3.
2.2.1 Devices
In the PalCom architecture, devices are independent systems that should com- municate with each other. The main goal of PalCom is to make it easy to connect devices that were not designed to communicate with each other. A device could be any digital device, as long as it supports PalCom and it can communicate with other devices, whatever the network is. Since PalCom is still a research project, no commercial device comes with PalCom support today, so it has to be added. A solution is to patch the current system of the device by adding a new server that runs in parallel with the built-in ones. In our example, we have three devices: Handheld This device is also known as personal digital assistant. In this scenario, it does not act as a special expert device, but rather as a generic PalCom browser, allowing the user to browse, control and interact with other Pal- Com devices. Video Camera This could be an Axis camera, patched with our PalCom proto- type. The main feature of this device is to provide a video stream captured in real time. Video Storage This unit is an advanced, stand alone hard disk. It can store a video streamed in real time so that it can be played back later on, without
6 Chapter 2. PalCom
Figure 2.3: PalCom architecture for the previous scenario
the need to be connected to a host with adapted software, as it would be for a normal hard drive. All these devices are connected together, being part of the area denoted "The Universe" in figure 2.3.
2.2.2 Discovery
One of the goals of PalCom is to combine visibility with invisibility. The goal of the discovery step is to make the devices visible to each other. The approach cho- sen is a flexible architecture, without any central directory. Each device announce its arrival and its departure, so that each device is aware of the presence of any other device in the network. The three devices in our example provide information all the time. As a result, the Handheld knows for example that there is a Camera and a Storage Unit nearby. The discovery protocol applies for all the information requests, and depending on the situation, uses broadcast or direct packet sending.
2.2.3 Services
In the PalCom terminology, a device can be divided into several services, which are logical groups of features. A device can ask for a list of the services pro- vided by another device and further information about some of them, in case
7 Chapter 2. PalCom they match its needs. The main information about a service is the type of data it exchanges (see section 2.2.5 for more information). We are going to describe the services that the devices in our example offer. Handheld This device has only one service, denoted UI. This service generates a user interface out of another service description. The user can then use and control services offered by the devices around. Video Camera Two services are available on the camera. Settings can be used by another PalCom device to change global settings of the camera, such as the frame rate and the resolution. Video is a service that pushes the real time video stream. Video Storage It has three services. Settings is the service one should use to set up global parameters of the storage unit (how long the video stream should be kept for example). Archives is the service to use to playback streams that have been stored on the disk. Recorder is the service responsible for receiving and storing a video stream.
Customer and provider
Independently of the nature of the device, each service can be either a provider or a customer. A provider is a service waiting for another one to use it. Settings, Archives and Video are such services. These services have in the first step to advertise so that other services know about them while waiting for customers. They have there- fore circle arcs representing female connectors in the figure 2.3. On the contrary, the UI and the Recorder services are customer services. A customer has to establish a relationship with a provider to actually do something. It is up to him to come to a provider and ask for information. These services have therefore arrows representing male connectors in the figure 2.3. Being a customer or a provider defines the direction a connection should be es- tablished, but does not assume anything about the ability to act spontaneously or to react to incoming orders, as explained in the next section. As you can see in figure 2.3, a device can have provider services only (Video Camera), customer services only (Handheld), or both (Video Storage).
2.2.4 Connections
To instantiate a communication between two services, a connection must be es- tablished. This connection must be initiated by a provider service, connecting to a customer service. Two providers cannot be connected, and neither can two cus- tomers. This does not assume anything about the direction data is sent during this connection, but just which side is responsible for establishing the connection. In figure 2.3, connections are represented by dashed lines connecting one male connector to one female connector.
8 Chapter 2. PalCom
Each service can have multiple connections. For example, the UI service has es- tablished three connections: one to set up the settings of the camera, one to set up the settings of the storage device, and one to consult the archives stored in the storage device. In figure 2.3, each service has only 4 possible connections to make it more readable, but there is no theoretical limit.
2.2.5 Information exchanged
Once two services are connected, they can start to communicate. The communica- tion is entirely defined by the provider, which has provided the type of data that will be exchanged over the connection. In our example, all the services commu- nicate with the x-palcom-control MIME type, so we will focus on the different commands the type defines.
2.2.6 The x-palcom-control MIME type
This MIME3 type is actually XML with a given DTD. When two services commu- nicate with it, they can send or receive commands. Depending on the nature of the service, which is defined by the provider, commands can be either in or out. From a provider point of view they are sent from the customer to the provider or from the provider to the customer respectively.
The double arrows on the connection lines symbolize these commands. For ex- ample, the Video service in the camera has only out commands, as it only sends in- formation and does not wait for any commands coming from a connected provider. The Archives service has both in and out commands, as it waits for the command containing the date requested ("I want to see the stream recorded on March 13th") before streaming the appropriate video.
Last but not least, the commands can have parameters. The previous command, asking for the stream on a special date, has a parameter which is namely the date. This parameter is also defined by a MIME type. As only XML commands can be exchanged over a x-palcom-control connection, information is most of the time embedded as one or several parameters. The stream that consists of multiple JPEG frames is thus made of several out commands with a parameter which MIME type is JPEG.
2.2.7 Assemblies
To make devices communicate without any human interaction, there is a neces- sity for a scripting language. Assemblies act as services in a browser, and allow such scripting. An assembly can connect to several services, describing what to do according to an event/action scheme. See [10] for more details.
3Multipurpose Internet Mail Extensions. This standard is used to describe non-text information when it is sent over a character stream, as in an e-mail or an HTTP server answer.
9 Chapter 2. PalCom
2.3 Communication model
This section contains a technical description of the PalCom communication model: it describes the implementation of the architecture explained in section 2.2. An overview of a typical PalCom communication session is described in fig- ure 2.4. It represents all the messages exchanged when a user wants to consult the archives in the Video Storage Unit, from the handheld, as described in the scenario from section 2.2.
Figure 2.4: Overview of a PalCom communication session
2.3.1 Network
Currently, the PalCom architecture relies on that all devices are connected to the same network. Future versions will provide device-gateway features, allowing
10 Chapter 2. PalCom for example a device A, connected to a device B through an isolated network, to communicate with a device C, connected to B through another isolated network. All the messages in the PalCom communication model are UDP packets. Note that, at the time of writing, sending big PalCom packets using several UDP pack- ets is not yet supported. Furthermore the communication model is probabilistic and does not rely on sessions, which means that there is no guarantee that a packet sent has been received. For the advertisement steps (DeviceInfoRequest and DeviceInfo messages), mul- ticast is used as a way to broadcast messages to all the available devices. All the other messages are unicast. To prevent firewall blocked ports problems, PalCom devices use as few ports as possible. In the current model, one is fixed and must be opened to receive multicast messages, and it is up to the device to choose the port(s) it will use for unicast communication. Next versions of the PalCom model will probably only use one port.
2.3.2 Message format
PalCom messages are most of the time high level XML documents encapsulated in a low level PalCom packet. In this section we give details on both levels. An overview of the PalCom message flow is given in figure 2.5. It represents a Video Storage Unit with one connection with the Archives service opened.
PalCom header
As only a limited number of UDP ports are open for communication, one has to specify, in each message, what service or connection it is meant for. The model used for these "internal PalCom ports" is called selectors. As you can see in fig- ure 2.5, there are selectors for each service, each connection, plus one for global messages. These selectors are strings which are chosen by the device itself, with- out any constraint. Below is an example which shows the format of the PalCom header, taken from [9]: 42;d;8;12;[a 42 byte long message] The actual message comes after the last semicolon. The header consists of four fields separated by semicolons: size The first field indicates the size of the actual message and is given in decimal digits. type The second field gives the type of the message. It can have three values: c Control messages. For example a disconnect message could look like this: 10;c;8;12;disconnect d Data messages. All other kinds of complete messages are of type data. The message part is usually XML but can also be binary.
11 Chapter 2. PalCom
Figure 2.5: Typical message flow in a PalCom device
+ Multipart messages. After a header with type multi-part follows directly zero or more complete messages. These messages may be multi-part messages themselves. sender selector The selector on the remote device is 8 in this example. receiver selector The selector on the local device is 12 in this example. This field may be empty when the packet is not aimed at any specific service or con- nection, or when the header is a part header, inside a multipart PalCom packet.
Discovery packet
Here is an example of a multicast, multipart, discovery packet: a DeviceInfo.
1 323;+;0;0;9;d;;;discovery300;d;;;
2
3
4
Listing 2.1: Example of a PalCom packet: DeviceInfo
12 Chapter 2. PalCom
Command packet
Here is an example of a unicast, multipart, x-palcom-control packet: a SynchTime command with a time parameter which is "2006-12-12 17:42:00".
1 238;+;2;6;204;d;;;
2
3
4 19;d;;;2006-12-12 17:42:00 Listing 2.2: Example of a PalCom packet: Command
A schematic view of this packet is shown in figure 2.6. The attribute dataRef inside the time parameter is a pointer to the corresponding information. The reason why such information is not included directly in the XML is that it may be binary.
Figure 2.6: Schematic view of a Command packet
13
Chapter 3
AXIS 207W Network Camera
An Axis network camera[1] can be described as a camera and computer combined in one unit. It operates as a stand-alone unit and requires only a connection to an IP network by wired or wireless means. It captures and sends live video directly over any IP network, from a local intranet to the Internet. It has a built in web server which means that it does not need a direct connection to a PC or any other hardware or software to capture and transfer images. The built in web server enables users to view and/or manage the camera using a standard Web browser on any local or remote computer on a network.
3.1 Overview
The camera has two connectors (network and power), four indicators (status, network, power and wireless), a microphone, a wireless antenna, a 4-pin I/O terminal connector block, and a control button to reset the camera to its factory defaults. The focus can be adjusted using the focus ring around the lens. It takes approximately one minute for the camera to boot.
3.2 Features
3.2.1 Network camera
A network camera is an independent device that can be connected by itself to a network, unlike for example a web camera which needs a host such as a personal computer. Depending on the configuration, the camera can have a static IP or get one from a DHCP. The camera can then be reached by its IP address. The AXIS 207W can connect to an IP-network via Ethernet or its 802.11g wireless interface. By default, the Ethernet interface has a higher priority, so the wireless will be enabled if and only if no cable is plugged in.
15 Chapter 3. AXIS 207W Network Camera
Figure 3.1: Axis 207W
3.2.2 Image features
The camera is able to take pictures, stream Motion JPEG and MPEG-4 videos in real-time, and perform motion detection. Video streaming can be unicast (up to 10 users) or multicast.
• The Motion JPEG format consists in sending lots of JPEG images (basically 25 frames per seconds). It requires a large bandwidth but pushes frames almost without any latency.
• The MPEG-4 format performs compression not only on frames, but also from one frame to another by coding only the differences, requiring a sen- sibly smaller bandwidth. However, the compression processing introduces a latency of several hundreds milliseconds.
3.2.3 Web server user interface
The 207W has a built in web server providing user friendly configuration in- terface and pictures/video preview. All its parameters can be set up: network settings, picture settings, video settings, motion detection windows and object sensitivity etc.
16 Chapter 3. AXIS 207W Network Camera
3.2.4 Triggers and services
The camera can be configured to react to special events such as motion detection or pin input. A picture or a video file can then be uploaded to an FTP server, or sent by e-mail.
3.3 Technical aspects
An overview of the internal architecture of the camera is presented in figure 3.2. There are also other servers such as UPnP1 and Bonjour2 but none of them were used in this project and are not related to the functionalities discussed in this report.
Figure 3.2: Axis camera internal architecture (simplified)
3.3.1 Hardware
Unlike the other AXIS cameras embedding an ETRAX CRIS core chip3, the 207 and 207W are based on an ARM9 architecture4. The image processing part is handled by the ARTPEC-A chip. The system has 32 MB of RAM and 8 MB of flash memory. The flash memory is divided in two parts : The operating system , which can only be modified by updating the firmware. Firmware update is easy thanks to the web interface, see section A.2. A read/write area of 2.5 MB used to store both configuration files (this area is mounted in the /etc directory) and user-made programs and scripts. The initial configuration files take around 400 kB, leaving approximately 2.1 MB for user made applications.
1http://www.upnp.org/ 2http://developer.apple.com/networking/bonjour/ 3The ETRAX CRIS series are CPUs designed by Axis. 4Processor ARM/ANOTO CT200
17 Chapter 3. AXIS 207W Network Camera
3.3.2 Software
Linux
The camera runs under a Linux environment (2.6.12 kernel for our firmware). All the usual UNIX commands are thus available, thanks to the busybox package5. A telnet server can be enabled by uncommenting a line in the init script see section C.4. Even the vi text editor is available. The login/password to use in order to open a shell or an FTP session is the one the user was asked to set up at the first web interface connection.
3.3.3 API
All Axis network cameras have a programming interface called VAPIX 6. The VA- PIX API provides functionality for requesting images, controlling network cam- era functions and setting/retrieving internal parameter values. As you can see in figure 3.2, the VAPIX API is accessible via the HTTP server, and is used in- ternally by the HTTP user interface. As a result, VAPIX could be used through a user friendly interface in HTML, or directly with HTTP request, by scripts or advanced users. From one AXIS camera to another, the VAPIX API could differ in some parame- ters and settings, but is globally the same. It is a fully documented and supported interface that is the standard of Axis. As a result, one should use it as much as possible when writing external or internal tools, in order to be sure scripts will still work for future firmwares or even models. Depending on the type of resource to work with, VAPIX requires a certain level of authentication. As a result, basic requests can be anonymous, but those which deal with the system settings require an account. Accounts are actually UNIX account that can be used either with VAPIX, telnet, or FTP. Three groups are de- fined: users, operators, and administrators.
Development
As a linux environment, the camera can run C programs compiled by a "x86 to ARM" cross compiler, provided that the compiler has been given the right flags (see section C.2). Cross-compiling is the operation of building a binary file that will be run on another platform than the compiler host itself. Debugging is more difficult, as no gdb7 is available on the camera. It would be possible to remote debug but the tools required are not in the public domain. The easiest way to write a third-party program for execution on the camera, is to put it in user space. Writing a kernel module would require access to the oper- ating system part on the flash memory, and thus to use lot of private AXIS tools.
5This package combines tiny versions of the most common UNIX utilities into a single small exe- cutable. See http://www.busybox.net. 6http://www.axis.com/techsup/cam_servers/dev/cam_http_api_index.htm 7gdb is the standard GNU debugger.
18 Chapter 3. AXIS 207W Network Camera
This is not recommended by Axis because of maintenance issues and potential modifications in next versions. During the development process, it is better to put executables in /tmp/ in order to reduce flash memory I/O. The flash chip manufacturer estimates the number of writes to the flash chips to about 100,000. The problem with this is that the files stored in /tmp/ are lost when the camera reboots.
19
Chapter 4
A PalCom server prototype on the AXIS 207W
This chapter contains a description of the PalCom server on the Axis camera. A description of the different services provided and a motivation for them as part of a possible scenario is found in section 4.1. Details about implementation of the PalCom model are described in section 4.2. Sections 4.3 and 4.4 describe how the server internally works, presenting its module and its thread architecture. An overview of the PalCom server in the Axis camera is presented in figure 4.1. Compare this overview with figure 3.2. The module architecture of the server is described in section 4.3.
Figure 4.1: Axis camera internal architecture with PalCom server zoomed. The module architecture of the PalCom server is explained in the zoomed figure.
4.1 Services
This section describes the design of the services and a motivation for the different commands and parameters. For a guide of how to use the services in the camera please refer to section A.3 in Appendix A - User Manual.
21 Chapter 4. A PalCom server prototype on the AXIS 207W
The camera provides the following services: PingService, TimeService, Picture- Service, MJpegService and TriggerService. A dump of the XML ServiceList which the device sends after a ServiceListRequest is presented in listing 4.1. The ServiceList contains one ServiceInfo for each service.
1
2
3
4
5
6
7
8
9
10 Listing 4.1: XML message with ServiceList
According to the PalCom approach, we will first describe the scenarios we imag- ined the camera can be involved in, and then the features resulting from those scenarios.
4.1.1 PingService
Background scenario
In the PalCom model, communication is probabilistic and we are never sure about the state of a remote device. In some situations, such as failure detection, it is interesting to ping a device to be sure it is running.
Design of service
A dump of the XML message describing the PingService is found in listing 4.2 and its respective graphical representation is found in figure A.1.
1
2
3
4
22 Chapter 4. A PalCom server prototype on the AXIS 207W
5
6
7
8
9
10
11 Listing 4.2: XML message describing PingService
This service is very simple. It has one incoming command and one outgoing command: • ←− hello : This incoming command should be sent to check if the server is running. It results in an outgoing acknowledgement. • −→ ack(string time) : This outgoing command, sent after a hello request, has one parameter. It was chosen to be the local time of the camera.
4.1.2 PictureService
Background scenario
Network cameras are mostly used for video surveillance. An operator is often in charge of inspecting the pictures recorded by the camera, as motion detection is most of the time inefficient in crowded environments. Therefore, depending on the environment the camera is used in, pictures should either be pulled from the camera, i.e. sent after a request, or pushed out from the camera, i.e. sent without any request, for example every 5 seconds.
Design of service
A dump of the XML message describing the PictureService is found in listing 4.3 and its respective graphical representation is found in figures A.3 and A.4 in Ap- pendix A.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
23 Chapter 4. A PalCom server prototype on the AXIS 207W
15
16
17
18
19
20
21
22
23
Listing 4.3: XML message describing PictureService
This service has three incoming commands and one outgoing command. • ←− TakePicture: This incoming command should be sent to get a picture. It results in an outgoing Picture. • ←− EnableTrigger(start, period): This incoming command should be sent to enter a time-triggered pushing mode. At least one parameter has to be non empty. If the start parameter is empty it will be set to start immediately. If a value is given it can be set to start at the most 24 hours in advance. If the period parameter is empty only one frame will be sent. A later request of the same command will result in a change of the start time and/or period. • ←− StopPeriodic: This incoming command will exit the time-triggered pushing mode. • ←− SetGlobalParameters(compression, resolution and text): This in- coming command results in changing the respective picture parameter for the camera. The change will also effect other PalCom connections to this camera. If their values are not set, the respective values will be what they were set to last. • −→ Picture(frame): This outgoing command encapsulates a JPEG frame.
4.1.3 TimeService
Background scenario
It is always interesting to know when a picture was taken. You could for example have two different cameras sending you pictures of the same scene from different angles, where the time is shown on the frames. To be able to compare those pictures the two cameras need to have the same time set. Thus it is good to be able to synchronize the cameras’ time.
Design of service
A dump of the XML message describing the TimeService is found in listing 4.4 and its respective graphical representation is found in figure A.2 in Appendix A.
24 Chapter 4. A PalCom server prototype on the AXIS 207W
1
2
3
4
5
6
7
8
9
10 Listing 4.4: XML message describing TimeService
This service has one incoming command. Its result can be checked with the PingService or with the PictureService. • ←− SynchTime(time): This incoming command results in setting the time of the camera. If the parameter value is empty, the camera will be asked to read the time from an NTP server. Otherwise it should be the new time for the camera.
4.1.4 MJpegService
Background scenario
To use the camera for surveillance you need video. A lower frame rate requires less bandwidth.
Design of service
A dump of the XML message describing the MJpegService is found in listing 4.5 and its respective graphical representation is found in figure A.5 in Appendix A.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
25 Chapter 4. A PalCom server prototype on the AXIS 207W
15 Listing 4.5: XML message describing MJpegService
• ←− ShowVideo: This incoming command subscribes to an MJPEG stream. • ←− StopVideo: This incoming command unsubscribes to the MJPEG stream. • ←− SetGlobalFrameRate(frames per second): This incoming command sets the frame rate of the MJPEG stream. The change will also effect other PalCom connections to this camera. • −→ Video(frame): This outgoing command encapsulates a JPEG frame from the MJPEG stream.
4.1.5 TriggerService
Background scenario
In an ambulance or at a hospital you monitor the state of the patients. Sometimes it might be interesting to monitor only the patient’s movements. Then you only need to be sent frames from the time before, during and after the movement. Another scenario using motion detection trigger is a break-in. You want a picture of the burglar. A few frames from before the movement was detected and during the motion is good to have in order to identify the thief. A scenario where the external trigger can be used is at an orienteering competi- tion. If two orienteerers cross the finish line at almost the same time you want to have a picture from exactly that moment to be able to decide who was the fastest. The sensor for the finish line can be connected to the camera’s external input. It is desirable to have a few frames from before the signal and a few frames after to be able to make a fair judgment.
Design of service
A dump of the XML message describing the TriggerService is found in listing 4.6 and its respective graphical representation is found in figure A.6 in Appendix A.
1
2
3
4
5
6
7
8
9
10
11
12
26 Chapter 4. A PalCom server prototype on the AXIS 207W
13
14
15
16
17
18
19
20
21
22
23 Listing 4.6: XML message describing TriggerService
This service uses the cameras motion detection daemon. Communication be- tween the PalCom server and the camera is done via a virtual UNIX socket. When trigger is enabled the server continuously buffers the number of frames specified in pretrigger frames. • ←− EnableTrigger(trigger on external signal, trigger on motion detection, period between frames, pretrigger frames, posttrigger frames): This incoming command enables the trigger mode. One of the pa- rameters trigger on external signal and trigger on motion detection must be given a value. Pretrigger frames and posttrigger frames are by default 0. • ←− StopTrigger: This incoming command disables the trigger mode. • ←− SetGlobalMotionSensitivity(object size sensitivity): This in- coming command is only valid if the cameras motion daemon is enabled. The changes effects all PalCom connections. • −→ Picture(frame): This outgoing command encapsulates a JPEG frame.
4.2 PalCom implementation
4.2.1 Discovery
The server replies to browser multicast and unicast requests, and spontaneously sends its DeviceInfo when starting. All the discovery messages are based on static XML messages.
4.2.2 Selectors
According to the PalCom model selectors are strings. Remote selectors are parsed as such but for the local selectors we have chosen to assign integers as it is easier to handle and does not change anything for the customer. Each service has a statically assigned selector. When a customer sends a connect request to one of those service selectors, a new connection selector is taken and returned to the customer. This selector is chosen as the smallest available positive integer.
27 Chapter 4. A PalCom server prototype on the AXIS 207W
4.2.3 Connections
When the server receives an incoming message on a connection that is already established, it always checks if the sender information (basically the IP address and the remote selector) corresponds to the customer that actually opened the connection. With this strategy, we take care of unwanted scenarios that can occur when one of the parties thinks the connection is still established while it is not. To make it more simple and as the PalCom communication model is probabilis- tic, the thread architecture of the server has been designed in such a way that too many packets may sometimes be sent. For example, it may take around one second between the server receives a disconnect packet and it actually stops sending packets to the customer.
4.2.4 Timeouts
As the PalCom server is meant to run permanently, it is desirable to have a sta- ble server without any memory leak. Moreover, our server comes with a timeout detection module responsible for closing potential zombie connections, whose re- mote device has crashed or left the network without any announcement. Without such a system, resources would never been released, resulting in overloaded CPU and/or out-of-memory issues when several remote devices crashed. A connection is considered zombie when our server has not received any informa- tion from the remote device through the discovery protocol for a minute after a request was sent.
4.3 Module architecture
The modules of our server implementation are divided into three parts. The Pal- Com Base handles the PalCom protocol according to the PalCom model. This is the PalCom specific part of the server. It should be possible to transfer those mod- ules to another device, which does not have to be a camera. The Services modules are guided by user scenarios and handles service design. These are open mod- ules since new services can be added, old services removed or existing services modified. The third part, VAPIX interface, handles the internal communication with the camera. It is a "VAPIX to C converter" and is guided by the VAPIX API. Figure 4.2 explains what files of the code belongs to which of the three parts. The source code can be found at http://www.lucas.lth.se/axis-palcom/.
4.3.1 PalCom base modules
The main() function is found in palcom.c, it calls com_listen_sockets() in communica- tion.c. In communication.c two UDP sockets are opened. One socket for listening to incoming messages from the multicast address and one socket for listening to incoming unicast messages and sending outgoing messages. We listen to both sockets using select(). The received PalCom messages are parsed by calling palcom_parse() in messages.c.
28 Chapter 4. A PalCom server prototype on the AXIS 207W
Figure 4.2: File names and the respective part of the code they belong to.
Figure 4.3: Call graph for most important functions in PalCom base modules
In palcom_parse() the PalCom header is parsed. The sender selector is assumed to be a string of maximum length 10. The receiver selectors, selector addresses in the camera, are always integers since this makes it easier to handle them, see section 4.2.2. The type of the message is checked (data, control, multipart) and the parsed messages are stored in a data structure (pointer structure) explained in figure 4.4.
Depending on the receiver selector, the message (without the palcom header) is then sent to one of three handler functions:
• global_msg_handler(),
• service_msg_handler(),
• connection_msg_handler()
In all three handler functions parse_xml() is called. If a message is of type con- trol or of type data and starting with "
In global_msg_handler() three kinds of PalCom messages are handled. If the mes- sage was a DeviceInfoRequest, we broadcast the camera’s DeviceInfo via mul- ticast, for an example see listings 4.7 and 4.8. If the message was an InfoEvent
29 Chapter 4. A PalCom server prototype on the AXIS 207W
Figure 4.4: Structure used to represent a PalCom packet, result of palcom_parse()
Figure 4.5: Structure used to represent the XML message presented in listing 4.8, result of parse_xml()
30 Chapter 4. A PalCom server prototype on the AXIS 207W
1
2
3
4 Listing 4.7: DeviceInfo request from remote device (Device 116)
with keepInfo="false", i.e. the remote device is about to close down, we update our list of current connections.
1
2
3
4 Listing 4.8: Axis camera’s answer on a DeviceInfo request
If the message was a ServiceListRequest (listing 4.9), we send the cameras Ser- viceList (listing 4.1 in section 4.1).
1
2
If the message was a ServiceDescriptionRequest, we send the corresponding Ser- viceDescription. If for example the request was for the Ping service (listing 4.10), the XML message found in listing 4.2 in section 4.1 is sent.
1
2
Listing 4.10: ServiceDescriptionRequest for PingService from remote device
If the receiver selector was the selector of a particular service service_msg_handler() is called. If it was a Connect message, see listing 4.11, we open a connection, connection_open(), and reply by sending a Connect, see listing 4.12, to the sender service. Connections are stored in a CONNECTION structure in connection.c.
1 240;c;2;1;
2
3
4 Listing 4.11: Connect message to PingService (selector 1) sent from remote device
31 Chapter 4. A PalCom server prototype on the AXIS 207W
1 237;c;6;2;
2
3
4
Listing 4.12: Connect message from established connection in the camera. The connection is between PingService and a service in a remote device and was given selector 6 localy.
If the receiver selector was the selector of an already opened connection connec- tion_msg_handler() is called. Those messages can either be Disconnect messages or specific messages to the service. In the latter case, depending on the service, we either call a service handler function or put a mail in the service thread’s mailbox. See section 4.4 for more information about threads.
4.3.2 Services modules
Figure 4.6: Call graph for most important functions in Services modules
New services are added in the services_definition() function. In this function all information about the services are put. The name of the service, incoming com- mands and outgoing commands and their respective parameters are defined here. For simple services, that only does something once when given an incoming com- mand, such as the PingService and the TimeService, we just call a function. More complex services, such as PictureService with the command EnablePeriodic and the MJpegService and TriggerService, where the outgoing command of the cam- era consists in sending many frames at a specified interval or listening for motion detection signals etc, we start a new thread1 for each service. This is defined in services_open_service() which is called by services_definition().
1pthreads implementation was used for thread management. See section D.1.2 for more details.
32 Chapter 4. A PalCom server prototype on the AXIS 207W
Now, if the message was a specific message to a service connection_msg_handler() was called. Depending on the receiving service, either a message is put in the respective service thread’s mailbox using the function mb_put(), or if the service is simple and has no thread, command_handler() is called. In command_handler() a specific handling function is called, as defined in services_definition(). For the PingService Hello command, the handling function is ping_Hello() and for Time- Service SynchTime command the handling function is time_SynchTime(). See sec- tion 4.4 for more information about threads. picture_handler_t() in picture.c, mjpeg_handler_t() in mjpeg.c and trigger_handler_t() in trigger.c handle messages to the respective Service.
4.3.3 VAPIX module
The camera’s VAPIX API [11] is accessed via HTTP requests. For HTTP the trans- port protocol used is TCP, though PalCom communication is done over UDP. Thus in this module we open a TCP socket to localhost and forward the messages from the Services modules to VAPIX. The messages forwarded can be either a request for setting an internal parameter value in the camera (defined in [12]) or a request for a JPEG frame.
4.4 Thread architecture
Our prototype is a multithreaded server. From a general point of view, we can divide threads into three categories: • The main thread is responsible for handling incoming messages, parse them, and decide what to do with them. It is thus responsible for the discovery protocol, timeout checking, etc. Depending on the complexity degree of the service, this thread does also process some simple, non-blocking com- mands. More complex commands are forwarded to service-specific threads. • The service-specific threads are started at program start up, and are not stopped during execution. Their role is to handle complex services, by keeping track of each connected customer and the current "state" of the con- nection. All the services of our prototype except Ping and Time are man- aged by such threads. • In some situation, a service-specific thread is not sufficient to correctly han- dle event-triggered and time-triggered events at the same time. Other threads are then created/stopped depending on each connection, under the control of a service-specific thread.
4.4.1 Inter-process communication
Inter-process communication between threads can be done in three ways: Semaphores, monitors or mailboxes. The three methods do the same thing, which one to chose is mostly a matter of taste. We have chosen to use mailboxes and have written our own mailbox module.
33 Chapter 4. A PalCom server prototype on the AXIS 207W
This module offers non-blocking and blocking functions to retrieve mails. A spe- cial implementation of the blocking get() has a timeout, allowing the caller to sleep and wait for a message at the same time. A special flag exists, which role is to tell the thread owning this mailbox when to commit suicide. Mailboxes use static size buffers and that can lead to data loss if the buffer is full when trying to put a new message.
34 Chapter 5
Development
In this chapter we describe the hidden part of our prototype, namely the develop- ment. We present the tools involved to test the server, why we ended up with the current solutions and choices, what impact the development had on the PalCom communication model, and we finally conclude by evaluating the development step itself.
5.1 Testing
To test our server, we have mainly used the Handheld device from the Java Pal- Com implementation. Using the Device Factory, it is easy to create scenarios and handle several devices within the same interface.
With the Handheld, it is possible to display all the PalCom devices connected on a network (within the multicast range) and to establish/close connections between any customer service and any provider service. Last but not least, the Handheld is also a flexible customer for any service providing common MIME type objects such as text or images.
We also used another browser currently developed within the PalCom project. It is an Eclipse plugin that is more flexible and offers all the features of the Handheld. New advanced features such as assemblies are also available but we did not use them.
By testing our server with two different browsers yet sharing the same PalCom communication stack, we wanted to be sure the server was flexible enough to handle communication with any device, especially when it deals with behaviour that is not clearly defined by the communication model. We had for example to update our server so that it supports both browsers concerning empty parameters in Commands. The Handheld sends a part for each parameter, even if it is empty, while the Eclipse browser does not send empty part and just omits the dataRef attribute in the Command.
35 Chapter 5. Development
5.1.1 Debugging
The camera does not have an embedded debugger, but it is possible to debug programs remotely. However, since our prototype is a C program using only the standard library and the portable tool expat, it was possible to debug it directly on our Linux workstation, without cross-compiling it first. Calls to camera-specific features are indeed HTTP requests (see section 5.2.1) so our program can run on any Unix workstation, provided that the camera IP is provided in the code. This way, debugging has been much easier and efficient, as our prototype has exactly the same behavior wherever it is run.
5.1.2 Valgrind
Valgrind1 is an open source suite of tools for debugging and profiling Linux pro- grams. As we did for the other debugging (see section 5.1.1), we used valgrind directly on our host Linux workstation in order to detect memory-related prob- lems: wrong size allocation, obsolete pointers, and last but not least, memory leaks. The presence of memory leak is indeed critical in an embedded system for two reasons: • The camera has a limited amount of resources, and a memory leak in a frame buffer could result in crashing the whole system after several pictures has been taken. • If the camera runs out of memory, it may take a while before the user notices it and restarts it. The camera is not considered as a computer by the end- user and has no standard output to signal problems.
5.2 Design choices
5.2.1 Camera-specific features
To code the protocol part of our server, there was no need to access camera- specific functions, as the camera is itself a Linux embedded system, coming with a complete C library. However, to be able to fetch frames or to update the text overlaid on each of them, there were two solutions: 1. As the server runs with root privilege, it is possible to access the most low- level layer to communicate with the hardware. For example, to fetch a frame, one can read a special Unix file, namely /dev/jpeg. 2. As described in figure 3.2, the built-in Web server consists of two different parts. The user-friendly web interface actually relies on another component called VAPIX. VAPIX is the HTTP API common to all Axis Camera models. Each solution has its advantages, and we switched from one to another during the project:
1http://valgrind.org/
36 Chapter 5. Development
1. We first choose to access the hardware through the most low level layer pos- sible. This method is the most efficient one and it is quite straightforward to implement.
2. However, the only documentation we got about this internal API was ir- relevant to our camera model. Axis has deliberately chosen not to support their internal API because they cannot guarantee it will not change from one firmware version to another. On the opposite, VAPIX is fully-documented and Axis provide public support. Using VAPIX instead of the direct access is a little bit more demanding under a resource aspect as it adds a HTTP client/server in between, but VAPIX offers much better flexibility, as all fea- tures are documented and supported, and portability since all Axis cameras flashed with the latest firmware support it.
Another issue with choosing VAPIX is that it requires a login/password each time a request is sent. It is a basic HTTP authentication where the client must send a base64-encoded2 login/password pair that will be decoded and matched on the server side. The earlier versions of the server required the user to change the root password to a static one that our server knew. Not only is this a security hole, but it is quite demanding since the administrator cannot even choose its own password. We updated the installation script and the server code so that it uses a dedicated palcom account instead, but it does not solve the security problem as the password is still static: this password giving root access to any camera equipped with our software can be found unencrypted in the installation script. A possible solution is suggested in section 5.3.2.
5.2.2 Video features
The AXIS camera comes with native support for video: it can stream out MJPEG and MPEG4. MJPEG is suited for video surveillance applications, where it is im- portant to get sharp frames at any time, not to miss a potential break-in. The MPEG4 is perfect for other applications mainly because it requires much less bandwidth. Our first goal was to support both of them, using two different ser- vices, but we finally ended up with only implementing an MJPEG service.
MJPEG
MJPEG normally consists of pushing JPEG frames over a TCP connection. As the PalCom does not yet implement any session-safe protocol3, we choose to im- plement a basic MJPEG over UDP, which is actually nothing more than sending several JPEG frames in a row.
2base64 is a way to encode a sequence of octets in a sequence of printable characters, but this transformation is by nature reversible and is thus not a way to encrypt data. 3A session-safe protocol, such as TCP, is a protocol where a sub-layer is responsible for controlling that packets arrive in the right order, without any packet loss.
37 Chapter 5. Development
MPEG4
The development of an MPEG4 service was much more complex than what we expected. Therefore our prototype does not come with an MPEG4 service. First, it is not possible to send chunks of MPEG4 over UDP without any underly- ing control protocol, because MPEG4 is a stream and any packet loss result may result in a stream corruption and thus unexpected behavior on the client side. Moreover, this strategy would require a client knowing that it has to concatenate packets to reconstruct an MPEG4 stream. The native solution on the camera is to stream MPEG4 over RTP4, which itself relies on UDP. The streaming can be unicast or multicast, and clients willing to connect should retrieve an SDP5 to initiate the connection. Note that MPEG4 over UDP is the only solution supported by VAPIX to get a real video stream. To be able to control this native streaming transparently from a PalCom device, the only solution is to create a sort of proxy inside the PalCom server. Thus, it is possible to hide the RTP packets which are not easy to encapsulate into PalCom packets. The final goal is indeed to be able to stream MPEG4 over a PalCom protocol to be defined. We started to implement such a proxy in streaming.c/h. It is disabled in the code but can be enabled by uncommenting relevant lines in services_definition(). It is currently just an independent thread that forward RTP packets from the na- tive server to an external client. VLC6 is the only open source alternative able to connect to a stream of MPEG4 over RTP that we found. Other media players lacked either MPEG4 support or RTP support.
5.3 Impact of the prototype development on the Pal- Com protocol
5.3.1 Improvements
Connect messages
When a device was asking for a new connection, a simple plain-text connect message used to be sent. As a result, it was impossible from our server point of view to know formally which device, identified by its URN, was the customer of a given connection. As our server may run for a long time and has a limited amount of resources, there was a nice-to-have feature consisting in a clean-up function, keeping track of connections and removing those qualified in the code as zombies, i.e. whose customer crashed. A proposition was made: Connect messages should encapsulate information about the customer establishing the connection. This proposition resulted in a new XML
4Real-time transfer protocol. 5Session Description Protocol, file providing information about address and codecs used for a multimedia stream. 6http://www.videolan.org
38 Chapter 5. Development message aimed to replace the former plain text message. Disconnect messages were left unchanged since they are supposed to come after Connect messages, that have already provided enough information.
Human-readable information in the ServiceDescription
When a PalCom device is used by a user, for example through a browser such as the Handheld, some parameters may be difficult to comprehend. To try to solve this issue, we proposed to extend the ServiceDescription DTD, allowing the de- veloper to give a human-readable information about not obvious parameters. It consists of a help attribute in the Parameter element in the ServiceDescription XML. Our server uses this feature to describe units and default values for several pa- rameters. However, sending an extended ServiceDescription is everything but useful if no other device can use the extended information. Thus, we updated the Handheld accordingly: the user will find a tooltip text containing the description when hovering a parameter. Note that this extension is however not yet part of the PalCom model and is only used by the Handheld. Nevertheless, this exten- sion seems transparent since other devices are not affected, and the Handheld still accept ServiceDescription without the extra attribute.
5.3.2 Open issues
UDP-packet limitation
The PalCom stack uses UDP packets to carry information over the network. The only requirement that the communication stack of a system has to meet to support UDP is to be able to send UDP packets whose size is up to 8K. Nevertheless, this maximal size can vary depending on the system, but this size cannot exceed the theoretical limit which is 64K. In the AXIS camera, it is possible to send packets up to 32K with the current firmware version. A PalCom message cannot be transmitted over several UDP packets. That means that the UDP-packet size limit also determines the maximal size for PalCom mes- sages. This is an important issue when it comes to sending pictures inside those packets: our server cannot send high resolution, low compressed JPEG pictures. A protocol allowing a device to send a PalCom message over several UDP packets is being developed in the computer science department at University of Aarhus, Denmark.
Default values for incoming parameters in ServiceDescription
We noticed that having a default value for each parameter would greatly im- prove the user experience. For example, a user using the Handheld to set up the local time of the camera should get the current time as the default value, so that he does not have to type in the whole date and worry about the format. This default value could be given in ServiceDescription as another attribute of the
39 Chapter 5. Development
Parameter (as the help described in section 5.3.1). This default value will be static, set to the value defined at a given time in the ServiceDescription, but would still be better than an empty parameter.
Authentication
As of today, the PalCom model has no notion of authentication. As a result, when a device reboots, two devices can try to reach it on the same connection selector, which can result in unexpected behaviours. There were lots of reboots during testing, so we decided to check the remote IP and the remote selector. In case they don’t match with the ones saved when the connection was established, the command is not processed. The standard behaviour should probably be defined so that it would also be possible to send a Disconnect message in order to tell the remote device that something is wrong and that a new connection must be established.
Another possible improvement concerning authentication would be to protect connections by password protected accounts. In the next version of the PalCom model, there will probably such a solution, where the password is given in the Connect messages. This would help to solve our security problem described in section 5.2.1. Special actions that should not be performed by every user, such as changing the time or the picture settings will require the remote device to send a valid password. Thus our server prototype would not need to store any pass- word.
XML type
When receiving a message, our prototype parses it as an XML when it starts with
Remote Selector Length
Even if we decided that the local selectors for our prototypes were numbers, re- mote selectors have to be parsed as strings according to the PalCom model. How- ever, no maximal number of characters is defined, and for simplicity reasons we choose to assume that selectors were no more than 10 characters long7. A maxi- mal number of characters should be defined in the future definitions of the Pal- Com model, and the constant changed accordingly in the code.
7constant SELECTOR_STRING_LENGTH in the code.
40 Chapter 5. Development
5.4 Evaluation
5.4.1 Developing a server for an AXIS Camera
Developing a server for an Axis Camera is not so difficult. One must know C, C++, or any other language with a cross-compiler to ARM architecture, and how to set up the cross-compiler, but apart from that, the development is not different from a non-embedded system project. Thanks to the common standard library, the ability to debug and profile the program directly on the host machine was a real advantage during development. The AXIS 207W has 32MB of RAM and a fast CPU, which makes deep optimisa- tion unnecessary. There has not been any optimisation step during the develop- ment. Using a low-level programming language, coding with adequate buffers and avoiding polling or other cpu demanding trick is fairly enough to build a robust server. Modifying system files so that the PalCom daemon is started automatically is probably the most specific and technical part, as it has to be done via an installa- tion script. This installation script patches critical files on the camera, whose con- tent is unknown and depends on the current configuration of the camera and/or its firmware.
5.4.2 PalCom in a small device
Among all the developing tasks, implementing a minimalist version of the Pal- Com communication stack was the most interesting one. Relying on the papers describing the PalCom model was not enough because as a research project, the model is constantly evolving. Complying to the Java implementation was our main task, as this implementation is the most supported one. The PalCom protocol module itself is run by one thread, and requires a really small amount of memory, as the only dynamic information to be saved is the list of connections. We choose to keep track of the devices in order to detect zombie connections, but the overhead is small and can be removed anyway. The most demanding task for our server is for sure to parse XML messages. For example, the same discovery messages are entirely parsed at a quite high fre- quency: this could be improved if there was a necessity for our prototype to run on a slower embedded device by parsing only relevant parts with low-level func- tions instead of calling the external XML library expat.
41
Chapter 6
Conclusions
During this master thesis, we have successfully implemented a PalCom server prototype for the AXIS 207W network camera.
6.0.3 Evaluation of the prototype
The prototype is written in ISO C and uses one external library, expat. Although it does not have all the possible features such as MPEG4 streaming, it is stable and quite efficient. It takes from 2% to 10% of the CPU depending on the number of connections established, and requires around half a megabyte of RAM during typical use. Our prototype comes with an installation script that makes it easy for a user with some background in Unix systems to install it on any AXIS 207W camera. Once installed, our server takes only 404kB, which corresponds to only 20% of the total available space for user programs and scripts.
6.0.4 Comparison with the built-in HTTP server
Since the camera comes with a built-in HTTP server, it is interesting to compare it with the prototype. First of all, unlike the built-in HTTP server, a commercial Axis camera has to be patched with the PalCom server in order to become a PalCom device. This re- quires a Unix workstation and a computer science background, which may bridle the deployment of the prototype. This could be improved by developing an auto- matic installation script running on a popular operating system such as Windows or MacOS X. Once the installation step is done, the PalCom server seems to behave better than the HTTP server when concerning usability. There are of course fewer features in the PalCom server, but those features seems to be more straightforward to use. When it comes to protocols to find a device and use one of its service, PalCom turns out to be the easiest since it is an "All-in-one" server, as opposed to use both its built-in UPnP and HTTP interface.
43 Chapter 6. Conclusions
Finally, the PalCom server is by nature more flexible than the HTTP server. While the HTTP server has static, hardcoded standards, the PalCom server can be in- volved in various scenarios where devices just have to support PalCom to com- municate together.
6.1 Future work
This work can be the starting point of other projects. In this section, we will briefly discuss possibilities for this.
6.1.1 Maintaining the prototype
As PalCom is still under research, the communication model is meant to change. Therefore the prototype has to be maintained until the PalCom model reaches a stable phase. Without support, the prototype will not handle further modifica- tions of the protocol, and will most likely become useless.
6.1.2 Alternative implementation based on PalVM
Given the relatively large resources offered on the camera, it is possible to di- rectly port the existing Pal-VM1 using a light virtual machine cross-compiled to the ARM architecture of the camera. Erik Corry from Aarhus has sucessfully done this. A Java/Smalltalk version of the Axis-PalCom server could thus be implemented.
6.1.3 Reusing the prototype’s PalCom modules
As described in Appendix B, the prototype has been designed to be modular, so that the code specific to the Axis camera could be removed. Instead of starting from scratch, PalCom developers willing to develop a server for another device may use the C basis from the prototype.
6.1.4 Develop an MPEG4 service
The built-in support for streaming MPEG4 over RTP may be reused in the Pal- Com server. MPEG4 streaming requires a session-safe channel that the PalCom model currently lacks. Once such a standard is defined, it will be possible to implement an MPEG4 service using a sort of RTP proxy that would encapsulate MPEG4 frames inside PalCom packets.
1PalCom virtual machine
44 Appendix A
User Manual
The PalCom server is a third party software that can be installed on the AXIS 207W network camera1. Installed on the appropriate model and firmware, the server is considered as sta- ble and is compliant to the current PalCom communication model (December 2006). It has however some known limitations (see section A.4). Please note that the server comes with no warranty, and that no support is provided by Axis. This document is both an installation guide and a short reference (section A.3).
A.1 AXIS 207W Quick Guide
This section is a quick start-up guide. It is not meant to substitute the AXIS User Manual, but rather to give a practical introduction to a PalCom user who wants to use the camera, with the PalCom server, as fast as possible. Note that this step requires some knowledge about Unix systems, as the installa- tion procedure can only be run from a host running a Unix operating system.
A.1.1 Hardware Overview
Power Power can be provided either by the power supply or by the terminal connector pins (see below). LED indicators The camera has four indicators: Status the outer ring around the camera CCD. Green when the camera is ready, amber on boot time, red on problem. Power supply second light from left to right at the back of the camera. It should be green when power is connected.
1Other cameras from Axis might also be supported, such as the 207 or the 207MW, and possibly some other cameras based on the same architecture
45 Appendix A. User Manual
Ethernet (Wired network) first light from left to right at the back of the camera. Unlit when there is no wired network connection, or when the camera is in wireless mode, flashes when information is sent or received through the wired network. Wireless first light from left to right at the back of the camera. Green when connected to an access point, red otherwise, flashes for activity. Reset button To reset the camera to its factory defaults, use the small circular black button on the back of the camera, between the network indicator and the power indicator LEDs: 1. Turn the camera off by unplugging the power supply. 2. Press the reset button and keep it pressed. 3. Reconnect the device with power supply. 4. Release the reset button when the status indicator becomes amber. 5. Wait until the status indicator becomes green. I/O connector pins There are four external pins, from left to right: 1. Ground. 2. Auxiliary DC Power. Can be used to supply power to the camera. 3. Digital Input. Can be used to trigger the PalCom server from an ex- ternal electronic source (see section A.3.5). Leave floating to disable, connect to ground to enable. 4. Open-collector digital output. Not relevant for the PalCom server. Focus ring Around the CCD, turn it manually to adjust the focus.
A.1.2 Network
Ethernet or Wireless By default, if an Ethernet cable is plugged, the wired in- terface is used, even if an accessible wireless network has been detected. Please refer to the AXIS User Manual to learn more about network configu- ration. DHCP or static IP By default, the camera will ask for a dynamic IP provided by a DHCP server. A static IP could be set up using the web interface (see AXIS User Manual), or using specific commands on a Unix workstation connected to the same local network. To set up the camera with a given MAC2
and restart the camera, keeping your terminal open until the camera replies to the ping. Note that this commands must be issued within 2 minutes of connecting power to the camera.
2serial number written on the back of the camera (for example: 00:40:8c:18:10:00)
46 Appendix A. User Manual
A.1.3 HTTP server and root password
Once the camera is connected to a network and is replying to a ping, you will have to set up a root password. Open a HTTP browser and type in http://
A.2 Install the PalCom server
A.2.1 Requirements
Firmware 4.40 The PalCom server requires firmware 4.40 to run properly. This was the latest public version available when writing this User Manual. Later versions should also be supported, but it is safer to upgrade/downgrade to 4.40. You can check the current version using the HTTP server (Setup), and install a new one if necessary. To do this, you will have to download the firmware from the Axis website3 and flash the camera (System Options > Maintenance > Upgrade Server). IP and root password of the camera As explained in sections A.1.2 and A.1.3. A Linux, UNIX or BSD workstation The computer you install the server from must have a Unix shell and ftp client compliant with the .netrc file. If it does not, you will have to look inside the installation scripts in order to install each file and run each script manually.
A.2.2 Step by step
1. Run $ install.sh
where
Remember that a telnet session is not safe, and that this operation should be done within a safe, isolated network.
3http://www.axis.com/techsup/cam_servers/cam_207w/firmware.php
47 Appendix A. User Manual
4. The camera will reboot and the PalCom server should now be available. You should decrease the resolution to 352x288 to prevent the image size limitation (see section A.4).
A.3 Using the services
The camera with the PalCom server provides five services. To describe them, we will give brief examples and provide screen shots taken from a GUI browser from the Java implementation. Note that this browser is able to parse information about parameters included in the Axis PalCom server service descriptions and display it as a tooltiptext.
Each customer service that is connected to the Axis camera has its own settings. For example it is possible to have two connections on the same service from two different devices, with a different period. However, some resources are global and are shared among all the connected customers. That means that changing such a parameter from one connected customer will result in changing it for all of them. Such resources are defined by commands whose name contains Global.
A.3.1 Ping Service
This service is mainly used to test that the setup of the camera and the network is OK. When a Hello command is received the camera sends back its time.
Figure A.1: Screenshot of the handheld browser connected to the Ping Service
48 Appendix A. User Manual
A.3.2 Time Service
You can try to set up the date and time to 2006-12-24 15:00:00 using the SynchTime button in the Time service (see figure A.2).
Figure A.2: Screenshot of the handheld browser connected to the Time Service
Using the Ping service (see figure A.1), you can ask for the local time on the cam- era by clicking on the Hello button, and thus checking that the previous com- mand was successful. Update the local time on the camera. Fill in the time parameter in the format "YYYY-MM-DD HH:MM:SS" and send the SynchTime command. Sending the com- mand with an empty parameter results in putting the camera in NTP mode i.e. if there is a gateway to Internet, the time is retrieved from a time server.
A.3.3 Picture Service
The simplest way to use this service is to click on TakePicture (see figure A.3). To ask the camera to send frames periodically, fill in the period in milli seconds (for example 1000) in the period field and press the EnableTrigger button. You may choose to add a text and change resolution and compression of the pic- tures (see figure A.4). Set the compression field to 20, the resolution field to 352x288, the text field to "The time is now: %T" and press the SetGlobalPa- rameters button to update the settings. The next frame you will receive should contain the text with the time. This service sends JPEG frames and modify the cameras image settings. There are three commands: TakePicture To get latest frame from the camera.
49 Appendix A. User Manual
Figure A.3: Screenshot of the handheld browser connected to the Picture Service
50 Appendix A. User Manual
Figure A.4: Screenshot of the handheld browser connected to the Picture Service
EnablePeriodic / StopPeriodic To get frames periodically. An example is shown in figure A.4. • Fill in the period parameter (in milliseconds) with values from 100 to 10000. • Optionally fill in the start parameter in the format "HH:MM:SS". The camera will start sending pictures immediately or if a time is speci- fied the first frame will be sent at this time. You can thus program a periodic sending of pictures up to 24 hours in advance. • Start the periodic operation or synchronize it with the current time using the command StartPeriodic with its parameters, and stop it by sending the StopPeriodic command. SetGlobalParameters To set new parameters globally in the camera. Changes also effect the MJPEG service. • Optionally fill in the Compression parameter with values from 1 to 100. Beware of the image size limitation (see section A.4). If you up- date the settings without filling in this parameter, the previous com- pression setting is kept. • Optionally fill in the Resolution parameter with one of thoose resolu- tions: 640x480, 480x360, 352x288, 320x240, 240x180, 176x144, 160x120. Beware of the image size limitation (see section A.4). If you
51 Appendix A. User Manual
update the settings without filling in this parameter, the previous res- olution setting is kept.
• Optionally fill in the Text parameter: any text string where %F gives the date and %T gives the time. If you update the settings without filling in this parameter, the text is disabled.
• Send the SetGlobalParameters command with its parameters to up- date the settings.
A.3.4 MJPEG Service
With this service, you can receive a stream of JPEG frames, (see figure A.5). Press the ShowVideo button to subscribe to the stream. You may change the framerate: set the frames per second field to e.g. 10 and press the SetGlobalFrameRate button.
Figure A.5: Screenshot of the handheld browser connected to the MJPEG Service
This service sends a continuous stream of JPEG frames, which is sometimes ref- ered as Motion JPEG, or MJPEG. It can be quite demanding for the customer, es- pecially if the compression is low, and the resolution is high.
ShowVideo and StopVideo Send those commands to subscribe, respectively un- subscribe, to an MJPEG stream.
SetGlobalFrameRate Fill in a frame rate in frame(s) per seconds, from 1 to 30, and send the SetGlobalFrameRate command to globally update the frame rate.
52 Appendix A. User Manual
A.3.5 Trigger Service
With this service you can ask the camera to send frames only when an event occurs.
Figure A.6: Screenshot of the handheld browser connected to the Trigger Service
Set the trigger on external signal to up and press the EnableTrigger button. If you short-circuit pin 1 and 3, you get a frame. This can also be done virtually via the HTTP interface, see section A.3.5 Motion detection is another event this service can trigger on (see figure A.6). Set the object size sensitivity to 10 and press the SetGlobalMotionSensitivity. Thus, even a small movement will trigger the motion detection. Write anything in the trigger on motion detection field and choose a period of 10000 ms. Press the EnableTrigger button: frames will be sent every 10 s as long as the camera detects motion. This service sends frames according to an event-trigger scheme. The events which the service can trigger on are motion detection and state changes in the external digital input (see section A.1.1). The customer can choose to trigger on one or the other, or on both. The external digital input can also be set via the build-in HTTP server4. The service provides prebuffer and postbuffer features, which means that you can choose to receive frames from respectively before and after the event. EnableTrigger and StopTrigger When a trigger has been enabled via the En- ableTrigger command, it starts in Pre-trigger mode. Once an event is re-
4http://
53 Appendix A. User Manual
ceived, it switches either to In-trigger mode if the event is motion (see fig- ure A.7) or directly to Post-trigger mode if it is external (see figure A.8). In both cases, all the potential frames cached in the pre buffer are sent at once. In the motion case, frames are then sent periodically until the motion stops, then it switches to Post-trigger mode. The Post-trigger mode lasts until all the number of wanted post trigger frames have been periodically sent. It then swiches back to Pre-trigger mode, waiting for a new event. The trigger is stopped by sending a StopTrigger command.
Figure A.7: Example of trigger on motion detection with 3 pre-trigger frames and 4 post- trigger frames.
• Fill in at least one event to trigger on. To trigger on motion detection, set the trigger on motion detection parameter to a non empty value (for example any character is fine); to trigger on the external signal, set the trigger on external signal parameter to "up", respectively "down", if you want the service to trigger when the state goes from disabled to enabled, respectively from enabled to disabled. Note that you can choose to trigger on both motion and external. • Fill in the period (in milliseconds) with a value from 100 to 10000. This period applies for pre-trigger if the number of frame is not null, post- trigger if the number of frames is not null, and in-trigger if motion detection is enabled. Note that this parameter is irrelevant and can thus be left empty when the trigger is external-only, without pre or post trigger frames, as only one frame will be sent at each external event. • Optionaly fill in the pre-trigger frames parameter with a value from 0 to 5. The default value is 0. • Optionaly fill in the post-trigger frames parameter with a value from 0 to 100. The default value is 0.
54 Appendix A. User Manual
Figure A.8: Example of trigger on external signal with 3 pre-trigger frames and 8 post- trigger frames.
SetGlobalMotionSensitivity Fill in the object size sentivity parameter with a value between 1 and 100 and send a SetGlobalMotionSensitivity command to update the threshold of the motion detection. The higher this value is, the bigger the object must be to trigger a motion detection event. You may probably want to choose values around 20 for common use. This setting is global.
A.4 Known limitations
Limited picture size It is currently impossible to send frames larger than 32Kb5. As a result, with highest resolution(640x480) compression must approxi- mately be greater than 40 or with highest compression (1) resolution must approximately be 320x240 or less.
5This is due to the current PalCom model that have no protocol (yet) to transmit information over several UDP packets
55
Appendix B
How to reuse our code for another PalCom server
This chapter is for developers willing to reuse our C implementation of the Pal- Com architecture for another device. The code was designed to be as flexible as possible, so the current implementation can be the base of any PalCom device, as long as it has only provider services. This guide is practical, and assume that the reader has read section 4 and is familiar with the general structure of the code. Files that are necessary to implement a new server are the files from the PalCom module and service.c/h.
B.1 Active and passive services
Depending on each service, the processing of incoming commands can be ex- ecuted within the main thread or by a dedicated thread. For each service you want to implement, you will have to decide whether it really requires a specific thread and code it accordingly.
B.1.1 Passive services
Those services are the most simple ones, as TimeService and PingService in our prototype. In such services, there are no command that require a dedicated thread. All you need to do is to write one function for each incoming command.
B.1.2 Active services
These services are more complex. First, you have to write a thread receiving PalCom incomming commands (MT_PARSED_PALCOM) and information about con- nections (MT_CONNECTIONS). For the latter, linked list functions (servconn_*) are available in service.c.
57 Appendix B. How to reuse our code for another PalCom server
Depending on the nature of each command, this thread could process itself in- coming orders, as the handler for the MJPEGService (mjpeg_handler_t()), or delegates to another thread that it manages, as the periodic commands in the PictureService (picture_Periodic_t()).
B.2 Check-list
There are some important points one has to check to port the server to another device. This section tries to list the most important ones: • Update the Makefile: new files, compiler, DEBUG_OBJS list... • Change the DeviceInfo templates in messages.h to change the name of the device. • Change info_hostname() : the server must have a unique ID, and taking the hostname may not work when several servers are started on the same system. • Change paths in palcom.c if the program is not run as root. • Check that the number of commands and parameters are correct in calls in services_definition(). There is no error checking at this level, and this could crash the whole server. • Check that all the handlers for active thread free mails after processing, us- ing mb_free_mail()
58 Appendix C
How to develop on the camera and tools needed
C.1 Build the ARM cross compiler on your host
1. Make sure you have the following tools available on your linux system: gcc and its standard libraries, make, bison and flex. 2. Untar the archive comptools-arm-1.20050730.1.tar.gz 3. Choose an install-path (/usr/local/arm for example) 4. $ install-arm-tools install-path 5. Add install-path/bin to your $PATH (e.g. /usr/local/arm/bin ), updat- ing /etc/environement.
C.2 Cross compilation
Use the following flags to cross compile : CC = arm-linux-gcc ARCHFLAGS = -march=armv4 -mtune=arm9tdmi CFLAGS = -Wall -Wshadow -O2 -c LDFLAGS = -static
PROG = hello OBJS = hello.o all: $(PROG)
%.o: %.c $(CC) $(ARCHFLAGS) $(CFLAGS) -o $@ $<
$(PROG): $(OBJS)
59 Appendix C. How to develop on the camera and tools needed
$(CC) $(ARCHFLAGS) $(LDFLAGS) -o $@ $^ clean: rm -f $(PROG) *.o core
C.3 Transfer a file to the camera
1. $ ftp
C.4 Telnet
To start the telnet server on camera, there are two ways : • FTP : 1. $ ftp
5. ftp> put etc/inittab • Web interface : 1. Setup->System Options->Advanced 2. click on the button "Open script editor" 3. click on inittab 4. uncomment the following line in inittab : tnet:35:once:/usr/sbin/telnetd
5. Save Finally, reboot the camera: either switch the power off and on or via the webpage Setup->System Options->Maintanance and click the button "Restart". A shell can now be given by invoking the command $ telnet
60 Appendix D
Tools used
D.1 Libraries used
D.1.1 XML-parser: Expat
Expat[8] is an XML library written in C that provides stream-oriented parsing. It is one of the most efficient and fastest parsers and is widely used, for exam- ple in the Mozilla project, Apache or as a base for the Perl wrapper XML::Parser. To cross compile it for our ARM-based architecture, we used the following com- mand: ./configure CC=arm-linux-gcc host arm-linux CFLAGS='-march=armv4 -mtune=arm9tdmi' LDFLAGS='-static -static-libgcc'. As a stream oriented parser, Expat should be given handler functions that are called sequentially as the document is browsed. This is mainly done by us- ing XML_SetElementHandler and XML_SetCharacterDataHandler. The two other important functions are XML_ParserCreate and XML_Parse that respectively ini- tialize the parser and start the processing.
D.1.2 Pthreads
From the system point of view
POSIX threads is a UNIX programming interface standardized in 1995. It consists of a set of structures and functions that provide multithreading programming ability, i.e. to run several stack and scheduler independant entities within the same process (theoretically), using the clone() command. Parallelism could also be achieved by using several processes thanks to the fork() command, but this solution is 10 to 1000 times slower because of each process overhead at creation, and makes the synchronization between the parallel tasks difficult as they do not share the same adress space. Since the 2.6 version, the GNU/Linux kernel uses the Native POSIX Thread Library implementation. Though, each thread is actually a kernel process (the smallest
61 Appendix D. Tools used
GNU/Linux schedulable entity), and the library emulates threads by providing address space sharing. The NPTL implementation is now part of the GNU C standard library, glibc, making it very straightforward to use.
From the programming point of view
Pthread provides all the common objects one can expect from a thread library for basic use: thread creation and joining, mutexes and condition variables. The flag -pthread should be used when invoking gcc, both at compilation and linking steps. The notable points are the following: • Thread start: a thread is started by calling a function of the pthread library. Once initialized, the thread needs a function to "work", and this function should take one and only one argument. This argument is (void *) so the best way to pass data to a starting thread function is to allocate a structure and cast it to (void *). As the information is passed by reference, it can lead to synchronisation issues and should not be accessed anymore in the calling thread. • Mutexes and condition variables: these common synchronization objects are actually C structures, so they need to be initialized. This can be done statically, using special constants1 or dynamically, to set special object at- tributes.
D.2 Software used
D.2.1 Eclipse SDK
As the Eclipse SDK[4] is used for the PalCom development, we realized it would be better to use it as well for maintaining issues. Eclipse SDK is mainly aimed to assist Java Programmers, but its community has developed several tools that provide other languages support.
C/C++ Environnement
The CDT (C/C++ Development Tools) Project[5] has released an environnement to code in C/C++ inside Eclipse, providing: • Advanced source editor • Debugging facility • Project-oriented management • Content assistants This plugin is available as a source archive to compile or as packages for several distributions (Debian/Ubuntu for example).
1PTHREAD_MUTEX_INITIALIZER and PTHREAD_COND_INITIALIZER
62 Appendix D. Tools used
Additional plugins and tools
GNU Indent frontend The CDT community provides a frontend plugin to easily use the GNU indent tool. Once both indent and the frontend are installed, source formatting is available inside the source editor. Eclox Eclox[6] provides user-friendly doxygen configuration setup inside Eclipse and is available easily using the Eclipse Software Manager.
D.2.2 Doxygen
Doxygen[3] is a Javadoc-like documentation generator. It supports many lan- guages, including C, and generates HTML and LaTeX code documentation. It is possible to generate on-line call graphs. Such graphs are really convenient to summarize the relationships between the functions of different modules and also in our case to check which functions must be thread safe. We used to use egypt[7], a Perl script that can generate one call graph for the whole project, but its use became difficult as the project was growing. We found that Doxygen was a better alternative, especially because the latter can generate not only a call chain, but also a caller chain, so that the reader can see where a given function is called from.
63
Bibliography
[1] Axis Communications - Network cameras. http://www.axis.com/ products/video/camera/, 2006. [2] PalCom External Report no 9: Deliverable 11 (8.1). [3] Doxygen. http://www.stack.nl/~dimitri/doxygen/. [4] Eclipse.org home. http://www.eclipse.org/. [5] Eclipse C/C++ Development Tooling - CDT. http://www.eclipse.org/ cdt/. [6] Eclox. http://home.gna.org/eclox/. [7] egypt - create call graph from gcc RTL dump. http://www.gson.org/egypt/ egypt.html. [8] The Expat XML Parser. http://expat.sourceforge.net/. [9] David Svensson. Palcom Working Note #75 Status of the Communication Component, 2006. [10] David Svesson. Support for Ad-Hoc Applications in Ubiquitous Computing, Licentiate Thesis, 2006. [11] AXIS VAPIX API - Interface Specification. http://www.axis.com/techsup/ cam_servers/dev/cam_http_api_2.htm. [12] AXIS VAPIX API - Parameter Specification. http://www.axis.com/ techsup/cam_servers/dev/cam_param_2.htm.
65