~ubuntu-branches/debian/squeeze/asterisk-chan-capi/squeeze : revision 4

1

(CAPI*) chan_capi a Common ISDN API 2.0 implementation for Asterisk

2

1

(CAPI*) chan_capi a Common ISDN API 2.0 implementation

2

for Asterisk/OpenPBX

3

4

5

Armin Schindler <armin@melware.de>

6

7

Reworked, but based on the work of

8

9

Klaus-Peter Junghanns <kpj@junghanns.net>

10

11

Ported to OpenPBX.org 22nd October 2004,

12

Rob Thomas, <xrobau@gmail.com>

3

13

4

14

This program is free software and may be modified and distributed under

5

15

the terms of the GNU Public License. There is _NO_ warranty for this!

6

16

7

Thanks go to the debuggers and bugfixers (listed in chronological order) :)

17

Thanks go to the debuggers, bugfixers and contributors :)

8

18

===========================================================================

9

19

Lele Forzani <lele@windmill.it>

10

20

Florian Overkamp <florian@obsimref.com>

11

21

Gareth Watts <gareth@omnipotent.net>

12

22

Jeff Noxon <jeff@planetfall.com>

13

23

Petr Michalek <petr.michalek@aca.cz>

14

(...and all the others that i forgot..) :-)

15

16

chan_capi version 0.3.5 includes:

17

======================================

18

19

- multiple controller support

24

Jan Stocker

25

Frank Sautter, levigo group

26

Hans Petter Selasky

27

28

(...and all the others that have been forgotten...) :-)

29

30

No support for Asterisk 1.0.x any more, you need at least

31

Asterisk 1.2.x

32

33

To support all fax features (e.g. fax polling), you

34

need version 3 of libcapi20.

35

36

This chan_capi version includes:

37

================================

38

- Multiple controller support

20

39

- CID,DNID (callling party, called party)

21

40

- CLIR/CLIP

22

- supplementary services, CD,HOLD,RETRIEVE,ECT

41

- Supplementary services: CD (deflect/reroute),HOLD,RETRIEVE,ECT

23

42

- DTMF (dependend on card) + software DTMF support

24

- early B3 connects (always,success,never)

25

- digital audio (what did you think?)

26

- incoming/outgoing calls

27

- overlap sending (dialtone)

28

- E(xplicit) C(all) T(ransfer) (...although it's done implicit .. but dont tell!)

29

- tuneable latency ;) you can configure the size of B3 blocks at compile time

30

(in chan_capi_pvt.h, AST_CAPI_MAX_B3_BLOCK_SIZE)

31

the default is 160 samples, for non-VoIP use you can tune it down to 130

32

- use asterisk's internal dsp functions for dtmf

33

- alaw support

34

- ulaw support!

43

- Early B3 connects (always,success,never)

44

- Digital audio (what did you think?)

45

- Incoming/outgoing calls

46

- Overlap sending (dialtone and additional digits)

47

- E(xplicit) C(all) T(ransfer) (...although it's done implicit-but don't tell!)

48

- Use asterisks internal DSP functions for DTMF

49

- Alaw support

50

- Ulaw support!

35

51

- Eicon CAPI echo cancelation (echocancel=1)

36

- reject call waiting (ACO)

52

- Reject call waiting (ACO)

37

53

- DID for Point to Point mode (a.k.a overlap receiving)

38

- experimental echo squelching (echosquelch=1)

39

- call progress, no need to add ||r to your dialstring anymore

40

- rx/tx gains (rxgain=1.0)

41

- call deflection on circuitbusy (makefile option) (deflect=12345678)

42

- (inter)national dialing prefix (for callerid) configurable in capi.conf

43

- CLI command "capi info" shows B channel status

44

- capiECT will announce the callerID since it gets lost on most isdn pbxes

45

the called party can press # to drop the call

46

- audio syncing (timing outgoing dataB3 on incoming dataB3), supposed to fix

47

the DATA_B3_REQ (error = 0x1103) problem

48

- catch all MSN (incomingmsn=*)

49

- some configuration enhancements (msn=123,124,125 and controller=1,2,3,4)

50

- accountcode= added.

51

- finally the echo squelching works!

52

- callgroup support

53

- fixed pipe leak

54

- updated to support the new frame->delivery field

55

- compiles with latest cvs with a makefile option (LOOK AT THE MAKEFILE)

56

- fixed channel name bug in p2p mode

57

- added app_capiNoES for disabling the primitive echo suppressor, use this before

58

you start recording voicemail or your files may get choppy

59

- fixed for latest cvs (AST_MUTEX_DEFINE_STATIC)

60

- fixed for latest cvs (asterisk/parking.h -> asterisk/features.h)

61

- fixed for latest cvs ast_pthread_create

62

63

The default codec has now changed from signed linear to alaw/mulaw. This will

64

have a positive effect on performance and might even reduce some echo (latency).

65

66

Helper applications

67

===================

68

kapejod says: "No No No, dont use those yet....!" (except maybe HOLD,ECT...)

69

70

app_capiCD.c forwards an unanswered call to another phone (does not rely on sservice CD)

71

example:

72

exten => s,1,Wait,1

73

exten => s,2,capiCD,12345678

74

75

app_capiHOLD.c puts an answered call on hold, this has nothing to do with asterisk's onhold thingie (music et al)

76

after putting a call onhold, never use the Wait application!

77

78

app_capiRETRIEVE.c gets the holded call back

79

80

app_capiECT.c explicit call transfer of the holded call (must put call on hold first!)

81

example:

82

exten => s,1,Answer

83

exten => s,2,capiHOLD

84

exten => s,3,capiECT,55:50

85

will ECT the call to 50 using 55 as the callerid/outgoing msn

54

- Rx/Tx gains (rxgain=1.0)

55

- (Inter)national dialing prefix (for callerid) configurable in capi.conf

56

- CLI command "capi info" shows B channel status of chan_capi

57

- Catch all MSN (incomingmsn=*)

58

- Some configuration enhancements (msn=123,124,125)

59

- Added accountcode=

60

- Echo squelching (echosquelch=1)

61

- Callgroup support

62

- report correct DIALSTATUS and HANGUPCAUSE.

63

- Updated to support the new frame->delivery field

64

- Compiles with different Asterisk versions (automatic build configuration)

65

- receive/send faxes over CAPI (see below)

66

- Fixes and compatibility for BSD (Jan Stocker and Hans Petter Selasky)

67

- Support 'type of number'.

68

- ISDN hold.

69

- CAPI Line Interconnect.

70

- Eicon DIVA Server VoIP/RTP

71

- CLI command "capi show channels" shows details on channel status.

72

73

Permissions

74

===========

75

76

OpenPBX.org, by default, runs as the non-root user/group

77

openpbx/openpbx. You must make sure that the /dev/capi* device files

78

are readable by OpenPBX.org either by changing the ownership or the

79

permissions of the the device files or by running OpenPBX.org as root.

80

81

The Dial string

82

===============

83

84

Example: Dial(CAPI/g<group>/[<callerid>:]<destination>[/<params>])

85

Or: Dial(CAPI/contr<controller>/[<callerid>:]<destination>[/<params>])

86

Or: Dial(CAPI/<interface-name>/[<callerid>:]<destination>[/<params>])

87

88

'group' can be a value, comma separated list of values or a range

89

using '-'. The according interface is found by searching a match with

90

the 'group' specified in the capi.conf for each interface.

91

92

The optional <callerid> followed by an ':' can be used to set a callerid

93

for this dial() command, without changing the original channel's callerid.

94

95

'params' is an optional part to set special settings for this call.

96

The string consists of a list of characters with the following meaning:

97

'b' : early B3 always.

98

'B' : early B3 on successful calls only.

99

'd' : use the default caller id which is set by defaultcid= in capi.conf

100

'o' : use overlap sending of number.

101

(Useful if additional digits shall be send afterwards or together

102

with 'b' to get dialtone and then send the number, e.g. if otherwise

103

no progress tones are available)

104

105

If the <interface-name> is used in dialstring, be sure the name (specified

106

in capi.conf) does not start with 'contr' or 'g'.

107

108

CLIP/CLIR uses the calling presentation of the calling channel, which can

109

be modified using the SetCallerPres() application. Use

110

SetCallerPres(prohib_not_screened) for CLIR. That is why the msn= param in

111

capi.conf has been removed. The callerID is also taken from the calling channel.

112

113

114

CAPI command application

115

========================

116

chan_capi provides an additional Asterisk application

117

capicommand()

118

With this application, special capi commands and features can be used.

119

120

Call Deflection:

121

Forwards an unanswered call to another number.

122

Example:

123

exten => s,1,capicommand(deflect|12345678)

124

125

Fax receive:

126

Receive a fax using CAPI.

127

Example:

128

exten => s,1,capicommand(receivefax|/tmp/${UNIQUEID}|+49 6137 555123|Asterisk)

129

(more see below)

130

131

Fax send:

132

Send a fax using CAPI.

133

Example:

134

exten => s,1,capicommand(sendfax|/path/to/faxfile.sff|+49 6137 555123|Asterisk)

135

(more see below)

136

137

Enable/Disable echosquelch:

138

Enable or disable a very primitive echo suppressor.

139

Disable this before you start recording voicemail or your files may get choppy.

140

Example:

141

exten => s,1,capicommand(echosquelch|yes)

142

or

143

exten => s,1,capicommand(echosquelch|no)

144

145

Enable/Disable echocancel:

146

Enable or disable echo-cancel provided by CAPI driver/hardware.

147

You may need to disable echo-cancel when e.g. data/fax transmission handled

148

by non-CAPI application.

149

Example:

150

exten => s,1,capicommand(echocancel|yes)

151

or

152

exten => s,1,capicommand(echocancel|no)

153

154

Malicious Call Identification:

155

Report a call of malicious nature.

156

Example:

157

exten => s,1,capicommand(malicious)

158

159

Hold:

160

Puts an answered call on hold, this has nothing to do with asterisk's onhold

161

thingie (music et al).

162

An optional parameter is the name of the variable which shall be set with

163

the reference ID of the call on hold.

164

Example:

165

exten => s,1,capicommand(hold)

166

or

167

exten => s,1,capicommand(hold|MYHOLDVAR)

168

169

Holdtype:

170

Set the type of 'hold'. When Asterisk wants to put the call on hold, the specified method

171

will be used.

172

Example:

173

exten => s,1,capicommand(holdtype|local) ;no hold, Asterisk can play MOH

174

or

175

exten => s,1,capicommand(holdtype|hold) ;ISDN-HOLD

176

or

177

; not yet implemented

178

exten => s,1,capicommand(holdtype|notify) ;notify the peer only, Asterisk can play MOH

179

180

181

Retrieve:

182

Gets back the holded call. An optional parameter is the reference ID of the call

183

on hold.

184

Example:

185

exten => s,1,capicommand(retrieve)

186

or

187

exten => s,1,capicommand(retrieve|${MYHOLDVAR})

188

189

ECT:

190

Explicit call transfer of the call on hold (must put call on hold first!)

191

Example:

192

exten => s,1,capicommand(ect|${MYHOLDVAR})

193

or

194

[macro-capiect]

195

exten => s,1,capicommand(ect)

196

[default]

197

exten => s,1,capicommand(hold)

198

exten => s,2,Wait(1)

199

exten => s,3,Dial(CAPI/contr1/1234,60,M(capiect))

86

200

87

201

88

202

Using CLIR

89

203

==========

90

in the Dial command put a '@' infront of the msn you want to use for dialing out, e.g.:

91

exten => s,1,Dial(CAPI/@12345678:${EXTEN},30,r)

92

204

Use the SetCallerPres() application before you dial:

205

exten => _X.,1,SetCallerPres(prohib_not_screened)

206

exten => _X.,2,Dial(CAPI/contr1/${EXTEN})

207

93

208

94

209

Enjoying early B3 connects (inband call progress, tones and announcements)

95

210

==========================================================================

96

early B3 is now configurable in the dialstring :)

97

if you prefix the destination number with a 'b' early B3 will always be used, also if the call fails

211

Early B3 is configurable in the dialstring parameters.

212

If you set a 'b', early B3 will always be used, also if the call fails,

98

213

because the number is unprovisioned, etc ...

99

if you prefix it with a 'B' early B3 will only be used on successful calls, giving you ring indication,etc...

100

101

dont use indications in the Dial command, your local exchange will do that for you:

102

exten => s,1,Dial(CAPI/12345678:B${EXTEN},30) (early B3 on success)

103

exten => s,1,Dial(CAPI/12345678:b${EXTEN},30) (always early B3)

104

exten => s,1,Dial(CAPI/12345678:${EXTEN},30,r) (no early B3, fake ring indication)

105

106

exten => s,1,Dial(CAPI/12345678:b${EXTEN},30,r) (always early B3, fake indicatons if the exchange

107

does not give us indications)

108

exten => s,1,Dial(CAPI/12345678:B${EXTEN},30,r) (early B3 on success, fake indicatons if the exchange

109

does not give us indications)

214

If you set a 'B', early B3 will only be used on successful calls,

215

giving you ring indication,etc...

216

217

Don't use indications in the Dial command, your local exchange will do that for

218

you:

219

exten => _X.,1,Dial(CAPI/contr1/${EXTEN}/B,30)

220

(early B3 on success)

221

222

exten => _X.,1,Dial(CAPI/contr1/${EXTEN}/b,30)

223

(always early B3)

224

225

exten => _X.,1,Dial(CAPI/contr1/${EXTEN},30,r)

226

(no early B3, fake ring indication)

227

228

exten => _X.,1,Dial(CAPI/contr1/${EXTEN}/b,30,r)

229

(always early B3, fake indicatons if the exchange does not give us

230

indications)

231

232

exten => _X.,1,Dial(CAPI/contr1/${EXTEN}/B,30,r)

233

(early B3 on success, fake indicatons if the exchange does not give us

234

indications)

110

235

111

you can totally turn B3 off in the Makefile at buildtime (-DNEVER_EVER_EARLY_B3_CONNECTS).

112

113

For normal PBX use you would use the "b" option, always early B3.

236

For normal PBX usage you would use the "b" option, always early B3.

114

237

115

238

Overlap sending (a.k.a. real dialtone)

116

239

======================================

117

when you dial an empty number, and have early B3 enabled, with:

118

Dial(CAPI/12345678:b)

119

the channel will come up at once and give you the dialtone it gets from the local exchange.

120

at this point the channel is like a legacy phone, now you can send dtmf digits to dial.

121

122

123

More information/documentation and commercial support can be found at:

124

http://www.junghanns.net/asterisk/

125

126

240

When you dial an empty number, and have early B3 enabled, with:

241

Dial(CAPI/g1//b)

242

The channel will come up at once and give you the dialtone it gets from the

243

local exchange.

244

At this point the channel is like a legacy phone, now you can send DTMF digits

245

to dial.

246

247

Example context for incoming calls on MSN 12345678:

248

===================================================

249

250

[capi-in]

251

exten => 12345678,1,Dial(SIP/phone1)

252

exten => 12345678,2,Hangup

253

254

255

Short HOWTO of capicommand(receivefax...) and capicommand(sendfax...):

256

==========================================================================

257

For those of you who have a CAPI card with an on-board DSP (like some Eicon and

258

DIVA Server), this allows you to receive/send faxes.

259

260

capicommand(receivefax|<filename>[|<stationid>|<headline>]):

261

------------------------------------------------------------

262

If you want to answer a channel in fax mode, use capicommand(receivefax|...)

263

instead of Answer()

264

If you use Answer(), you will be in voice mode. If the hardware DSP detects

265

fax tone, you can switch from voice to fax mode by calling capicommand(receivefax|...).

266

The parameter <filename> is mandatory and the parameters <stationid> and

267

<headline> are optional.

268

To enable fax tone detection and redirect to extension 'fax', use config variable

269

'faxdetect' in capi.conf.

270

271

Example of use :

272

line number 123, play something, if a fax tone is detected, handle it

273

line number 124, answer directly in fax mode

274

275

[incoming]

276

exten => 123,1,Answer()

277

exten => 123,2,BackGround(jpop)

278

exten => 124,1,Goto(handle_fax,s,1)

279

exten => fax,1,Goto(handle_fax,s,1)

280

281

[handle_fax]

282

exten => s,1,capicommand(receivefax|/tmp/${UNIQUEID}[|<stationid>|<headline>])

283

exten => s,2,Hangup()

284

exten => h,1,deadagi,fax.php // Run sfftobmp and mail it.

285

286

The output of capicommand(receivefax|...) is a SFF file.

287

Use sfftobmp to convert it.

288

With a DIVA Server, following features are provided:

289

- fax up to 33600

290

- high resolution

291

- Color Fax

292

- JPEG Compression is disabled (not tested yet)

293

294

capicommand(sendfax|<filename>[|<stationid>|<headline>]):

295

------------------------------------------------------------

296

To send a fax, you can use the same mechanism like with receivefax.

297

Just replace the <filename> with the path to the .SFF file to send.

298

299

After disconnect of a fax connection, the following variables

300

will be set for that channel:

301

FAXSTATUS : 0 = OK, 1 = Error.

302

FAXREASON : Value of B3 disconnect reason.

303

FAXREASONTEXT : Decoded text of FAXREASON value.

304

FAXRATE : The baud rate of the fax connection.

305

FAXRESOLUTION : 0 = standard, 1 = high.

306

FAXFORMAT : 0 = SFF.

307

FAXPAGES : Number of pages received.

308

FAXID : The ID of the remote fax maschine.

309

310

311

CLI command "capi show channels"

312

================================

313

This CLI command shows detailed info on all CAPI channels.

314

Column description:

315

Line-Name : the name of the interface as defined in capi.conf

316

NTmode : is the line in NT mode instead fo TE mode

317

state : the state of the channel, like 'Conn', 'Disc', 'Dial', ...

318

i/o : incoming or outgoing line

319

bproto : protocol on CAPI ('fax', 'trans' or 'rtp')

320

isdnstate : a string which may consists of the following characters

321

* = PBX is active

322

G = Line-Interconnect (CAPI bridge) active

323

B = b-channel is up

324

b = b-channel is requested

325

P = Progress was signaled

326

H = this line is on hold

327

T = this line is in transfer (ECT) mode

328

S = SETUP[_ACK] was signaled

329

ton : type of number value

330

number : the caller-number and destination-number

331

332

Asterisk variables used/set by chan_capi

333

========================================

334

335

BCHANNELINFO

336

On incomming call, this variable is set with the B-channel information value:

337

'0' : B-channel is used (default)

338

'1' : D-channel is used (not implemented yet)

339

'2' : neither B nor D channel is used (e.g. call waiting)

340

Call-Waiting: an incoming call with BCHANNELINFO not '0' cannot be accepted.

341

Another connection must be dropped before accepting or use

342

capicommand(deflect|<number>) to initiate call deflection to another destination.

343

344

CALLEDTON

345

The 'type of number' value of the called number is saved in this variable on

346

incomming call.

347

348

_CALLERHOLDID

349

If a call is put on hold (ISDN-HOLD), the reference id is saved in this variable.

350

This variable is inherited as CALLERHOLDID to the dialed channel and will be used

351

if e.g. capicommand(ect) is used to transfer the held call.

352

353

CALLINGSUBADDRESS

354

If set on dial(), the calling subaddress will be set to the content.

355

356

CALLEDSUBADDRESS

357

If set on dial(), the called subaddress will be set to the content.

358

359

CONNECTEDNUMBER

360

Can be set before answering and if set, the content is used for

361

IE 'Connected Number' on answering.

362

363

FAXEXTEN

364

If chan_capi sends the call to extensions 'fax', the original extension number

365

is saved in this variable.

366

367

PRI_CAUSE

368

If set, this value will be used as hangup cause on hangup.

369

370

REDIRECTINGNUMBER

371

On incoming call, if the call was redirected to you by someone, the

372

number of the redirecting party is saved in this variable.

373

RDNIS is set as well.

374

375

REDIRECTREASON

376

If the incoming call was redirected to you, this variable is set

377

with the reason value.

378

127

379