Zapata zaptel interface
From FreeSWITCH Wiki
The BSD Telephony project Zapata was the creators of the original Zaptel interface. This interface is how Zap based cards work. This is an explanation of that interface.
[edit]
License
The zapata library is public domain and is still functional. We are documenting the Zaptel public interface here, which the zapata library or anyone else for that matter could use to talk to zaptel.
/* * BSD Telephony Of Mexico "Zapata" Telecom Library, version 1.10 12/10/01 * * Part of the "Zapata" Computer Telephony Technology. * * See http://www.bsdtelephony.com.mx * * * The technologies, software, hardware, designs, drawings, scheumatics, board * layouts and/or artwork, concepts, methodologies (including the use of all * of these, and that which is derived from the use of all of these), all other * intellectual properties contained herein, and all intellectual property * rights have been and shall continue to be expressly for the benefit of all * mankind, and are perpetually placed in the public domain, and may be used, * copied, and/or modified by anyone, in any manner, for any legal purpose, * without restriction. * * TTY/TDD functionality heavily based upon 'rtty' program by Jesus Arias. */
[edit]
struct: zt_params
12 ints, 1 40 byte char array, and 11 ints. Passed to the ioctl ZT_GET_PARAMS and ZT_SET_PARAMS
int channel_number; -- Channel number int span_number; -- Span itself int channel_position; -- Channel number in span int signal_type; -- read-only int signal_cap; -- read-only int rxisoffhook; -- read-only int rxbits; -- read-only int txbits; -- read-only int txhooksig; -- read-only int rxhooksig; -- read-only int curlaw; -- read-only -- one of ZT_LAW_MULAW or ZT_LAW_ALAW int idlebits; -- read-only -- What is considered the idle state char channel_name[40]; -- Name of channel int prewinktime; int preflashtime; int winktime; int flashtime; int starttime; int rxwinktime; int rxflashtime; int debouncetime; int pulsebreaktime; int pulsemaketime; int pulseaftertime;
[edit]
struct: zt_confinfo
3 ints passed to ioctl ZT_GETCONF ZT_SETCONF and ZT_CONFLINK
int channel; -- channel number, 0 for current int conference_number; -- conference number int conference_mode; -- conferencing mode
[edit]
struct: zt_gains
1 int, 2 unsigned 256 byte char arrays. Used in ZT_GETGAINS and ZT_SETGAINS
int channel; -- channel number, 0 for current unsigned char rxgain[256]; -- Receive gain table unsigned char txgain[256]; -- Transmit gain table
[edit]
struct: zt_spaninfo
1 int, 1 20 byte char array, 1 40 byte char array, and 12 int. Used in ZT_SPANSTAT
int spanno; -- span number (or -1 to use name) char name[20]; -- Name of span char desc[40]; -- Description of span int alarms; -- alarms status int txlevel; -- what TX level is set to int rxlevel; -- current RX level int bpvcount; -- current BPV count int crc4count; -- current CRC4 error count int ebitcount; -- current E-bit error count int fascount; -- current FAS error count int irqmisses; -- current IRQ misses int syncsrc; -- span # of current sync source, or 0 for free run int numchans; -- number of configured channels on this span int totalchans; -- total number of channels on the span int totalspans; -- total number of zaptel spans in entire system
[edit]
struct: zt_maintinfo
2 int, Used in ZT_MAINT
int spanno; -- span number 1-2 int command; -- command
[edit]
struct: zt_lineconfig
1 int, 1 char 20 bytes char array, 3 ints Used in ZT_SPANCONFIG
int span; -- Which span number (0 to use name) char name[20]; -- Name of span to use int lbo; -- line build-outs int lineconfig; -- line config parameters (framing, coding) int sync; -- what level of sync source we are
[edit]
struct: zt_chanconfig
1 int, 1 40 byte char array, 4 int and 1 16 byte char array. Passed to the ioctl ZT_CHANCONFIG
int chan; -- Channel we're applying this to (0 to use name) char name[40]; -- Name of channel to use int sigtype; -- Signal type int deflaw; -- Default law (ZT_LAW_DEFAULT, ZT_LAW_MULAW, or ZT_LAW_ALAW int master; -- Master channel if sigtype is ZT_SLAVE int idlebits; -- Idle bits (if this is a CAS channel) or channel to monitor (if this is DACS channel) char netdev_name[16]; name for the hdlc network device
[edit]
struct: zt_tone_def_header
3 int, 1 40 byte char array. Passed to the ioctl ZT_LOADZONE
int count; -- How many samples follow int zone; -- Which zone we are loading int ringcadence[ZT_MAX_CADENCE]; -- Ring cadence in ms (0=on, 1=off, ends with 0 value) char name[40]; -- Informational name of zone
[edit]
struct: zt_bufferinfo
6 ints passed to ioctls ZT_SET_BUFINFO and ZT_GET_BUFINFO
int txbufpolicy; -- Policy for handling receive buffers int rxbufpolicy; -- Policy for handling receive buffers int numbufs; -- How many buffers to use int bufsize; -- How big each buffer is int readbufs; -- How many read buffers are full (read-only) int writebufs; -- How many write buffers are full (read-only)
[edit]
struct: zt_dialparams
3 ints passed to ioctls ZT_GET_DIALPARAMS and ZT_SET_DIALPARAMS
int mfv1_tonelen; -- MF tone length (KP = this * 5/3) int dtmf_tonelen; -- DTMF tone length int reserved[4]; -- Reserved for future expansion -- always set to 0
[edit]
struct: zt_dialoperation
1 int and 1 char array of ZT_MAX_DTMF_BUF size passed to ioctls ZT_DIAL
int op; char dialstr[ZT_MAX_DTMF_BUF];
[edit]
Event Definitions
| Zaptel Events | ||
| ZT_EVENT_NONE | 0 | Return Value for GET/WAIT Event, no event |
| ZT_EVENT_ONHOOK | 1 | Return Value for GET/WAIT Event, Went Onhook |
| ZT_EVENT_RINGOFFHOOK | 2 | Return Value for GET/WAIT Event, Went Offhook or got Ring |
| ZT_EVENT_WINKFLASH | 3 | Return Value for GET/WAIT Event, Got Wink or Flash |
| ZT_EVENT_ALARM | 4 | Return Value for GET/WAIT Event, Got Alarm |
| ZT_EVENT_NOALARM | 5 | Return Value for GET/WAIT Event, Got No Alarm (after alarm) |
| ZT_EVENT_ABORT | 6 | Return Value for GET/WAIT Event, HDLC Abort frame |
| ZT_EVENT_OVERRUN | 7 | Return Value for GET/WAIT Event, HDLC Frame overrun |
| ZT_EVENT_BADFCS | 8 | Return Value for GET/WAIT Event, Bad FCS |
| ZT_EVENT_DIALCOMPLETE | 9 | Return Value for dial complete |
| ZT_EVENT_RINGERON | 10 | Return Value for ringer going on |
| ZT_EVENT_RINGEROFF | 11 | Return Value for ringer going off |
| ZT_EVENT_HOOKCOMPLETE | 12 | Return Value for hook change complete |
| ZT_EVENT_BITSCHANGED | 13 | Return Value for bits changing on a CAS / User channel |
| ZT_EVENT_PULSE_START | 14 | Return Value for the beginning of a pulse coming on its way |
| ZT_EVENT_TIMER_EXPIRED | 15 | Timer event -- timer expired |
| ZT_EVENT_TIMER_PING | 16 | Timer event -- ping ready |
| ZT_EVENT_POLARITY | 17 | Polarity reversal event |
| ZT_EVENT_RINGBEGIN | 18 | Ring Begin event |
| ZT_EVENT_EC_DISABLED | 19 | Echo can disabled event |
| ZT_EVENT_REMOVED | 20 | Channel was disconnected. Hint user to close channel |
| ZT_EVENT_PULSEDIGIT | (1 << 16) | This is OR'd with the digit received |
| ZT_EVENT_DTMFDOWN | (1 << 17) | Same for DTMF key down event |
| ZT_EVENT_DTMFUP | (1 << 18) | Same for DTMF key up event |
| Conference modes | ||
| ZT_CONF_MODE_MASK | 0xff | mask for modes |
| ZT_CONF_NORMAL | 0 | normal mode |
| ZT_CONF_MONITOR | 1 | monitor mode (rx of other chan) |
| ZT_CONF_MONITORTX | 2 | monitor mode (tx of other chan) |
| ZT_CONF_MONITORBOTH | 3 | monitor mode (rx & tx of other chan) |
| ZT_CONF_CONF | 4 | conference mode |
| ZT_CONF_CONFANN | 5 | conference announce mode |
| ZT_CONF_CONFMON | 6 | conference monitor mode |
| ZT_CONF_CONFANNMON | 7 | conference announce/monitor mode |
| ZT_CONF_REALANDPSEUDO | 8 | real and pseudo port both on conf |
| ZT_CONF_DIGITALMON | 9 | Do not decode or interpret |
| ZT_CONF_MONITOR_RX_PREECHO | 10 | monitor mode (rx of other chan) - before echo can is done |
| ZT_CONF_MONITOR_TX_PREECHO | 11 | monitor mode (tx of other chan) - before echo can is done |
| ZT_CONF_MONITORBOTH_PREECHO | 12 | monitor mode (rx & tx of other chan) - before echo can is done |
| ZT_CONF_FLAG_MASK | 0xff00 | mask for flags |
| ZT_CONF_LISTENER | 0x100 | is a listener on the conference |
| ZT_CONF_TALKER | 0x200 | is a talker on the conference |
| ZT_CONF_PSEUDO_LISTENER | 0x400 | pseudo is a listener on the conference |
| ZT_CONF_PSEUDO_TALKER | 0x800 | pseudo is a talker on the conference |
| Tone Defines | ||
| ZT_TONE_ZONE_MAX | 128 | |
| ZT_TONE_ZONE_DEFAULT | -1 | To restore default |
| ZT_TONE_STOP | -1 | |
| ZT_TONE_DIALTONE | 0 | |
| ZT_TONE_BUSY | 1 | |
| ZT_TONE_RINGTONE | 2 | |
| ZT_TONE_CONGESTION | 3 | |
| ZT_TONE_CALLWAIT | 4 | |
| ZT_TONE_DIALRECALL | 5 | |
| ZT_TONE_RECORDTONE | 6 | |
| ZT_TONE_INFO | 7 | |
| ZT_TONE_CUST1 | 8 | |
| ZT_TONE_CUST2 | 9 | |
| ZT_TONE_STUTTER | 10 | |
| ZT_TONE_MAX | 16 | |
| ZT_TONE_DTMF_BASE | 64 | |
| ------------------------------------------------------------------------------- | ||
| ZT_LAW_DEFAULT | 0 | Default law for span |
| ZT_LAW_MULAW | 1 | Mu-law |
| ZT_LAW_ALAW | 2 | A-law |
| ------------------------------------------------------------------------------- | ||
| ZT_MAX_DTMF_BUF | 256 | Define the max # of outgoing DTMF or MFv1 digits to queue in-kernel |
| ZT_CHUNKSIZE | 8 | 8 samples = 1 ms |
| ZT_MAX_BLOCKSIZE | 8192 | |
| ZT_DEFAULT_MTU_MRU | 2048 | |
| ------------------------------------------------------------------------------- | ||
| ZT_FLUSH_READ | 1 | Flush and stop the read (input) process |
| ZT_FLUSH_WRITE | 2 | Flush and stop the write (output) process |
| ZT_FLUSH_BOTH | (ZT_FLUSH_READ | ZT_FLUSH_WRITE) | Flush and stop both (input and output) processes |
| ZT_FLUSH_EVENT | 4 | Flush the event queue |
| ZT_FLUSH_ALL | (ZT_FLUSH_READ | ZT_FLUSH_WRITE | ZT_FLUSH_EVENT) | Flush everything |
| ------------------------------------------------------------------------------- | ||
| ZT_IOMUX_READ | 1 | Flag Value for IOMUX, read available |
| ZT_IOMUX_WRITE | 2 | Flag Value for IOMUX, write available |
| ZT_IOMUX_WRITEEMPTY | 4 | Flag Value for IOMUX, write done |
| ZT_IOMUX_SIGEVENT | 8 | Flag Value for IOMUX, signalling event available |
| ZT_IOMUX_NOWAIT | 256 | Flag Value for IOMUX, Do Not Wait if nothing to report |
| ------------------------------------------------------------------------------- | ||
| ZT_ONHOOK | 0 | Value for ZT_HOOK, set to ON hook |
| ZT_OFFHOOK | 1 | Value for ZT_HOOK, set to OFF hook |
| ZT_WINK | 2 | Value for ZT_HOOK, wink (off hook momentarily) |
| ZT_FLASH | 3 | Value for ZT_HOOK, flash (on hook momentarily) |
| ZT_START | 4 | Value for ZT_HOOK, start line |
| ZT_RING | 5 | Value for ZT_HOOK, ring line (same as start line) |
| ZT_RINGOFF | 6 | Value for ZT_HOOK, turn ringer off |
| Maintenance Modes | ||
| ZT_MAINT_NONE | 0 | Normal Mode |
| ZT_MAINT_LOCALLOOP | 1 | Local Loopback |
| ZT_MAINT_REMOTELOOP | 2 | Remote Loopback |
| ZT_MAINT_LOOPUP | 3 | Send Loopup Code |
| ZT_MAINT_LOOPDOWN | 4 | Send Loopdown Code |
| ZT_MAINT_LOOPSTOP | 5 | Stop Sending Loop Codes |
| Alarm Condition Bits | ||
| ZT_ALARM_NONE | 0 | No Alarms |
| ZT_ALARM_RECOVER | 1 | Recovering from Alarm |
| ZT_ALARM_LOOPBACK | 2 | In Loopback |
| ZT_ALARM_YELLOW | 4 | Yellow Alarm |
| ZT_ALARM_RED | 8 | Red Alarm |
| ZT_ALARM_BLUE | 16 | Blue Alarm |
| ZT_ALARM_NOTOPEN | 32 | N/A |
| Dial Operation bits | ||
| ZT_DIAL_OP_APPEND | 1 | N/A |
| ZT_DIAL_OP_REPLACE | 2 | N/A |
| ZT_DIAL_OP_CANCEL | 3 | N/A |
[edit]
IOCTLS Defines
Here are a list of ioctls that use the public interface to zaptel kernel drivers. These are used in the Public domain Zapata Library.
ZT_CODE = 'J' used in ioctls.
| ZT_GET_BLOCKSIZE | _IOW (ZT_CODE, 1, int) | Get Transfer Block Size. |
| ZT_SET_BLOCKSIZE | _IOW (ZT_CODE, 2, int) | Set Transfer Block Size. |
| ZT_FLUSH | _IOW (ZT_CODE, 3, int) | Flush Buffer(s) and stop I/O |
| ZT_SYNC | _IOW (ZT_CODE, 4, int) | Wait for Write to Finish |
| ZT_GET_PARAMS | _IOR (ZT_CODE, 5, struct zt_params) | Get channel parameters |
| ZT_SET_PARAMS | _IOW (ZT_CODE, 6, struct zt_params) | Set channel parameters |
| ZT_HOOK | _IOW (ZT_CODE, 7, int) | Set Hookswitch Status |
| ZT_GETEVENT | _IOR (ZT_CODE, 8, int) | Get Signalling Event |
| ZT_IOMUX | _IOWR (ZT_CODE, 9, int) | Wait for something to happen (IO Mux) |
| ZT_SPANSTAT | _IOWR (ZT_CODE, 10, struct zt_spaninfo) | Get Span Status |
| ZT_MAINT | _IOW (ZT_CODE, 11, struct zt_maintinfo) | Set Maintenance Mode |
| ZT_GETCONF | _IOWR (ZT_CODE, 12, struct zt_confinfo) | Get Conference Mode |
| ZT_SETCONF | _IOWR (ZT_CODE, 13, struct zt_confinfo) | Set Conference Mode |
| ZT_CONFLINK | _IOW (ZT_CODE, 14, struct zt_confinfo) | Setup or Remove Conference Link |
| ZT_CONFDIAG | _IOR (ZT_CODE, 15, int) | Display Conference Diagnostic Information on Console |
| ZT_GETGAINS | _IOWR (ZT_CODE, 16, struct zt_gains) | Get Channel audio gains |
| ZT_SETGAINS | _IOWR (ZT_CODE, 17, struct zt_gains) | Set Channel audio gains |
| ZT_SPANCONFIG | _IOW (ZT_CODE, 18, struct zt_lineconfig) | Set Line (T1) Configurations and start system |
| ZT_CHANCONFIG | _IOW (ZT_CODE, 19, struct zt_chanconfig) | Set Channel Configuration |
| ZT_CONFMUTE | _IOW (ZT_CODE, 20, int) | Set Conference to mute mode |
| ZT_SENDTONE | _IOW (ZT_CODE, 21, int) | Send a particular tone (see ZT_TONE_*) |
| ZT_SETTONEZONE | _IOW (ZT_CODE, 22, int) | Set your region for tones (see ZT_TONE_ZONE_*) |
| ZT_GETTONEZONE | _IOR (ZT_CODE, 23, int) | Retrieve current region for tones (see ZT_TONE_ZONE_*) |
| ZT_DEFAULTZONE | _IOW (ZT_CODE, 24, int) | Master unit only -- set default zone (see ZT_TONE_ZONE_*) |
| ZT_LOADZONE | _IOW (ZT_CODE, 25, struct zt_tone_def_header) | Load a tone zone from a ZT_tone_def_header |
| ZT_FREEZONE | _IOW (ZT_CODE, 26, int) | Free a tone zone |
| ZT_SET_BUFINFO | _IOW (ZT_CODE, 27, struct zt_bufferinfo) | Set buffer policy |
| ZT_GET_BUFINFO | _IOR (ZT_CODE, 28, struct zt_bufferinfo) | Get current buffer info |
| ZT_GET_DIALPARAMS | _IOR (ZT_CODE, 29, struct zt_dialparams) | Get dialing parameters |
| ZT_SET_DIALPARAMS | _IOW (ZT_CODE, 30, struct zt_dialparams) | Set dialing parameters |
| ZT_DIAL | _IOW (ZT_CODE, 31, struct zt_dialoperation) | Append, replace, or cancel a dial string |
| ZT_AUDIOMODE | _IOW (ZT_CODE, 32, int) | Set a clear channel into audio mode |
| ZT_ECHOCANCEL | _IOW (ZT_CODE, 33, int) | zero to disable echo cancellation and non-zero to enable echo cancellation. Num between 32 and 256 will set taps in the echo canceller |
| ZT_CHANNO | _IOR (ZT_CODE, 34, int) | Return a channel's channel number (useful for the /dev/zap/pseudo type interfaces |
| ZT_DIALING | _IOR (ZT_CODE, 35, int) | Return a flag indicating whether channel is currently dialing |
| ZT_HDLCRAWMODE | _IOW (ZT_CODE, 36, int) | Set a clear channel into HDLC w/out FCS checking/calculation mode |
| ZT_HDLCFCSMODE | _IOW (ZT_CODE, 37, int) | Set a clear channel into HDLC w/ FCS mode |
| ZT_SPECIFY | _IOW (ZT_CODE, 38, int) | Specify a channel on /dev/zap/chan -- must be done before any other ioctl's and is only valid on /dev/zap/chan |
| ZT_SETLAW | _IOW (ZT_CODE, 39, int) | Temporarily set the law on a channel to ZT_LAW_DEFAULT, ZT_LAW_ALAW, or ZT_LAW_MULAW. Is reset on close. |
| ZT_SETLINEAR | _IOW (ZT_CODE, 40, int) | Temporarily set the channel to operate in linear mode when non-zero or default law if 0 |
| ZT_HDLCPPP | _IOW (ZT_CODE, 41, int) | Set a clear channel into HDLC w/ PPP interface mode |
| ZT_GETCONFMUTE | _IOR (ZT_CODE, 49, int) | Get Conference to mute mode |
| ZT_ECHOTRAIN | _IOW (ZT_CODE, 50, int) | Request echo training in some number of ms (with muting in the mean time) |
| ZT_STARTUP | _IOW (ZT_CODE, 99, int) | Startup a span |
| ZT_SHUTDOWN | _IOW (ZT_CODE, 100, int) | Shutdown a span |
