Zapata zaptel interface
About
The BSD Telephony project Zapata created the original Zaptel interface. This interface is how Zaptel-based cards work. This page explains that the low-level interface.
If you're interested in how to configure FreesSWITCH to interface with Zaptel-compatible hardware, how to install Zaptel kernel drivers, and similar information, see here for details.
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.
*/
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;
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
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
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
struct: zt_maintinfo
2 int, Used in ZT_MAINT
int spanno; -- span number 1-2
int command; -- command
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
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
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
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)
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
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];
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 |
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 |