Skip to main content

Zapata zaptel interface


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.

Click here to expand Table of Contents


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
* 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_NONE0Return Value for GET/WAIT Event, no event
ZT_EVENT_ONHOOK1Return Value for GET/WAIT Event, Went Onhook
ZT_EVENT_RINGOFFHOOK2Return Value for GET/WAIT Event, Went Offhook or got Ring
ZT_EVENT_WINKFLASH3Return Value for GET/WAIT Event, Got Wink or Flash
ZT_EVENT_ALARM4Return Value for GET/WAIT Event, Got Alarm
ZT_EVENT_NOALARM5Return Value for GET/WAIT Event, Got No Alarm (after alarm)
ZT_EVENT_ABORT6Return Value for GET/WAIT Event, HDLC Abort frame
ZT_EVENT_OVERRUN7Return Value for GET/WAIT Event, HDLC Frame overrun
ZT_EVENT_BADFCS8Return Value for GET/WAIT Event, Bad FCS
ZT_EVENT_DIALCOMPLETE9Return Value for dial complete
ZT_EVENT_RINGERON10Return Value for ringer going on
ZT_EVENT_RINGEROFF11Return Value for ringer going off
ZT_EVENT_HOOKCOMPLETE12Return Value for hook change complete
ZT_EVENT_BITSCHANGED13Return Value for bits changing on a CAS / User channel
ZT_EVENT_PULSE_START14Return Value for the beginning of a pulse coming on its way
ZT_EVENT_TIMER_EXPIRED15Timer event -- timer expired
ZT_EVENT_TIMER_PING16Timer event -- ping ready
ZT_EVENT_POLARITY17Polarity reversal event
ZT_EVENT_RINGBEGIN18Ring Begin event
ZT_EVENT_EC_DISABLED19Echo can disabled event
ZT_EVENT_REMOVED20Channel 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_MASK0xffmask for modes
ZT_CONF_NORMAL0normal mode
ZT_CONF_MONITOR1monitor mode (rx of other chan)
ZT_CONF_MONITORTX2monitor mode (tx of other chan)
ZT_CONF_MONITORBOTH3monitor mode (rx & tx of other chan)
ZT_CONF_CONF4conference mode
ZT_CONF_CONFANN5conference announce mode
ZT_CONF_CONFMON6conference monitor mode
ZT_CONF_CONFANNMON7conference announce/monitor mode
ZT_CONF_REALANDPSEUDO8real and pseudo port both on conf
ZT_CONF_DIGITALMON9Do not decode or interpret
ZT_CONF_MONITOR_RX_PREECHO10monitor mode (rx of other chan) - before echo can is done
ZT_CONF_MONITOR_TX_PREECHO11monitor mode (tx of other chan) - before echo can is done
ZT_CONF_MONITORBOTH_PREECHO12monitor mode (rx & tx of other chan) - before echo can is done
ZT_CONF_FLAG_MASK0xff00mask for flags
ZT_CONF_LISTENER0x100is a listener on the conference
ZT_CONF_TALKER0x200is a talker on the conference
ZT_CONF_PSEUDO_LISTENER0x400pseudo is a listener on the conference
ZT_CONF_PSEUDO_TALKER0x800pseudo is a talker on the conference
Tone Defines
ZT_TONE_ZONE_DEFAULT-1To restore default
ZT_LAW_DEFAULT0Default law for span
ZT_MAX_DTMF_BUF256Define the max # of outgoing DTMF or MFv1 digits to queue in-kernel
ZT_CHUNKSIZE88 samples = 1 ms
ZT_FLUSH_READ1Flush and stop the read (input) process
ZT_FLUSH_WRITE2Flush 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_EVENT4Flush the event queue
ZT_IOMUX_READ1Flag Value for IOMUX, read available
ZT_IOMUX_WRITE2Flag Value for IOMUX, write available
ZT_IOMUX_WRITEEMPTY4Flag Value for IOMUX, write done
ZT_IOMUX_SIGEVENT8Flag Value for IOMUX, signalling event available
ZT_IOMUX_NOWAIT256Flag Value for IOMUX, Do Not Wait if nothing to report
ZT_ONHOOK0Value for ZT_HOOK, set to ON hook
ZT_OFFHOOK1Value for ZT_HOOK, set to OFF hook
ZT_WINK2Value for ZT_HOOK, wink (off hook momentarily)
ZT_FLASH3Value for ZT_HOOK, flash (on hook momentarily)
ZT_START4Value for ZT_HOOK, start line
ZT_RING5Value for ZT_HOOK, ring line (same as start line)
ZT_RINGOFF6Value for ZT_HOOK, turn ringer off
Maintenance Modes
ZT_MAINT_LOOPUP3Send Loopup Code
ZT_MAINT_LOOPDOWN4Send Loopdown Code
ZT_MAINT_LOOPSTOP5Stop Sending Loop Codes
Alarm Condition Bits
ZT_ALARM_RECOVER1Recovering from Alarm
Dial Operation bits

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