The Zap Channel Module provides an interface layer between Asterisk on the one side, and the Zaptel interface drivers on the other side. These drivers, in turn, provide the ability to use interface cards to connect your PBX to traditional digital and analog telephone equipment:

Asterisk <--> chan_zap.so <-> zaptel.ko (kernel) <-> device driver <-> Zaptel device <-> Phone/switch/PSTN

• /etc/asterisk/zapata.conf - configuration file of The Asterisk Zaptel channel (chan_zap.so) is configured through . This is generally the first place to look for configuration.
• /etc/asterisk/users.conf - Some configuration options from Zapata.conf may also be used in users.conf.
• /etc/zaptel.conf - Some lower-level configuration applied directly to spans and channels.
• Specific kernel parameters can be used to change the behaviour of drivers.

Using the Dial Command with Zap Channels

Recall that the format of the Dial command is like this:

   Dial(type/identifier,timeout,options)

For Zap channels, the type is always Zap. The timeout and options parts are explained on the Dial page.

The identifier parameter can be made up of a number of parts. It can be a little complex:

   chanspec[c][d][rcadence][/phonenumber]

• chanspec: specifies which Zap channel or channel group, as defined in the configuration file, you want to use. It can be one of three types:
  • one of the letters g, G, r, or R followed by a Zap channel group number. See "Dialing a Group", below.
  • for analog Zap interfaces: a simple channel number. Example: 1 means Zap channel 1.
  • for PRI Zap interfaces: a span number, then a hyphen, then a port number. Example: 1-2 means Zap span 1, port 2.

• If the letter c follows, then "Answer Confirmation" is requested, in which the call is not considered answered until the called user presses #.

• If the letter d follows, and the channel is an ISDN PRI channel, then the channel will be "made digital", whatever that means. If you are not getting ringing/busy feedback on your PRI, using the 'd' option may fix your problem!

• If the letter r and a number follow, that number specifies which "distinctive ring" style to use. See "Distinctive Ring Styles", below. Note that specifying a distinctive ring makes sense only when you are ringing an internal extension (e.g. the channel is connected by an FXS interface).

• phonenumber, if present, specifies which telephone number you wish to be connected with. Note that this makes sense only when you are dialing a telephone line (an FXO or PRI interface), not an internal extension. Within the phone number, you may use the special modifier w to indicate a half-second pause. You might want to use this to wait for a dialtone or for a pause while dialing digits. "w would normally indicate a "wait", but putting it at the end of your dialstring will cause asterisk to assume the number before is "complete"."(sic! ~markster). This is usefull if you have the situation of calls where the cdr-records are truncated due to outbound overlapdial. You may also use the special modifier c to allow for clear channel connections between PRI ports.

Here are some examples of complete Dial commands as they might appear in your Dialplan:

   exten => s,1,Dial(Zap/1)            ; Ring extension on channel 1
   exten => s,1,Dial(Zap/1r2)          ; Ring extension on channel 1 with distinctive ring #2
   exten => s,1,Dial(Zap/1,30)         ; Ring extension on channel 1 with 30 second timeout
   exten => s,1,Dial(Zap/2/5551234)    ; Dial 5551234 on channel 2
   exten => s,1,Dial(Zap/2c/5551234)   ; Dial 5551234 on channel 2 with answer confirmation
   exten => s,1,Dial(Zap/2/ww5551234)  ; Wait 1 second then dial 5551234 on channel 2
   exten => s,1,Dial(Zap/2/5551234w)   ;  Assume the number is complete, then dial 5551234 on channel 2
   exten => s,1,Dial(Zap/g1/5551234)   ; Dial 5551234 on the first available channel in group 1
   exten => s,1,Dial(Zap/1-2/1234)     ; Dial 1234 on span 1, port 2
   exten => s,1,Dial(Zap/1-2/c1234)    ; Dial 1234 on span 1, port 2, with PRI clear channel option

Dialing a Group

In the Zap Channel Module's configuration file (zapata.conf), you can define groups of Zap channels that get treated as a single channel as far as the Dial command is concerned. You specify which of four methods the Zap channel module is to use to select a non-busy channel from the channel group by prefixing the group number with one of the letters g, G, r, or R:

• g: select the lowest-numbered non-busy Zap channel (aka. ascending sequential hunt group).
• G: select the highest-numbered non-busy Zap channel (aka. descending sequential hunt group).
• r: use a round-robin search, starting at the next highest channel than last time (aka. ascending rotary hunt group).
• R: use a round-robin search, starting at the next lowest channel than last time (aka. descending rotary hunt group).

The round-robin searches make the Zap channel module start looking for an available channel from a different channel number each time. For each channel group, the Zap channel module keeps track of the last round-robin start point, and this time starts checking availability from either the next (lowercase r)) or the previous uppercase R channel in the group. Which channel it actually finds available (if any) does not affect the starting point for the next round-robin search. Calls to the Dial command using ordinary (g or G) group selections do not affect future round-robin starting points either.

For example, if you have defined channel group 2 as containing Zap channels 1, 2, 5 and 8, and the last round-robin search for this group (group 2) began searching from channel 5, this is the order of searching that the Zap channel module will use for the four possible selection methods:

• Dial(Zap/g2...): Looks in order 1, 2, 5, 8
• Dial(Zap/G2...): Looks in order 8, 5, 2, 1
• Dial(Zap/r2...): Looks in order 8, 1, 2, 5
• Dial(Zap/R2...): Looks in order 2, 1, 8, 5

Distinctive Ring Styles

The four distinctive ring styles that the Zaptel driver can generate when ringing a Zap-connected handset are:

1. Quick chirp followed by long ring
2. British style ring
3. Three quick chirps
4. Short ring followed by long ring

If you do not specify any distinctive ring style, then the ring style used depends on your the country code specified by defaultzone in your Zaptel configuration file, zaptel.conf. The default ring style for a particular country setting may be one of the above four, or it may be a fifth style.

NOTE: You can also add you own custom ring styles by adding cadence= lines to your zapata.conf file.

• The format for the cadence command is ontime,offtime,ontime,offtime .... etc in ms.
• A negative number indicates where to place the Caller ID spill.
• The new ring styles will be assigned 'r' numbers from 1 and up depending on how many cadence= lines you have; they replace the default definitions. (This may only apply to 1.2.x or later.)
• Ring styles can also be hard coded in asterisk by editing chan_zap.c.

Zap ring styles are NOT defined anywhere in the Zapata source.

NOTICE: The ring styles (and also the defintion of the "dialtone", "busy", "ringing", etc tones) are defined by the Zaptel driver. You can not change the definitions without recompiling the zaptel driver (see Zaptel Installation). The settings in your indications.conf file do not have any effect on the tones and ring styles generated by the Zaptel driver.

Detecting Distinctive Ring on Incoming Calls

Your telco may let you use the one analog telephone line for several different phone numbers. Your telco will make your incoming lilne ring in different ways depending on which number the caller dialed.

The Zap channel module can be configured to detect up to three different distinctive ring styles in addition to your normal ring pattern. First of all, you must enable distinctive ring detection by setting usedistinctiveringdetection=yes in your zapata.conf file. Then you can use the dringn and dringncontext keywords to describe (a) the pattern of ring cadences your telco uses, and (b) which context a call matching that cadence should go into. Calls not matching any of your defined distinctive ring styles go to the regular context you defined for this channel.

The distinctive ring detection feature is still rather experimental. Apparently it assumes that if your telco provides distinctive ring, you must also be getting caller ID, which is of course an invalid assumption. If you are in the US, you may have more success with distinctive ring detection than the rest of us.

Note that enabling distinctive ring detection will mean that Asterisk will have to let the phone ring a two or three times to see what kind of ring style it is using. Only after it has done that will it ring your handsets. So you may think you've answered the phone after the first ring, but your callers will tell you that they heard a ringing signal maybe four times before you picked up.

You describe a distinctive ring pattern to Asterisk by giving it three integers. Apparently the only way you can find out which numbers to use is to enable distinctive ring detection and then enter the Asterisk console in verbose mode. When a call comes in, Asterisk will apparently report the three numbers it sees as representing the ring tone it heard, and you can use these numbers in a dring definition. If you discovered that the three numbers it reports are: 325, 95, 0, then you would put this into your zapata.conf:

   usedistinctiveringdetection=yes
   dring1=325,95,0
   dring1context=mycontext

If you have multiple distinctive ring styles, you may add entries for dring2 and dring3.

Here are some ring patterns other people have suggested:

• 95,0,0
• 325,95,0
• 367,0,0
• 247,0,0

SBC\Wisconsin uses the following:

• 337,0,0 - Distinctive Ring 1
• 337,312,0 - Distinctive Ring 2

They may use them in other states as well, report back here and let us know!

For Australian users, who have Caller ID enabled and Distinctive Ring, you might find that asterisk cannot detect your distinctive ring. This is logged in the issue tracker as bug 1007 (and bug 3596). There is a patch available attached to bug 3596 to enable this, but cant be added to asterisk because the author of the original patch is unknown and the there isnt a disclaimer for the patch from the author. If there is somebody who could write the patch again (it may need improvement) and submit the required paper work to the asterisk developers, this would be great :)

Names of Established Zap Connections

When you have an established Zap connection, its channel name will be in this format:

   Zap/channel-instance

channel is the channel number and instance is a number from 1 to 3 representing which of up to 3 logical channels associated with a single physical channel this is.

   Zap/1-1  First call appearance on Zap channel 1
   Zap/3-2  Second call appearance on Zap channel 3

Note that using the ChanIsAvail command will return channel names in this format.

The Cut command can be useful for extracting the channel type from a full channel name. Let's say that the variable Foo has the value "Zap/1-2":

   Cut(ChannelType=Foo,/,1)

Now variable ChannelType has the value "Zap". You could use the GotoIf command to check that a channel is a Zap channel:

   GotoIf($[${ChannelType} = Zap]?10)

If you wish to extract just the channel number from a channel name, you might use two Cuts. If variable Foo has the value "Zap/1-2", then after these steps, variable Bar will have the value "1":

   Cut(Bar=Foo,/,2})
   Cut(Bar=Bar,-,1)

Built-in Extension Numbers

There are some "extension numbers" that are built into the Zap channel module. You may override these in your Dialplan, i.e. these are used only if the number dialed does not match any of your Dialplan extension patterns.

Some of them will only be used if a specific configuration option in zapata.conf is enabled for the channel.

Ext.	zapata.conf	Action
*0		Send hook flash
*67		Disable Caller ID
*69	callreturn	Say last caller's Caller ID ("call return")
*70	callwaiting	Disable call waiting (for current call)
*72	cancallforward	Activate "call forward immediate"
*73	cancallforward	Deactivate "call forward immediate"
*78		Enable "Do Not Disturb"
*79		Disable "Do Not Disturb"
*60		Add last caller's caller ID to blacklist
*82		Enable Caller ID (only if disabled with *67)

In addition, there are other codes that are not specific to the Zap channel module:

   *8# Callgroup pickup

Pulse Dialing

The Zap channel drivers also work fine with pulse dialing on analog channels.

The configuration option for that is:

 pulsedial=yes

For more information, see:

• Pulse Dialing on Zap Channels

ISDN Data Services

If you are connecting an ISDN interface through a Zap channel, and you wish to provide ISDN data services (PPP over ISDN), then you need to refer to the ZapRAS command, and refer to the following four configuration options in zapata.conf: idledial, idleext, minunused, minidle.

There is support for GR303 in the Zap channel since June 2004

Analog Dial

When dialing on an analog zap channel and the dialtone does not come up instantly, adding the w (wait) to the front of the number for a 1/2 sec pause usually works. Some analog lines however take a random time to provide the dialtone and just adding w's is not the best solution. What I did was use a macro that checks if the line is silent or not before dialing and that seems to have done the trick, as below:

   macro-dialanalog
   exten => s,1,NoOp
   exten => s,n(clear),   Dial(${DIALOUTANALOG}|${ARG2}|M(dialanalogcont^${ARG1}))
   exten => s,clear+101,  Set(MACRO_OFFSET=100)
   
   macro-dialanalogcont
   exten => s,1,NoOp
   exten => s,n(silence), WaitForSilence(100)
   exten => s,n,          GotoIf($"${WAITSTATUS}" = "SILENCE"?silence) ; Loop if silence is detected
   exten => s,n(realdial),SendDTMF(${ARG1})
   exten => s,n,          Goto(end)
   exten => s,n(end),     Macro(record-on)

Troubleshooting

Missing libpri

Symptom: chan_zap fails to load (no 'zap' in the CLI). In the logs you see the error:

  chan_zap.c: Unknown signalling method 'pri_cpe'

Cause: chan_zap.so in Asterisk was built without support for libpri. libpri was not installed when you ran ./configure before building asterisk.

Fix: Rebuild asterisk and make sure libpri is supported.

 $ strings channels/chan_zap.so | grep pri_cpe
 pri_cpe

See also

• Zap Channel Module configuration (zapata.conf)
• Zaptel Driver configuration (zaptel.conf)
• Zaptel Installation
• Bristuff and zaptelBRI
• Zapata: What's "Zapata" Anyway?
• TDMoE Mini-HOWTO

---

Asterisk | Channels