NCID - Network Caller ID User Manual

NCID

Copyright: 2014-2016

Authors:
John L Chmielewski
Todd A Andrews

Last Edit: Nov 30, 2016


Introduction

NCID (Network Caller ID) is Caller ID (CID) distributed over a network to a variety of devices and computers.

The NCID server monitors either a modem, Caller ID device, or gateway (e.g., SIP, VoIP, smartphones) for the CID data. The data is collected and sent, via TCP, to one or more connected clients. The server supports multiple gateways which can be used with or without a modem or device. The server also supports one line text messages.

The NCID project website is the central place to go for downloads and user/technical support for the official NCID package and its optional client packages.

This document contains information on how to get started with NCID, the hardware needed, a Frequently Asked Questions (FAQ) section, and a TODO list. It also provides information on supported clients, gateways and optional server features. Troubleshooting information is also provided.

Chapters

Getting Started
Installation
Obtaining Caller ID
Supported Clients
Client Output Modules
Using NCID
FAQ
Verbose Levels
Contributors
TODO
LICENSE

Getting Started

Table of Contents

NCID can be overwhelming for users who have never used it. Current users of NCID are probably not aware of all of its features, or how to use them properly. This document will try to help with those cases. The FAQ should also be of some help.

In this document:

Getting Started Index

Install the NCID package

See the list of Package Distributions.

SourceForge distributes NCID packages for several operating systems. In addition, operating system specific third parties distribute NCID. For example, there are Ubuntu and Fedora repositories that include NCID, making it easy to install with their package management applications; however, they are not always up-to-date with the latest version at SourceForge.

The first step is to download and install the NCID server, optional gateways, and client. You can download the NCID packages from sourceforge or a repository for your operating system if it is up to date.

If you are using Fedora, Ubuntu, or Raspbian, be aware that NCID is split into multiple rpm and deb packages. The server package is required. The gateways package is needed if you are using a gateway instead of a modem. The client and default output modules package is needed if you want to use the basic ncid client instead of another supported client, or if you want to use an output module.

The Macintosh shell package and the FreeBSD shell package on sourceforge have the complete NCID system.

There are many Linux distributions based on Redhat or Ubuntu so the Fedora or Ubuntu packages may install just fine. (For example, Linux Mint is an operating system based on Ubuntu.) Refer to the INSTALL-"operating system" section for your "operating system".

If you cannot locate a package, you can download the source, compile, and install it. Refer to the INSTALL (generic) section of this documentation.

Configure the ncidd server

Now that you have installed NCID, you need to configure the method used to obtain Caller ID:

Using a modem connected to a Unix computer

Most modern modems support Caller ID but to determine if yours does follow the steps below and then refer to Modem Caller ID Test.

The server needs to know which port the modem is on. The default port is different depending on the Operating System:

        Unknown Operating System distribution:    /dev/modem
        Fedora, Redhat, Debian, Raspbian, Ubuntu: /dev/ttyACM0
        FreeBSD:                                  /dev/cuaU0
        Mac OS X:                                 /dev/cu.usbmodem24680241
        Cygwin:                                   /dev/com1
        TiVo ppc:                                 /dev/ttyS1
        TiVo MIPS:                                /dev/ttyS3

If the default modem port is incorrect, you need to enter the correct port by editing ncidd.conf and either uncomment one of these lines, or add a line with the correct port:

        # set ttyport = /dev/cu.modem # default Mac OS X internal modem
        # set ttyport = /dev/cu.usbmodem24680241 # Mac OS X USB modem (DualComm, Zoom)
        # set ttyport = /dev/ttyS0 # Linux Serial Port 0
        # set ttyport = /dev/ttyACM0 # Linux USB modem 0

If you wish to use the hangup feature, you need to uncomment this line:

        # set hangup = 1

After modifying ncidd.conf, ncidd must be started.

Using a serial NetCallerID device connected to a Unix computer

The serial NetCallerID device is no longer manufactured by Ugotcall, but you can sometimes find it on eBay.

Even though it supports Caller ID, the NetCallerID device is not a modem and it does not support the NCID hangup feature. Start by hooking it up to a serial port and making the changes above. Once that is completed, make these additional changes to ncidd.conf:

Uncomment this line:

        # set nomodem = 1

Leave this line commented:

        # set hangup = 1

After modifying ncidd.conf, ncidd must be started.

Using a Caller ID modem on a Windows computer via the NCID YAC gateway

You would use the YAC gateway if you are using a YAC server on a Windows computer running Microsoft Windows 98 or later.

We have a complete section devoted to the YAC gateway. See yac2ncid setup in the Gateways topic for more information.

Using the SIP Gateway

You would use the sip2ncid gateway if your VoIP phone is using SIP.

We have a complete section devoted to the SIP gateway. See sip2ncid setup in the Gateways topic for more information.

Using the Whozz Calling (WC) gateway

You would use the wc2ncid gateway if you are using a Whozz Calling Ethernet Link device. Serial Whozz Calling units are not currently supported.

We have a complete section devoted to the WC gateway. See wc2ncid setup in the Gateways topic for more information.

Using the Android smartphone Remote Notifier (RN) gateway

You would use the rn2ncid gateway if you are using an Android smartphone.

We have a complete section devoted to the RN gateway. See rn2ncid setup in the Gateways topic document for more information.

Configure the ncid client

Normally the client does not need to be configured, but you should review ncid.conf to see if you want to change the defaults for displaying the number format, displaying the date format, and ring options if using an output module. There are other changes you can also make.

After making any changes to ncid.conf, start the ncid client.

IMPORTANT: The ncidd server and any needed gateways should already be running.

Configure yearly call log

The yearly crontab file is built each month by ncid-yearlog. It is designed to be run by crontab on the first of each month. It creates the $HOME/ncid/log directory the first time it is run. On the first of any month, it creates

        $HOME/ncid/log/cidcall-<year>.

and continues to add months until the end of the year.

If you have no crontab entry, you can add the crontab file:

        crontab /usr/share/ncid/sys/crontab.

IMPORTANT:

REQUIREMENTS:

NCID Startup

At this point you should have NCID functional. The INSTALL section for your operating system explains how to make sure NCID is working properly.

The INSTALL section also explains how to start NCID at boot and how to manually start the server, gateways, and client.

If you are having any problems you can ask for assistance in the NCID Help or Open Discussion forums on SourceForge.

Installation

Table of Contents

Description

Description

NCID supports the operating systems indicated here. These are install instructions for each of the operating systems. There is also a generic install with compile instructions.

INSTALL (generic)
INSTALL-Cygwin
INSTALL-Fedora
INSTALL-FreeBSD
INSTALL-Mac
INSTALL-Raspbian
INSTALL-Redhat
INSTALL-TiVo
INSTALL-Ubuntu
INSTALL-Win

Review the INSTALL for your Operating System.

Generic INSTALL and Overview

If using the email2ncid gateway, review email2ncid setup.
If using the ncid2ncid gateway, review ncid2ncid setup.
If using the obi2ncid gateway, review obi2ncid setup.
If using the rn2ncid gateway, review rn2ncid setup.
If using the sip2ncid gateway, review sip2ncid setup.
If using the wc2ncid gateway, review wc2ncid setup.
If using the yac2ncid gateway, review yac2ncid setup.

Table of Contents

Sections

Layout

Fedora

Debian, Ubuntu or Raspberry Pi (RPi)

FreeBSD

Macintosh OSX

Compile

Note: The Makefile requires GNU make. See the top of the Makefile for more information on targets.

dnf install libpcap libpcap-devel

make local

make package

make fedora

make redhat

make debian

make ubuntu

make raspbian

make mac  

or

make mac-fat

make tivo-s1

make tivo-s2

Install

Note: See the top of the Makefile for more information on targets.

make install

make install MAN=/usr/local/man

make package-install  

or

make install prefix=/usr prefix2=

make fedora-install

make redhat-install

make debian-install

make ubuntu-install

make raspbian-install

make mac-install

Test Using a Modem

ncidd
ncid

ncidd -D

ncidd -Dv3

ncidd -Dv9

Network Port: 3333
Wrote pid 20996 in pidfile: /var/run/ncidd.pid
End of startup: 04/01/2016 20:28:06

 Modem set for CallerID.  
 Modem Error Condition. (Phone rang here)  
 /dev/ttyS1: No such file or directory  

You need to set ncidd to ignore modem signals.

Uncomment the following line in ncidd.conf:

# set ttyclocal = 1

07/13/2010 15:21 RING No Caller ID

This indicates one of three problems:

Test Using a Device (like the NetCallerID box)

ncidd
ncid

ncidd -D

ncidd -Dv3

ncidd -Dv9

Network Port: 3333
Wrote pid 20996 in pidfile: /var/run/ncidd.pid
End of startup: 04/01/2016 20:28:06

Test Using sip2ncid

ncidd
sip2ncid
ncid

ncidd -D

ncidd -Dv3

ncidd -Dv9

Network Port: 3333
Wrote pid 20996 in pidfile: /var/run/ncidd.pid
End of startup: 04/01/2016 20:28:06

Test Using wc2ncid

ncidd
wc2ncid
ncid

ncidd -D

ncidd -Dv3

ncidd -Dv9

Network Port: 3333
Wrote pid 20996 in pidfile: /var/run/ncidd.pid
End of startup: 04/01/2016 20:28:06

Test Using yac2ncid

ncidd
yac2ncid
ncid

ncidd -D

ncidd -Dv3

ncidd -Dv9

Network Port: 3333
Wrote pid 20996 in pidfile: /var/run/ncidd.pid
End of startup: 04/01/2016 20:28:06

Cygwin Package Install

If NCID does not work, see INSTALL for some simple tests.

If using the email2ncid gateway, review email2ncid setup.
If using the ncid2ncid gateway, review ncid2ncid setup.
If using the obi2ncid gateway, review obi2ncid setup.
If using the rn2ncid gateway, review rn2ncid setup.
If using the sip2ncid gateway, review sip2ncid setup. If using the wc2ncid gateway, review wc2ncid setup.
If using the yac2ncid gateway, review yac2ncid setup.

Table of Contents

Sections:

NOTES
INSTALL
CONFIGURE
START
REBASE
RUN AS A QUASI-SERVICE

NOTES:

The server does not function directly controlling a modem.

The server must be configured for either:

The supplied yac2ncid gateway requires YAC to control a modem under Windows

The supplied sip2ncid gateway requires WinPcap and WpdPack

The last test was using WinPcap_4_1_3.exe and WpdPack_4_1_2.zip

The ncid client GUI mode requires X-windows so it can only be used in command line mode. You should install and use the windows version of ncid. However, the windows version does not support output modules so if you need an output module, you can use the Cygwin version of ncid:

        ncid --no-gui <module> &

INSTALL:

Install WinPcap from windows if using the sip2ncid gateway:

Install Cygwin from http://cygwin.com/

Install or upgrade NCID:

The NCID package normally installs in /usr/local:

Extracting the tar file will REPLACE the contents of all of the NCID configuration files. Be sure to back them up first. This includes all files in /usr/local/etc/ncid/.

Copy ncid-VERSION-cygwin.tgz to cygwin sudo tar -xzvf ncid-VERSION-cygwin.tgz -C / EXAMPLE: sudo tar -xzvf ncid-1.2-cygwin.tgz -C /

For an upgrade, the install script will preserve existing configurations, and new ones installed will have *.new as the extension.

Copy ncid-VERSION-cygwin_install.sh to cygwin sudo sh ncid-VERSION-cygwin_install.sh EXAMPLE: sudo sh ncid-1.3-cygwin_install.sh

Copy ncid-VERSION-src.tar.gz to cygwin, then: tar -xzvf ncid-VERSION-src.tar.gz cd ncid make cygwin (compiles for /usr/local, see top of Makefile) sudo make cygwin-install

If your phone system is VoIP and you want to use sip2ncid:

If you want to use your modem, you need YAC

CONFIGURE:

The Makefile configures ncidd.conf for the Cygwin, but you may want to change some of the defaults.

You need to configure sip2ncid to use the Network Interface. To find out the network interface name, you need to use the "-l" option to sip2ncid. You should see your Network interface names listed. Select the active one and use it with the "-i" option to sip2ncid.

START:

If this is your first time, you should do the Test Using sip2ncid and Test Using yac2ncid procedures in the INSTALL (generic) section first.

start the server and clients:

If using obi2ncid

If using sip2ncid

If using wc2ncid:

If using yac2ncid

If using ncid for the first start test:

Call yourself and see if it works.

REBASE:

One of the idiosyncrasies of Cygwin is the need to rebase the dll's (set a base dll load address) so they don't conflict and create forking errors. The easiest way to do this is documented at Rebaseall

Just start an ash or dash prompt from , and then type:

rebaseall -v
exit

RUN AS A QUASI-SERVICE:

cygrunsrv -I ncidd -n -p /usr/local/bin/ncidd -f "Network CallerID daemon(ncidd)" -a -D

Explaining these parameters:

-I indicates install
-n indicates that the service never exits by itself (I don't recall why this has to be set, but it doesn't work otherwise) -p /usr/local/bin/ncidd: Application path which is run as a service. -f "Network CallerID daemon (ncidd)": Optional string which contains the service description (the desc you see in the Services listing) -a -D: passes the parameter "-D" to the ncidd program so it runs in debug mode. This keeps ncidd running in the "foreground" of the cygrunsrv process.

cygrunsrv -I sip2ncid -n -p /usr/local/bin/sip2ncid -y ncidd   -a '-i "/Device/NPF_{XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX}"
-D' -f "Service to pick SIP packets from network and send to ncidd"   --termsig KILL

Explaining these parameters:

-I indicates install -n indicates that the service never exits by itself (I don't recall why this has to be set, but it doesn't work otherwise) -p /usr/local/bin/sip2ncid: Application path which is run as a service. -y ncidd: adds a service dependency with the ncidd service so that the ncidd service gets started automatically when you start sip2ncid -a '-i "/Device/NPF_{XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX}" -D': note the single and double quotes in this section. You need to replace XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX in the above with NETWORK_INTERFACE from way above. To be clear, you want to replace /Device/NPF_{XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX} with NETWORK_INTERFACE from way above. -f "Service to pick SIP packets from network and send to ncidd": Optional string which contains the service description (the desc you see in the Services listing) --termsig KILL: termination signal to send. If you don't include this the service doesn't always get stopped.

cygrunsrv -R sip2ncid

cygrunsrv -I ncid-notify -p /bin/sh.exe -a
'-c "/usr/local/bin/ncid --no-gui --message --program ncid-notify"'
-f "Service to use notify service to send ncid messages to iPad"

Explaining these parameters:

-I indicates install -p /bin/sh.exe: Application path to run, which in this case is just sh.exe because ncid-notify is a shell script
-a '-c "/usr/local/bin/ncid --no-gui --program ncid-notify"' these are the parameters that get sent to sh.exe: -c "/usr/local/bin/ncid: this is the path to the ncid script --no-gui: tells ncid not to have a gui --program ncid-notify: tells ncid to pass data to "ncid-notify" -f "Service to use notify service to send ncid messages to iPad":

Optional string which contains the service description (the desc you see in the Services listing)

-y ncidd: you COULD also add this line to add a service dependency with the ncidd service so that the ncidd service gets started automatically when you start ncid-notify. I don't do this, because strictly speaking, you could be running ncidd on a different computer.

cygrunsrv -R ncid-notify

Fedora RPM Package Install

If NCID does not work, see INSTALL for some simple tests.

If using the email2ncid gateway, review email2ncid setup.
If using the ncid2ncid gateway, review ncid2ncid setup.
If using the obi2ncid gateway, review obi2ncid setup.
If using the rn2ncid gateway, review rn2ncid setup.
If using the sip2ncid gateway, review sip2ncid setup.
If using the wc2ncid gateway, review wc2ncid setup.
If using the yac2ncid gateway, review yac2ncid setup.

Table of Contents

Sections:

COMPILE:
INSTALL or UPGRADE:
CONFIGURE:
FIRST STARTUP:
START/STOP/RESTART/RELOAD/STATUS:
AUTOSTART:

COMPILE:

The following package is required:

     sudo dnf install libpcap-devel

This package is required to run obi2ncid, rn2ncid, wc2ncid, wct:

    - sudo dnf install perl-Config-Simple

This additional package is required to run wc2ncid and wct:

    - sudo dnf install perl-Data-HexDump

See INSTALL for compile instructions

INSTALL or UPGRADE:

NCID requires the server and client RPM packages to function. The server is required on one computer or device, but the client can be installed on as many computers as needed.

The client has a most of the output modules in its RPM package, but there are optional output modules in their own RPM packages.

Download the server and client RPM packages using dnf from the Fedora repositories. You can also download any optional output modules you want.

      sudo dnf list ncid\*
      sudo dnf install fedora-release-rawhide  
      sudo dnf --enablerepo=rawhide list ncid\*
      sudo dnf install ncid-< rpm package >  
      sudo dnf install ncid-gateways-< rpm package >
      sudo dnf install ncid-client-< rpm package >
      sudo dnf install ncid-< module rpm package >

If the current release is not in the Fedora repositories, download the RPM packages from https://sourceforge.net/projects/ncid/

      ncid RPM Package          (server - required)  
      ncid-gateways RPM Package (gateways - optional)  
      ncid-client RPM Package   (client & default output modules - optional)
      ncid-MODULE RPM Package  (optional client output modules)
     Using the file viewer:
     - Open the file viewer to view the NCID RPM packages
     - Select the RPM packages
     - right click selections and select "Open with Package installer"
     Using YUM:
     - sudo dnf install ncid\*.rpm

CONFIGURE:

The ncidd.conf file is used to configure ncidd.

FIRST STARTUP:

      sudo systemctl start ncidd  
      ncid &
      sudo systemctl start ncidd sip2ncid  
      ncid &
      sudo systemctl start ncidd wc2ncid  
      ncid &
      sudo systemctl start ncidd yac2ncid
      ncid &

stop the gateway and server:

      sudo systemctl stop sip2ncid ncidd  

and continue reading the test sections.

For example, to start ncidd and sip2ncid at boot:

      sudo systemctl enable ncidd sip2ncid

The GUI ncid client must be started after login, not boot.

NOTE: > ncid normally starts in the GUI mode and there is no ncid.service script to start or stop it. There are service scripts for starting ncid with output modules, for example: ncid-page, ncid-kpopup, etc.

START/STOP/RESTART/RELOAD/STATUS:

Use the 'systemctl' command to start any of the daemons. The service commands are: start, stop, restart, reload, reload-or-restart, and status. The client can also be started using the output module name instead of ncid. All output modules can be run at the same time.

Here are some examples:

      sudo systemctl start ncidd.service
      sudo systemctl reload-or-restart ncidd.service
      sudo systemctl restart ncid-page.service
      sudo systemctl status ncid-speak.service

Review the man page (man systemctl).

AUTOSTART:

Use the 'systemctl' command to enable/disable a service to start at boot.

Here are some examples:

      sudo systemctl enable ncidd
      sudo systemctl enable ncidd sip2ncid
      sudo systemctl disable ncid-speak

Review the manpage (man systemctl).

FreeBSD Install

If NCID does not work, see INSTALL for some simple tests.

If using the email2ncid gateway, review email2ncid setup.
If using the ncid2ncid gateway, review ncid2ncid setup.
If using the obi2ncid gateway, review obi2ncid setup.
If using the rn2ncid gateway, review rn2ncid setup.
If using the sip2ncid gateway, review sip2ncid setup.
If using the wc2ncid gateway, review wc2ncid setup.
If using the yac2ncid geatway, review yac2ncid setup.

Table of Contents

Sections:

COMPILE:
INSTALL:
CONFIGURE:
STARTUP:
START/STOP/STATUS:
AUTOSTART:
TRIMMING LOG FILES:
GMAKE NOTE:

COMPILE:

INSTALL:

include /usr/local/logrotate.d

Install or upgrade using the tar archive as root, if available:

Extracting the tar file will REPLACE the contents of all of the NCID configuration files. Be sure to back them up first, as root. This includes all files in /usr/local/etc/ncid/.

Copy ncid-VERSION-freebsd.tgz to the FreeBSD computer tar -xzvf ncid-VERSION-freebsd.tar.gz -C / EXAMPLE: tar -xzvf ncid-1.2-freebsd.tar.gz -C /

You will need to manually compare your backed up configuration files with the new ones, and manually edit any differences.

Install or upgrade using the install script as root, if available:

GNU getopt is required when using the install script. See this note.

For an upgrade, the install script will preserve existing configurations, and new ones installed will have *.new as the extension.

Copy ncid-VERSION-freebsd_install.sh to the FreeBSD computer sh ncid-VERSION-freebsd_install.sh EXAMPLE: sh ncid-1.3-freebsd_install.sh

You will need to manually compare your current configuration files with the *.new ones, and manually edit any differences.

If there is no binary package, you need to compile the source.

Gmake is required when compiling the source. See this note.

Your existing configuration files will be preserved, and new ones installed will have *.new as the extension.

Copy ncid-VERSION-src.tar.gz to the FreeBSD computer
tar -xzvf ncid-VERSION-src.tar.gz
gmake freebsd (compiles for /usr/local, see top of Makefile)
gmake freebsd-install

CONFIGURE:

The ncidd.conf file is used to configure ncidd.

set modem = /dev/cuaa0

set noserial = 1

set noserial = 0 (this is the default)

STARTUP:

/usr/local/etc/rc.d/ncidd onestart
ncid &

/usr/local/etc/rc.d/rc.d/ncidd onestart
/usr/local/etc/rc.d/rc.d/sip2ncid onestart
ncid &

/usr/local/etc/rc.d/rc.d/ncidd onestart
/usr/local/etc/rc.d/rc.d/wc2ncid onestart
ncid &

/usr/local/etc/rc.d/rc.d/ncidd onestart
/usr/local/etc/rc.d/rc.d/yac2ncid onestart
ncid &

/usr/local/etc/rc.d/rc.d/sip2ncid onestop

/usr/local/etc/rc.d/rc.d/ncidd onestop

START/STOP/STATUS:

Here are examples:

sudo /usr/local/etc/rc.d/ncidd start
sudo /usr/local/etc/rc.d/ncidd reload
sudo /usr/local/etc/rc.d/sip2ncid restart
sudo /usr/local/etc/rc.d/ncid-speak stop
sudo /usr/local/etc/rc.d/ncid-page status
sudo /usr/local/etc/rc.d/ncid-kpopup rcvar

AUTOSTART:

            /usr/local/etc/rc.d/     /etc/rc.conf.local
            --------------------     ------------------
            ncidd                    ncidd_enable="YES"
            sip2ncid                 sip2ncid_enable="YES"
            yac2ncid                 yac2ncid_enable="YES"
            ncid-kpopup              ncidkpopup_enable="YES"
            ncid-notify              ncidnotify_enable="YES"
            ncid-page                ncidpage_enable="YES"
            ncid-samba               ncidsamba_enable="YES"
            ncid-skel                ncidskel_enable="YES"
            ncid-speak               ncidspeak_enable="YES"
            ncid-yac                 ncidyack_enable="YES"

TRIMMING LOG FILES:

/var/log/cid.log root:wheel 644 5 $M1D0 GN

GMAKE NOTE:

cd /usr/ports/devel/gmake make all install

Macintosh Install

If NCID does not work, see INSTALL for some simple tests.

If using the email2ncid gateway, review email2ncid setup.
If using the ncid2ncid gateway, review ncid2ncid setup.
If using the obi2ncid gateway, review obi2ncid setup.
If using the rn2ncid gateway, review rn2ncid setup.
If using the sip2ncid gateway, review sip2ncid setup.
If using the wc2ncid gateway, review wc2ncid setup.
If using the yac2ncid gateway, review yac setup.

Table of Contents

Sections:

SYSTEM REQUIREMENTS:
COMPILE REQUIREMENTS:
COMPILE:
INSTALL or UPGRADE:
CONFIGURE:
FIRST STARTUP:
(AUTO)START/STOP:
CHECKING DAEMON STATUS:
TRIMMING LOG FILES:

SYSTEM REQUIREMENTS:

NCID should work on Mac OS X 10.4 (Tiger) and later versions, using both PowerPC (PPC) and Intel processors.

In order to use the NCID GUI client on Mac OS X 10.4 (Tiger) and 10.5 (Leopard), you must install ActiveTcl because the NCID GUI client requires the new tcl/tk "tile" package.

Furthermore, you must install a patch after ActiveTcl is installed to prevent a "BGError: bad attribute" error from occuring when you try to change the font. See instructions under the FIRST STARTUP section.

Mac OS X 10.6 (Snow Leopard) was unavailable for testing.

COMPILE REQUIREMENTS:

When building NCID from source, you must compile on a case-sensitive Mac filesystem. This requirement is ONLY for compiling NCID. Do not attempt to put other Mac OS X applications on a case-sensitive filesystem because they will probably not work as expected.

Use the diskutil utility to determine the filesystem type. Assuming you will be installing to the Mac's startup volume, i.e., the root filesystem:

diskutil info / | fgrep -i "file system"

The default Mac OS X filesystem type is 'Journaled HFS+' which is not case-sensitive.

Look for 'Case-sensitive' in the output of the diskutil command above. If you don't see it, you can create a small, case-sensitive disk image just so you can compile NCID. A 10 megabyte disk image should be more than adequate.

hdiutil create -size 10m -fs "Case-sensitive HFS+" -volname NCID ~/NCID.dmg

Next, mount the disk image: >hdiutil attach ~/NCID.dmg

and change to its directory where you will copy the source: >cd /Volumes/NCID

COMPILE:

See INSTALL.

INSTALL or UPGRADE:

NCID requires the server and at least one client to function. The server is required on one computer or device, but the client can be installed on as many computers as needed.

Install NCID:

The NCID package normally installs in /usr/local.

Copy ncid-VERSION-mac-osx.tgz to the Mac sudo tar -xzvf ncid-VERSION-mac-osx.tgz -C / EXAMPLE: sudo tar -xzvf ncid-1.2-mac-osx.tgz -C /

Copy ncid-VERSION-mac-osx_install.sh to the Mac sudo sh ncid-VERSION-mac-osx_install.sh EXAMPLE: sudo sh ncid-1.3-mac-osx_install.sh

Copy ncid-VERSION-src.tar.gz to the Mac tar -xzvf ncid-VERSION-src.tar.gz cd ncid
make mac (compiles for /usr/local, see top of Makefile) sudo make mac-install

Upgrade NCID:

The NCID package normally installs in /usr/local and configuration files are normally in /usr/local/etc/ncid.

Extracting the tar file will REPLACE the contents of all of the NCID configuration files. Be sure to back them up first. This includes all files in /usr/local/etc/ncid/.

Copy ncid-VERSION-mac-osx.tgz to the Mac sudo tar -xzvf ncid-VERSION-mac-osx.tgz -C / EXAMPLE: sudo tar -xzvf ncid-1.2-mac-osx.tgz -C

You will need to manually compare your backed up configuration files with the new ones, and manually edit any differences.

For an upgrade, the install script will preserve existing configurations, and new ones installed will have *.new as the extension.

Copy ncid-VERSION-mac-osx_install.sh to the Mac sudo sh ncid-VERSION-mac-osx_install.sh EXAMPLE: sudo sh ncid-1.3-mac-osx_install.sh

You will need to manually compare your current configuration files with the ".new" ones, and manually edit any differences.

Your existing configuration files will be preserved, and new ones installed will have .new as the extension.

Copy ncid-VERSION-src.tar.gz to the Mac: tar -xzvf ncid-VERSION-src.tar.gz cd ncid make mac (compiles for /usr/local, see top of Makefile) sudo make mac-install

You will need to manually compare your current configuration files with the ".new" ones, and manually edit any differences.

CONFIGURE:

The Makefile preconfigures ncidd.conf for the Mac, but you may want to change some of the defaults.

set noserial = 1

set noserial = 0 (this is the default)

FIRST STARTUP:

ActiveTcl8.4.19.6.295590-macosx-universal-threaded.dmg

sudo /usr/local/share/doc/ncid/fix-combobox

(AUTO)START/STOP:

SERVER

Under Mac OS X 10.4 and later, the mechanism used to start the NCID server processes is 'launchd' and requires 'plist' files in /Library/LaunchDaemons. Appropriate plist files for the NCID server processes are created automatically when NCID is installed, however, they must be manually activated.

Once activated, no action is typically required as the plist files are configured to automatically start each time the system boots.

Here is the complete list of plist files:

/Library/LaunchDaemons/net.sourceforge.ncid-initmodem.plist
/Library/LaunchDaemons/net.sourceforge.ncid-notify.plist
/Library/LaunchDaemons/net.sourceforge.ncid-page.plist
/Library/LaunchDaemons/net.sourceforge.ncid-samba.plist
/Library/LaunchDaemons/net.sourceforge.ncid-speak.plist
/Library/LaunchDaemons/net.sourceforge.ncid-yac.plist
/Library/LaunchDaemons/net.sourceforge.ncid2ncid.plist
/Library/LaunchDaemons/net.sourceforge.ncidd.plist
/Library/LaunchDaemons/net.sourceforge.sip2ncid.plist
/Library/LaunchDaemons/net.sourceforge.wc2ncid.plist
/Library/LaunchDaemons/net.sourceforge.yac2ncid.plist

You do not interact with launchd directly, instead you use the 'launchctl' command line utility.

You should only activate the NCID servers and client modules you need. Activating will also start the process immediately; there is no need to reboot.

The syntax for stopping the daemons is the same as starting them, except you use the 'unload' command instead of the 'load' command. Doing an unload stops the daemon immediately and prevents it from starting automatically the next time the system is booted.

Here are some examples:

sudo launchctl load -w /Library/LaunchDaemons/net.sourceforge.ncidd.plist

sudo launchctl unload -w /Library/LaunchDaemons/net.sourceforge.sip2ncid.plist

sudo launchctl load -w /Library/LaunchDaemons/net.sourceforge.ncid-page.plist

Review the man page (man launchctl).

CLIENT:

For the NCID GUI client, no .plist is currently provided because of the requirement that NCID must be installed as root, and the GUI preference file is specific to each user. However, a script called "ncid-gui" is installed for you automatically to the Applications folder. To have it start when you automatically log in, drag "ncid-gui" to your account's Login Items as described here: http://support.apple.com/kb/HT2602

After you login, you should close the front Terminal window that says, "Completed Command" in the title bar.

CHECKING DAEMON STATUS:

Use the launchctl 'list' command to show the daemons currently loaded, optionally using fgrep to filter out only NCID related processes.

Daemons currently running will have a process id.

Daemons which were stopped without an error will not be listed at all.

If a daemon has stopped due to an error, it will have no process id but will have a numeric exit status. Examine the contents of the /var/log/system.log file to determine the problem. Once you fix the problem, use the launchctl 'unload' command followed by the 'load' command.

Example: sudo launchctl list|fgrep net.sourceforge.ncid

        PID     Status  Label
        422     -       net.sourceforge.ncid-notify
        419     -       net.sourceforge.ncidd

TRIMMING LOG FILES:

The Mac uses newsyslog to trim files. To trim the cidcall.log and the ciddata.log files, add this entry to /etc/newsyslog.conf

/var/log/cid.log root:wheel 644 5 $M1D0 GN

Raspbian Install

Raspberry Pi DEB Package Install using Raspbian OS

If NCID does not work, see INSTALL for some simple tests.

If using the email2ncid gateway, review email2ncid setup.
If using the ncid2ncid gateway, review ncid2ncid setup.
If using the obi2ncid gateway, review obi2ncid setup.
If using the rn2ncid gateway, review rn2ncid setup.
If using the sip2ncid gateway, review sip2ncid setup.
If using the wc2ncid gateway, review wc2ncid setup.
If using the yac2ncid gateway, review yac2ncid setup.

Table of Contents

Sections:

COMPILE:
INSTALL or UPGRADE:
CONFIGURE:
FIRST STARTUP:
START/STOP/RESTART/RELOAD/STATUS:
AUTOSTART:
PACKAGE REMOVAL:
KNOWN ISSUE - MODEM MANAGER MAY HANG NCID AT BOOT TIME:

COMPILE:

It's very important to update the latest package info before continuing. Don't skip these two steps!

sudo apt-get update
sudo apt-get upgrade

The following package is required:

sudo apt-get install libpcap0.8-dev

This package is required to run obi2ncid, rn2ncid, wc2ncid and wct:

sudo apt-get install libconfig-simple-perl

This additional package is required to run wc2ncid (install via cpan, see below):

Data::HexDump

See INSTALL (generic) for compile instructions.

INSTALL or UPGRADE:

NCID requires the server and client DEB packages to function. The server is required on one computer or device, but the client can be installed on as many computers as needed.

The client has most of the output modules in its DEB package, but there are optional output modules in their own DEB packages.

The latest NCID can be installed from a Raspbian repository using apt-get if it is available.

If you cannot find a repository that contains NCID or if the latest packages are not available, you can download them from SourceForge and install them using gdebi or dpkg.

It's very important to update the latest package info before continuing. Don't skip these two steps!

sudo apt-get update
sudo apt-get upgrade
sudo apt-get install libpcap0.8-dev          
sudo apt-cache search ncid
  sudo apt-get install ncid
  sudo apt-get install ncid-client
sudo apt-get install ncid-gateways
sudo apt-get install ncid-<module>

If the latest packages are not available at the Raspbian repository:

Download ncid version 1.5 (required)

wget http://sourceforge.net/projects/ncid/files/ncid/1.5/ncid_1.5-1_armhf.deb

If using the client, download ncid-client version 1.5 (optional)

wget http://sourceforge.net/projects/ncid/files/ncid/1.5/ncid-client_1.5-1_all.deb

If using a gateway instead of a modem, download ncid-gateways version 1.5 (optional)

wget http://sourceforge.net/projects/ncid/files/ncid/1.5/ncid-gateways_1.5-1_all.deb
  • Download any optional output modules wanted (most modules are included with the client package)
ncid-<module>_<version>_all.deb
  • Method 1: Install or Upgrade the packages using gdebi-gtk (GUI):
  • If needed use the menu item "Add/Remove.." to install the GDebi Package Installer.
  • Using the file viewer:
  • Open the file viewer to view the NCID DEB packages
  • Select the DEB packages
  • Double-click selections or right-click selections and select "Open with GDebi Package installer"
  • Method 2: Install or Upgrade the packages using gdebi (command line):
  • Install gdebi if needed:
sudo apt-get install gdebi    
  • Install the NCID server:
sudo gdebi ncid-<version>_armhf.deb
  • Install the client package and default modules:
sudo gdebi ncid-client-<version>_all.deb
  • Install the optional gateways:
sudo gdebi ncid-gateways_<version>_all.deb
  • Install any optional modules wanted:
sudo gdebi ncid-<module>-<version>_all.deb
  • Method 3: Install or Upgrade the packages using dpkg (command line):
  • Install the NCID server:
sudo dpkg -i ncid-<version>_armhf.deb
  • Install the client package and default modules:
sudo dpkg -i ncid-client-<version>_all.deb
  • Install the optional gateways:
sudo dpkg -i ncid-gateways_<version>_all.deb
  • Install any optional modules wanted:
sudo dpkg -i ncid-<module>-<version>_all.deb
  • Force install of all dependencies:
sudo apt-get install -f

Notes:

<version> would be something like: 1.0-1
<module> would be a module name like: kpopup, mythtv, samba

CONFIGURE:

The ncidd.conf file is used to configure ncidd.

set ttyport = /dev/ttyACM1
set noserial = 1
set noserial = 0  (this is the default)

FIRST STARTUP:

sudo invoke-rc.d ncidd start  
ncid &
sudo invoke-rc.d ncidd start  
sudo invoke-rc.d sip2ncid start  
ncid &
cpan  

interactive mode, first use will enter configure configure as much as possible automatically choose sudo from: (Choose 'local::lib', 'sudo' or 'manual') automatically choose some CPAN mirror when configure finishes, it displays the cpan prompt: cpan[1]>

install Data::HexDump
quit (quits cpan)

sudo invoke-rc.d ncidd start  
sudo invoke-rc.d wc2ncid start  
ncid &
sudo invoke-rc.d ncidd start  
sudo invoke-rc.d yac2ncid start  
ncid &
sudo invoke-rc.d sip2ncid stop  
sudo invoke-rc.d ncidd stop

NOTE:

The ncid GUI client must be started after login, not boot. There is no ncid.init script to start or stop it. Instead, to automatically launch ncid in GUI mode you need to modify the autostart script for LXDE (Lightweight X11 Desktop Environment). The steps below are partly based on Method 2 as seen in this post and have been modified to work with the Wheezy and Jessie releases of Raspbian. These steps will need to be done for each user login where you want the ncid GUI to launch automatically.

sudo find ~/ -name autostart -exec nano {} \;
  • If ncidd is running locally on the RPi:
@ncid
  • If ncidd is on a different server or port, specify the IP address or host name, followed by the port number.

Examples:

ncidd running at 10.0.1.9 on default port 3333:

@ncid 10.0.1.9

ncidd running at 10.0.1.9 on port 3334:

@ncid 10.0.1.9 3334
ctrl-x  
y  
ENTER  

The next time the user(s) login the ncid GUI will start automatically.

START/STOP/STATUS:

Use the invoke-rc.d command to start any of the daemons. The invoke-rc.d commands are: start, stop, restart, reload, and status. The client can also be started using the output module name instead of ncid. All output modules can be run at the same time.

Here are some examples:

sudo invoke-rc.d ncidd start
sudo invoke-rc.d sip2ncid stop
sudo invoke-rc.d ncidd reload
sudo invoke-rc.d ncid-page start
sudo invoke-rc.d ncid-speak status

Review the man page: man invoke-rc.d

AUTOSTART:

Use the update-rc.d command to enable/disable the service at boot.

Here are some examples:

sudo update-rc.d ncidd defaults
sudo update-rc.d ncid-page defaults
sudo update-rc.d -f ncidd remove

Review the man page: man update-rc.d

See also this section about a known issue where ModemManager may hang NCID at boot time.

PACKAGE REMOVAL:

Use apt-get to remove any NCID package installed.

For example, to use apt-get to remove the ncid package:

sudo apt-get remove ncid
sudo apt-get purge ncid
sudo apt-get autoremove

Review the man page: man apt-get

KNOWN ISSUE - MODEM MANAGER MAY HANG NCID AT BOOT TIME:

This issue was first reported on a Raspberry Pi 3 running Ubuntu Mate. The symptoms and solution are the same as described in the Install-Ubuntu section.

Redhat/Centos/Enterprise RPM Package Install

If NCID does not work, see INSTALL for some simple tests.

If using the email2ncid gateway, review email2ncid setup.
If using the ncid2ncid gateway, review ncid2ncid setup.
If using the obi2ncid gateway, review obi2ncid setup.
If using the rn2ncid gateway, review rn2ncid setup.
If using the sip2ncid gateway, review sip2ncid setup.
If using the wc2ncid gateway, review wc2ncid setup.
If using the yac2ncid gateway, review yac2ncid setup.

Table of Contents

Sections:

COMPILE:
INSTALL or UPGRADE:
CONFIGURE:
FIRST STARTUP:
START/STOP/RESTART/RELOAD/STATUS:
AUTOSTART:

COMPILE:

The following packages are required:

See INSTALL (generic) for compile instructions

INSTALL or UPGRADE:

NCID requires the server and client RPM packages to function. The server is required on one computer or device, but the client can be installed on as many computers as needed.

The client has most of the output modules in its RPM package, but there are optional output modules in their own RPM packages.

      ncid RPM Package          - server (required)
      ncid-gateways RPM Package - gateways (optional)
      ncid-client RPM Package   - client and default output modules (optional)
      ncid-MODULE RPM Package  - optional client output modules
      Using the file viewer:
          * Open the file viewer to view the NCID RPM packages
          * Select the RPM packages
          * right click selections and select "Open with Package installer"

      Using YUM:
          * sudo yum install ncid\*.rpm

CONFIGURE:

The ncidd.conf file is used to configure ncidd.

      set ttyport = /dev/ttyS0
      set noserial = 1
      set noserial = 0  (this is the default)

FIRST STARTUP:

      sudo service ncidd start  
      ncid &
      service ncidd start  
      sudo service sip2ncid start  
      ncid &
      sudo service wc2ncid start  
      sudo service wc2ncid start  
      ncid &
      sudo service ncidd start  
      sudo service yac2ncid start  
      ncid &
      + stop the gateway used:  
        sudo service sip2ncid stop

      + stop the server:  
        sudo service ncidd stop

      + and continue reading the test sections.

NOTE:

The ncid client normally starts in the GUI mode and there is no ncid.init script to start or stop it.

There are rc.init scripts for starting ncid with output modules, for example:

ncid-page, ncid-kpopup, etc.

START/STOP/RESTART/RELOAD/STATUS:

Use the service command to start any of the daemons. The service commands are: start, stop, restart, reload, and status. The client can also be started using the output module name instead of ncid. All output modules can be run at the same time.

Here are some examples:

      sudo service ncidd start
      sudo service sip2ncid stop
      sudo service ncidd reload
      sudo service ncid-page start
      sudo service ncid-speak status

Review the man page (man service).

AUTOSTART:

Use the chkconfig command to turn the service on/off for starting at boot.

Here are some examples:

      sudo chkconfig ncidd on
      sudo chkconfig ncid-page on
      sudo chkconfig ncid-kpopup on
      sudo chkconfig --list sip2ncid
      sudo chkconfig ncid-speak off

Review the manpage (man chkconfig).

TiVo TAR Package Install

The ncid client replaces the old tivocid package. It functions exactly like TiVoCID, if it is called tivocid, or if it is given the proper options. The ncid client requires the out2osd package to be installed to display the CID information on the TV screen.

The ncid client is also called tivoncid and uses the new ncid-tivo output module that uses /tvbin/text2osd to display the CID information.

The NCID package includes both the client and server. For a series1, the server would normally be ignored unless you have a DirecTiVo, a hardware modified internal modem, or a modem connected to the serial port.

Table of Contents

Sections

COMPILE NCID

See the Compile section of INSTALL (generic).

Install TiVoCID, TiVoNCID, sip2ncid, and ncidd

You have a choice of using either tivocid or tivoncid as your display client. Tivocid uses out2osd which does not work on all TiVo software hardware combinations. Tivoncid should work on all TiVo software and hardware combinations.

It is recomended you use tivoncid.

Install or upgrade using the tar archive

If this is an upgrade, you need to save the configuration files first:

cp -a /var/hack/etc/ncid /var/hack/etc/ncid.old

If you have a series 1 TiVo, copy ncid-VERSION-tivo-ppc.tgz to the tivo and extract:

tar -xzvf ncid-VERSION-tivo-ppc.tgz -C /var

EXAMPLE:

tar -xzvf ncid-0.5-tivo-ppc.tgz -C /var

If you have a series 2 or later TiVo, copy ncid-VERSION-tivo-mips.tgz to the tivo and extract:

tar -xzvf ncid-VERSION-tivo-mips.tgz -C /var

EXAMPLE:

tar -xzvf ncid-0.5-tivo-mips.tgz -C /var

If this is an upgrade, modify any of the configuration files previously modified and saved in /var/hack/etc/ncid.old. The new configuration files may have new comments and lines that can be modified so do not replace a new configuration with the old one. Normally you would have modified just ncidd.conf and ncidd.alias.

Install or upgrade using the install script

Requirements: awk, diff, tail, and tar commands

Installs into /var/hack

Copy ncid-VERSION-tivo-ppc_install.sh to the tivo and then execute:

sh ncid-VERSION-tivo-ppc_install.sh

The install script will save changed configurations as *.new.

Optional: Install the TiVo OUT2OSD display program

The tivocid script uses out2osd for display. The out2osd program only works on a Series 1 and a Series 2. It is recomended you use the tivoncid script instead of tivocid.

Get and install the latest OUT2OSD display program. It is available as either a source tar file, or a TiVo binary tar package.

Optional: Install Perl

If you would like to use the cidcall, cidalias, and update scripts, you need to get and install Perl into /var/hack/bin

Configure ncidd, if you are running it on the TiVo

ncidd is compiled to use directories under /var/hack. You can change this if you like, by using the command line to specify the location of the config file, and then using the config file to set the options for your new directory structure.

If you are using a modem:

The ncidd.conf file is preconfigured for a TiVo. These are the lines enabled for a Series1 and a Series2:

set ttyclocal = 1  
set ttyport = /dev/ttyS1 # TiVo PPC Modem Port  
set lockfile = /var/tmp/modemlock

If you are using a standalone series1 without the modem hardware modification to enable Caller ID, you need to uncomment the line:

set ttyport = /dev/ttyS3 # TiVo MIPS Modem Port  

and comment out the line:

set ttyport = /dev/ttyS1 # TiVo PPC Modem Port  

If you are using using sip2ncid or yac2ncid instead of a modem, you need to uncomment the line:

# set noserial = 1

Start and verify the ncid package is working

Use the startncid script to start NCID and use stopncid to stop all running NCID programs.

After you configure and start startncid as indicated below, check that the programs are running:

pgrep -fl ncid

If you are running the server and client on the TiVo and are using tivoncid with a modem:

use the startncid script:

/var/hack/bin/startncid

startncid executes these commands:

ncidd  
tivoncid &

If you are running the server and client on the TiVo and are using tivoncid with sip2ncid:

uncomment one of the timezone lines, for example:

TZ=EST5EDT,M3.2.0,M11.1.0    # EASTERN TIME

uncomment this line in startncid:

SIPGW=sip2ncid

use the startncid script:

/var/hack/bin/startncid

startncid executes these commands:

ncidd  
sip2ncid
tivoncid &

If you are running the server and client on the TiVo and are using tivoncid with yac2ncid:

uncomment this line in startncid:

YACGW=yac2ncid

use the startncid script:

/var/hack/bin/startncid

startncid executes these commands:

ncidd  
yac2ncid  
tivoncid &

If you are only running the client on the TiVo, modify ncid.conf:

change this line: set Host 127.0.0.1  
to this line:     set Host < NCID server IP address >

Example using the command line:

tivoncid IP.Server.Address &

If the server is at 192.168.0.10, the above becomes:

tivoncid 192.168.0.10 &

If you are running the server and client on the TiVo and are using tivocid with a modem:

comment the OSDCLIENT line in startncid:

#OSDCLIENT=tivoncid

uncomment the OSDCLIENT line in startncid:

OSDCLIENT=tivocid

use the startncid script:

/var/hack/bin/startncid

startncid executes these commands:

ncidd  
tivocid &

Call yourself and see if it works, if not, kill off ncidd, if it is running, and continue reading the test sections.

Once you are satisfied that everything is working OK, complete the setup of NCID.

Completing ncidd setup

NCID has a start up script, /var/hack/bin/startncid, to start the server, gateway, clients you are using, and to set up the environment. It is preconfigured to start ncidd, and tivoncid. You need to edit it if you want to set up your local timezone, or if you want to start tivoncid instead of tivocid, sip2ncid, ncid-yac, or ncid-initmodem. Do not configure both tivocid and tivoncid or both will try to display the Caller ID on screen.

After you customise startncid, add /var/hack/bin/startncid to the /etc/rc.d/rc.sysinit.author file.

If you have a problem with your modem dropping out of Caller ID, you can use the ncid-initmodem module to re-initialize the modem when a call is detected without Caller ID. This module must only be used when you are using a modem to obtain the Caller ID. The modem must provide ring detection for this to work.

You can also use /var/hack/bin/initmodem manually or call it from cron to re-initialize the modem. It can be used with ncid-initmodem.

Test using a Modem

ncidd -D
ncidd -Dv3
ncidd -Dv9
Network Port: 3333  
Wrote pid 20996 in pidfile: /var/run/ncidd.pid  
End of startup: 04/01/2016 20:28:06
/dev/ttyS1: No such file or directory

you need to set ttyclocal in ncidd.conf.

ncidd    
ncidd -C /hack/etc/ncidd.conf

Test using sip2ncid

ncidd  
sip2ncid
tivocid or tivoncid
ncidd -D
ncidd -Dv3
ncidd -Dv9
Network Port: 3333  
Wrote pid 20996 in pidfile: /var/run/ncidd.pid  
End of startup: 04/01/2016 20:28:06

Test using yac2ncid

ncidd  
yac2ncid
tivocid or tivoncid
ncidd -D
ncidd -Dv3
ncidd -Dv9
Network Port: 3333  
Wrote pid 20996 in pidfile: /var/run/ncidd.pid  
End of startup: 04/01/2016 20:28:06

Install ncidd on a separate computer, if not using it on the TiVo

Get, install, and test the latest NCID server/client package for the computer you will run it on, if it is not the TiVo.

NCID is available as either a source tar file, or a Redhat RPM package,

Test the TiVo CID Client (if using tivocid)

tivocid -V  
tivocid -V IP.Server.Address.  
bash-2.02# Tmk Assertion Failure:  
FsAllocateFunction, line 131 ()
Tmk Fatal Error: Thread tivosh <252> died due to signal -2 
f9c51c 100df1c 100e18c 100e1dc dabe9c dab55c 400c50 108a0b0 
Restarting system.

The fix is to start it this way:

tivosh ncid --no-gui -T --call-prog --program /var/hack/bin/out2osd &
tivocid -R -V IP.Server.Address.

This will show everything received from the server, and the CID information it processes.

tivocid &
tivocid IP.Server.Address &

Test the TiVo NCID Client (if using tivoncid)

tivoncid -V  
tivoncid -V IP.Server.Address.  
bash-2.02# Tmk Assertion Failure:  
FsAllocateFunction, line 131 ()
Tmk Fatal Error: Thread tivosh <252> died due to signal -2 
100df1c 100e18c 100e1dc dabe9c dab55c 400c50 108a0b0 
Restarting

The fix is to start it this way:

tivosh ncid --no-gui -T --call-prog --program /var/hack/bin/out2osd &
tivoncid -R -V IP.Server.Address.

This will show everything received from the server, and the CID information it processes.

tivoncid &
tivoncid IP.Server.Address &

Files installed and modem information

The series1 tivo requires a hardware modification to support Caller ID, but you can hang a modem off of the serial port using the TiVo serial cable and a modem serial cable connected together.

Series1 information on the hardware modification needed, various CID init strings, and another Caller ID program can be found here:

Caller-id program for DirecTivo

TiVo Modems gives some information about the TiVo modems.

The tar file creates and populates the following directories

hack |-- bin |-- sbin |-- etc -- ncid -- conf.d |-- log |-- doc -- ncid -- man |-- dev |-- share -- ncid

Notes

Ubuntu DEB Package Install

If NCID does not work, see INSTALL for some simple tests.

If using the email2ncid gateway, review email2ncid setup.
If using the ncid2ncid gateway, review ncid2ncid setup.
If using the obi2ncid gateway, review obi2ncid setup.
If using the rn2ncid gateway, review rn2ncid setup.
If using the sip2ncid gateway, review sip2ncid setup.
If using the wc2ncid gateway, review wc2ncid setup.
If using the yac2ncid gateway, review yac2ncid setup.

Table of Contents

Sections:

COMPILE:
INSTALL or UPGRADE:
CONFIGURE:
FIRST STARTUP:
START/STOP/RESTART/RELOAD/STATUS:
AUTOSTART:
PACKAGE REMOVAL:
KNOWN ISSUE - MODEM MANAGER MAY HANG NCID AT BOOT TIME:

COMPILE:

It's very important to update the latest package info before continuing. Don't skip these two steps!

sudo apt-get update
sudo apt-get upgrade

The following packages are required:

sudo apt-get install build-essential  
sudo apt-get install libpcap0.8-dev

This package is required to run obi2ncid, rn2ncid, wc2ncid and wct:

sudo apt-get install libconfig-simple-perl

This additional package is required to run wc2ncid (install via cpan, see below):

Data::HexDump

See INSTALL (generic) for compile instructions.

INSTALL or UPGRADE:

NCID requires the server and client DEB packages to function. The server is required on one computer or device, but the client can be installed on as many computers as needed.

The client has most of the output modules in its DEB package, but there are optional output modules in their own DEB packages.

It's very important to update the latest package info before continuing. Don't skip these two steps!

sudo apt-get update
sudo apt-get upgrade

The official repository for Debian/Ubuntu has not been updated since NCID version 0.88 was released in January 2014. For this reason you should only install from the files at SourceForge.

Download ncid version 1.5 (required)

wget http://sourceforge.net/projects/ncid/files/ncid/1.5/ncid_1.5-1_amd64.deb  

If using the client, download ncid-client version 1.5 (optional)

wget http://sourceforge.net/projects/ncid/files/ncid/1.5/ncid-client_1.5-1_all.deb

If using a gateway instead of a modem, download ncid-gateways version 1.5 (optional)

wget http://sourceforge.net/projects/ncid/files/ncid/1.5/ncid-gateways_1.5-1_all.deb

Download any optional output modules wanted (most modules are included with the client package)

ncid-<module>_<version>_all.deb
  • Method 1: Install or Upgrade the packages using gdebi-gtk (GUI):
  • If needed use the menu item "Add/Remove.." to install the GDebi Package Installer.
  • Using the file viewer:
  • Open the file viewer to view the NCID DEB packages
  • Select the DEB packages
  • Double-click selections or right-click selections and select "Open with GDebi Package installer"
  • Method 2: Install or Upgrade the packages using gdebi (command line):
  • Install gdebi if needed:
sudo apt-get install gdebi    
  • Install the NCID server:
sudo gdebi ncid-<version>_amd64.deb
  • Install the client package and default modules:
sudo gdebi ncid-client-<version>_all.deb
  • Install the optional gateways:
sudo gdebi ncid-<version>_amd64.deb
  • Install any optional modules wanted:
sudo gdebi ncid-<module>-<version>_all.deb
  • Method 3: Install or Upgrade the packages using dpkg (command line):
  • Install the NCID server:
sudo dpkg -i ncid-<version>_amd64.deb
  • Install the client package and default modules:
sudo dpkg -i ncid-client-<version>_all.deb
  • Install the optional gateways:
sudo dpkg -i ncid-<version>_amd64.deb
  • Install any optional modules wanted:
sudo dpkg -i ncid-<module>-<version>_all.deb
  • Force install of all dependencies:
sudo apt-get install -f

Notes:

<version> would be something like: 1.0-1
<module> would be a module name like: kpopup, mythtv, samba

CONFIGURE:

The ncidd.conf file is used to configure ncidd.

set ttyport = /dev/ttyS0
set noserial = 1
set noserial = 0  (this is the default)

FIRST STARTUP:

sudo invoke-rc.d ncidd start  
ncid &
sudo invoke-rc.d ncidd start  
sudo invoke-rc.d sip2ncid start  
ncid &
cpan  

interactive mode, first use will enter configure configure as much as possible automatically choose sudo from: (Choose 'local::lib', 'sudo' or 'manual') automatically choose some CPAN mirror when configure finishes, it displays the cpan prompt: cpan[1]>

install Data::HexDump
quit (quits cpan)

sudo invoke-rc.d ncidd start  
sudo invoke-rc.d wc2ncid start  
ncid &
sudo invoke-rc.d ncidd start  
sudo invoke-rc.d yac2ncid start  
ncid &
sudo invoke-rc.d sip2ncid stop  
sudo invoke-rc.d ncidd stop

NOTE:

The ncid GUI client must be started after login, not boot. There is no ncid.init script to start or stop it.

START/STOP/RESTART/RELOAD/STATUS:

START/STOP/STATUS:

Use the invoke-rc.d command to start any of the daemons. The invoke-rc.d commands are: start, stop, restart, reload, and status. The client can also be started using the output module name instead of ncid. All output modules can be run at the same time.

Here are some examples:

sudo invoke-rc.d ncidd start
sudo invoke-rc.d sip2ncid stop
sudo invoke-rc.d ncidd reload
sudo invoke-rc.d ncid-page start
sudo invoke-rc.d ncid-speak status

Review the man page: man invoke-rc.d

AUTOSTART:

Use the update-rc.d command to enable/disable the service at boot.

Here are some examples:

sudo update-rc.d ncidd defaults
sudo update-rc.d ncid-page defaults
sudo update-rc.d -f ncidd remove

Review the man page: man update-rc.d

See also this section about a known issue where ModemManager may hang NCID at boot time.

PACKAGE REMOVAL:

Use apt-get to remove any NCID package installed.

For example, to use apt-get to remove the ncid package:

sudo apt-get remove ncid
sudo apt-get purge ncid
sudo apt-get autoremove

Review the man page: man apt-get

KNOWN ISSUE - MODEM MANAGER MAY HANG NCID AT BOOT TIME:

Symptoms:

ModemManager is attempting to query modems (including bluetooth and other serial devices) at boot time by sending "AT+GCAP" (the AT command for a modem to "Request Complete Capabilities List"). This conflicts with the NCID server initializing the modem at the same time.

The solution is to disable ModemManager completely by issuing the following commands:

sudo systemctl disable ModemManager
sudo systemctl stop ModemManager
sudo systemctl status ModemManager

The disable line will prevent ModemManager from starting at boot.

The stop line will terminate the currently running instance of ModemManager.

The status lines should look like this:

o ModemManager.service - Modem Manager  
   Loaded: loaded (/lib/systemd/system/ModemManager.service; disabled; vendor pr  
   Active: inactive (dead)  

Loaded: will show disabled and Active: will show inactive (dead).

For USB modems, an alternative would be to create a udev rule as described here or here that will exclude only the NCID modem from being probed.

Windows Install

Install either the Windows client package or the complete package.

Table of Contents

Sections:

WINDOWS CLIENT INSTALL:
WINDOWS COMPLETE COMPILE:
WINDOWS COMPLETE INSTALL:
NCID.TCL INSTALL:

WINDOWS CLIENT INSTALL:

Install this package if you only need the client.

      ncid-?.?-setup.exe  

where ?.? is the version number, for example:

      ncid-1.0-setup.exe
      "ncid.sourceforge.net" or "192.168.22.10"

WINDOWS COMPLETE COMPILE:

See INSTALL (generic) and
INSTALL-Cygwin or
INSTALL-Ubuntu.

WINDOWS COMPLETE INSTALL:

INSTALL-Ubuntu on Windows or
INSTALL-Cygwin

if you need to install the complete NCID package, including server, client, and gateways.

The serial port functions of ncidd do not work under Windows or Cygwin so you must use the SIP or YAC gateway with it. It is unknown if a modem will work under Ubuntu so you may need to use a gateway with it also. If a modem is usable, it should be a modem that supports Linux like the USB modems described in Incomplete list of working modems.

NCID under Cygwin is a fairly complex command line install, and there are some performance issues with it. It is recommended you try Ubuntu.

See INSTALL-Cygwin if you want to install Cygwin and NCID.

NCID under Ubuntu is an easy install. You can use the GUI based package manager to install/update/remove it.

See INSTALL-Ubuntu if you want to install Ubuntu and NCID.

NCID.TCL INSTALL:

Use this method only if you want to run ncid.tcl instead of ncid.exe This was the original install method. You need to get ncid.tcl from the source package.

Download the tcl/tk interpreter:

Install tcl/tk:

Install ncid:

      c:\ncid\ncid.tcl

for example, if Target has C:

add IP address:

        C:\ncid 192.168.0.1

or, if path, in Target has spaces:

        E:\Program Files\ncid

add quotes around path, then add the IP address or DNS name:

        "E:\Program Files\ncid" 192.168.0.1

Obtaining Caller ID

Table of Contents

Description

Description

NCID requires hardware to obtain Caller ID. It can be a supported modem, a supported device, or a gateway.

Devices Supported
Modems
Gateways

Devices Supported

Table of Contents

Devices Index


Modems

Any Caller ID serial or USB modem supported by the operating system can be used. See Incomplete list of working modems.

If the modem supports FAX, the server can answer a call, produce receiving FAX tones for about 10 seconds, then hangup if the FAX hangup option is enabled.

NCID can also use those rare modems that do not support Caller ID by configuring gencid in ncidd.conf, but such modems are limited to the following features:

See the modem Configuration section for information on configuring modems.


ATA (Analog Terminal Adapter)

The ATA hardware is for VoIP (Voice over Internet Protocol).

VoIP telephone services use an Analog Terminal Adapter, sometimes called a VoIP gateway.

See also VoIP Info.

In order to receive Caller ID from VoIP, the local network must be configured. Three configurations are considered here:

One device: Cable/DSL Modem with integrated ATA device

Many cable companies such as Comcast and Time Warner now offer bundled services, referred to in the industry as "triple play service." This delivers television, Internet service, and digital phone service via a single device.

The protocol used for the digital phone service is usually proprietary.

NCID is not supported in this configuration.

Two devices: Cable/DSL Modem + Router Switch with integrated ATA device

These router and ATA combo devices may be configured to put the Caller ID on the built-in switch. If you have other routers working, please contribute to this list:

ROUTER    MODEL      SETTINGS     CONFIGURATION
------    -----      --------     -------------
Linksys  WRTP54G        -         (has "P" in model name)
use Vonage Talk
Linksys  RT31P2        DMZ        put computer IP address in the DMZ

Three devices: Cable/DSL Modem + Router Switch + ATA device

A stand-alone ATA device connected to your network will make its Caller ID info (Session Initiation Protocol, or SIP) available to all the other network devices that are listening for it. A typical setup has the ATA connected to one physical port on the router/switch, and the computer running NCID is connected to a different physical port. Most modern routers/switches isolate the network traffic on any one physical port from all the other physical ports. This is done on purpose to optimize network traffic throughput and provide better performance.

The problem is that having the network traffic isolated in this way does not allow the NCID computer to ever receive the Caller ID info from the ATA.

To circumvent this problem, you have several options:

A. Use an Ethernet Tap.

This is the preferred method to obtain Caller ID. The 

USB Powered 5-Port 10/100 Ethernet Switch TAP by DualComm is a good choice and has been successfully used with NCID. The Dualcomm USB powered 5-port Ethernet Switch TAP provides mirrors all ethernet traffic on port 1 to port 5. Simply plug your ATA into port 1 and your NCID server into port 5.

B. Use port mirroring.

Port mirroring is not port *forwarding*.

This method requires that your home router be running a Linux-based operating system such as OpenWRT or DD-WRT.

        STEPS TO CONFIGURE DD-WRT
        =========================

        Use ssh to connect to your router and enter the following commands:
           iptables -t mangle -A POSTROUTING -d IP-OF-SIP_ATA -j ROUTE --tee --gw IP-OF-NCID-SERVER
           iptables -t mangle -A PREROUTING -s IP-OF-SIP_ATA -j ROUTE --tee --gw IP-OF-NCID-SERVER 
        To verify the port mirror is setup properly, use:
           iptables -t mangle -L -v -n
        Which will provide output that should show something similar to:
           Chain PREROUTING (policy ACCEPT 4510K packets, 2555M bytes)
           pkts bytes target prot opt in out source destination
           ....
           219 152K ROUTE 0 -- * * IP-OF-SIP_ATA 0.0.0.0/0 ROUTE gw:IP-OF-NCID-SERVER tee
           ....

           Chain POSTROUTING (policy ACCEPT 17M packets, 7764M bytes)
           pkts bytes target prot opt in out source destination
           ....
           206 82184 ROUTE 0 -- * * 0.0.0.0/0 IP-OF-SIP_ATA ROUTE gw:IP-OF-NCID-SERVER tee
           ....
        Follow the sip2ncid instructions to make sure that SIP packets are being received.

        When everything is working properly, add the port mirroring commands to the DD-WRT 
        startup commands in the Management tab so that they will be run whenever DD-WRT is rebooted.

C. Use Ettercap.

Convince your router to send all SIP packets to your NCID server

and have your NCID server pass the packets on to your ATA. This is most easily and robustly accomplished through the use of ettercap.

        STEPS TO CONFIGURE ETTERCAP
        ===========================

        Perform these steps from a command prompt on your NCID server.

        To determine the proper INTERFACE for ettercap to use, `ifconfig` will show all available 
        interfaces. For example, wired ethernet is eth0 and wireless ethernet is wlan0 on Raspbian.
        Install ettercap if on Ubuntu, Raspbian and other Debian-based systems:
           sudo apt-get install ettercap-text-only
        Install ettercap if on Fedora and other Redhat-based systems:
           sudo dnf install ettercap
        Execute ettercap if using IPV6
           sudo ettercap -T -D -i <INTERFACE> -M arp:remote /<IP-OF-SIP_ATA>/ /<IP-OF-HOME-ROUTER>/
        Execute ettercap if using IPV4
           sudo ettercap -T -D -i <INTERFACE> -M arp:remote //<IP-OF-SIP_ATA>// //<IP-OF-HOME-ROUTER>//
        Follow the sip2ncid setup instructions to make sure that SIP packets are being received.
        You will want to add ettercap to your operating system startup sequence. Steps to do this
        vary depending on distribution and even depending on the version of a specific distribution.
        Consult your operating system documentation on how to do this.
  1. Use an Ethernet hub. (Historical, not recommended)
Ethernet hubs pre-date

Ethernet switches and do not isolate network traffic between physical ports. Ethernet switches have largely rendered Ethernet hubs obsolete. Some Ethernet hubs manufactured today are actually Ethernet switches in disguise. See the hub reference to determine if a hub is really a hub.

E. Use a router that supports SIP ALG (Application-level gateway). (Historical, not recommended)

Unfortunately, not all routers implement ALG correctly. The following

routers are known to use ALG properly with NCID. If you have other routers working, please contribute to this list:

ROUTER    MODEL      SETTINGS     CONFIGURATION
------    -----      --------     -------------
Linksys   WRT54G        -         (no "P" in model name) 
SIP packets on port 5060 may need a firmware update
if the firmware version is below 1.00.6. 
See http://www.voip-info.org/wiki-Linksys+WRT54G 
for firmware info.
Linksys   RVS4000    L2 Switch    mirror port #1 to port #2 
assumes gateway is port #1 and NCID SIP gateway is 
monitoring port #2


NetCallerID serial device

The NetCallerID device is used in place of a modem. It is no longer manufactured by Ugotcall but you can sometimes find it on eBay.

The ncidd server must be configured to use it. The server normally assumes a modem is going to be used so it must be configured to use a serial NetCallerID device that does not use AT commands.

Uncomment these lines in ncidd.conf (this assumes the device is connected to serial port 0):

 # set ttyport = /dev/ttyS0               # Linux Serial Port 0
 # set ttyspeed = 4800 # NetCallerID port speed
 # set nomodem = 1

Here are the specifications of the NetCallerID device:

ttyport:

 4800 8N1

Output Format:

 ###DATE08082225...NMBR14075551212...NAMEJOHN+++\r
 ###DATE...NMBR...NAME   -MSG OFF-+++\r


Tel-Control, Inc. (TCI) serial devices

TCI caller ID units are used in place of one or more modems. The company is no longer in business, but you can sometimes find units on eBay or at telephone equipment liquidators. As an alternative, Whozz Calling serial devices are direct replacements for TC-1041, MLX-41, TC-1082 and MLX-42 units. NCID has been tested with a TC-1041.

Configure the TCI unit to use a baud rate of 9600. There are two banks of switches located on the front of the unit labeled S1 and S2. On bank S2 you want to set DIP switch 1 and 2 to both be ON for a 9600 baud rate.

The ncidd server must be configured to use it. The server normally assumes a modem is going to be used so it must be configured to use a serial device that does not use AT commands.

Uncomment these lines in ncidd.conf (this assumes the device is connected to serial port 0):

 # set ttyport = /dev/ttyS0               # Linux Serial Port 0
 # set ttyspeed = 9600 # TCI serial device port speed
 # set nomodem = 1

TCI units supply their own line id to ncidd as a two-digit number. The default setting for lineid in ncidd.conf is a dash, and ncidd will automatically replace the dash with this two-digit number.

You may, if you wish, prefix the two-digit number with a meaningful identifier, such as 'MLX-', by uncommenting this line in ncidd.conf

 # set lineid = POTS

and changing it to

 set lineid = MLX-

Here are the specifications of the TCI serial device:

ttyport:

 9600 8N1

Output Format is fixed field with total length of 70 bytes:

 01      9/05     11:17 AM       702-555-1145           CARD SERVICES  
 02      9/05      2:00 PM            PRIVATE                          


Whozz Calling serial devices

Whozz Calling serial devices are used in place of one or more modems. They are currently supported by NCID only when the Output Format switch is set to TCI.

Set DIP switch 5 to OFF for a baud rate of 9600.

Set DIP switch 7 to ON for TCI output format.

The ncidd server must be configured to use it. The server normally assumes a modem is going to be used so it must be configured to use a serial device that does not use AT commands.

Uncomment these lines in ncidd.conf (this assumes the device is connected to serial port 0):

 # set ttyport = /dev/ttyS0               # Linux Serial Port 0
 # set ttyspeed = 9600 # TCI serial device port speed
 # set nomodem = 1

The TCI output format supplies its own line id to ncidd as a two-digit number. The default setting for lineid in ncidd.conf is a dash, and ncidd will automatically replace the dash with this two-digit number.

You may, if you wish, prefix the two-digit number with a meaningful identifier, such as 'WC-', by uncommenting this line in ncidd.conf

 # set lineid = POTS

and changing it to

 set lineid = WC-

Here are the specifications of the Whozz Calling serial device in TCI mode:

ttyport:

 9600 8N1

Output Format is fixed field with total length of 70 bytes:

 01      9/05     11:17 AM       702-555-1145           CARD SERVICES  
 02      9/05      2:00 PM            PRIVATE                          


A Whozz Calling (WC) Caller ID and Call monitoring unit is used in place of one or more modems. There are various models that all monitor incoming calls, and some can monitor outbound as well.

See CallerID.com.

Refer to the wc2ncid setup in the Gateways section to configure NCID to work with the WC device.


Obihai VoIP Telephone Adapters and IP Phone

Obihai sells the OBi1032 IP phone and the popular OBi100, OBi110, OBi200, OBi202 VoIP telephone adapters.

OBi devices equipped with a USB port also support the OBiLINE FXO to USB Phone Line Adapter. The OBiLINE provides PSTN (or POTS) connectivity to phones attached to the OBi device as well as to calls bridged from VoIP services to a land-line service via the OBi.

It appears that OBi devices require at least one third party VoIP service provider, even if you intend to use a POTS line as your primary incoming and outgoing service.

The OBi110 comes with an FXO port built-in.

Only the OBi100, OBi110, OBi200 with OBiLINE, and OBi202 with OBiLINE, were available for development and testing. The other OBi products may work completely, partially, or not at all.

Modems

Table of Contents

Index

NCID Modem Requirements

The modem must be supported by the Operating System (Linux, FreeBSD, Macintosh, etc.) where NCID is running.

The absolute minimum modem feature that NCID requires is a modem that indicates RING, even if it does not support Caller ID. By default, if ncidd does not detect Caller ID by ring number two, it will generate a pseudo-Caller ID by setting the number to "RING" and the name to "No Caller ID". This default behavior can be disabled.

The ideal minimum is a modem that supports Caller ID.

A modem supporting FAX and/or VOICE modes is required for the optional FAX and ANNOUNCE hangup features respectively.

Some modems come configured for the US. If you live in a different country and your modem does not work, check the ncidd.log file for the country code. It will give either the bare code or the code and country, for example:

Modem country code: B5 United States

See the Modem Country Codes section for a list of country codes.

You can use minicom to set your country code. It only needs to be set once. Do not include it in ncidd.conf.

For example, if you live in the UK, you would issue this command using minicom:

AT+GCI=B4

Configuration

The tty port of the modem is set in ncidd.conf. NCID packages for specific distributions (Fedora, Ubuntu, etc.) are usually pre-configured for an appropriate default port. You can change the default by editing ncidd.conf and simply uncommenting the appropriate ttyport line, or add a new port.

The default tty port:
    /dev/modem
Default Mac OS X internal modem:
    set ttyport = /dev/cu.modem
Mac OS X USB modem (DualComm, Zoom):
    set ttyport = /dev/cu.usbmodem24680241
Linux Serial Port 0:
    set ttyport = /dev/ttyS0
Linux USB modem 0:
    set ttyport = /dev/ttyACM0

Distinctive Ring (DR)

From: DISTINCTIVE RING & MODEMS

You can find out whether your modem supports DR by connecting to its COM port via Windows HyperTerminal (or using the Unix program minicom) and issuing the appropriate AT command; if it responds with an "OK", it does, otherwise it does not.

The AT command to enable DR depends on the modem chipset:
Chipset                Command
3Com/USR/TI            ATS41=1
Rockwell/Conexant      AT-SDR=7
Lucent/Agere           AT+VDR=1,0

Each chipset reports DR differently:

3Com reports ring codes: > RING A, RING B, RING C

Rockwell reports ring codes: > RING 1, RING 2, RING 3

Lucent reports the actual ring cadence (the duration of the ringing and the silent periods) with DROF/DRON messages.

As an example, one long ring usually indicates the main phone number, and two short rings usually indicates the first DR phone number. Responses below were generated by two short rings:

3Com: > RING B

Rockwell: > RING 2

Lucent: > DRON=5
DROF=11
DRON=5
DROF=34

Modem Caller ID Test

Start ncidd in debug mode with verbose level 3. You do not need to start any client.

ncidd -Dv3

You should get something similar to the following. The important part is the last line: Modem is fd x where x is usually a number less than 10

Started: 05/04/2011 21:48:14
Server: ncidd (NCID) 0.81.15  
logfile: /var/log/ncidd.log  
Command line: ncidd  
              -Dv3  
Processed config file: /etc/ncid/ncidd.conf  
Verbose level: 3  
Configured to send 'cidlog' to clients.  
Configured to send 'cidinfo' to clients.  
Processed alias file: /etc/ncid/ncidd.alias  
Leading 1 from a call required in an alias definition  
CID logfile: /var/log/cidcall.log  
CID logfile maximum size: 110000 bytes  
Data logfile: /var/log/ciddata.log  
Telephone Line Identifier: -  
TTY port opened: /dev/ttyACM0  
TTY port speed: 19200  
TTY lock file: /var/lock/lockdev/LCK..ttyACM0  
TTY port control signals enabled  
CallerID from AT Modem and optional gateways  
Handles modem calls without Caller ID  
Sent Modem 20 of 20 characters:  
AT Z S0=0 E1 V1 Q0  
Modem response: 26 characters in 1 read:  
AT Z S0=0 E1 V1 Q0  
OK  
Try 1 to init modem: return = 0.  
Modem initialized.  
Sent Modem 11 of 11 characters:  
AT+VCID=1  
Modem response: 17 characters in 1 read:  
AT+VCID=1  
OK  
Modem set for CallerID.  
Network Port: 3333  
Debug Mode  
Not using PID file, there was no '-P' option.  
Modem is fd 4

If you did start a client, you will get a line something like:

Client 6 from 127.0.0.1 connected, sent call log: /var/log/cidcall.log

Next, call yourself, and you should see something like:

RING  
CIDINFO: *LINE*VOIP*RING*1*TIME*21:49:49*  
DATE = 0504  
TIME = 2149  
NMBR = 4075551212  
NAME = Chmielewski Joh  
CID: *DATE*05042011*TIME*2149*LINE*VOIP*NMBR*4075551212*MESG*NONE*NAME*John*  
RING  
CIDINFO: *LINE*VOIP*RING*2*TIME*21:49:55*

Hang up the phone, and a second or two later you should see:

CIDINFO: *LINE*VOIP*RING*0*TIME*21:50:02*

Do a <CTRL-C> to break out and end the test:

^CReceived Signal 2: Interrupt  
Terminated: 05/04/2011 21:53:30

If your modem does not support CID, ncidd will generate a CID line on ring 2 to indicate "No Caller ID" by setting the number to "RING" and the name to "No Caller ID". You will get something like:

RING  
CIDINFO: *LINE*VOIP*RING*1*TIME*21:53:02*  
RING  
CIDINFO: *LINE*VOIP*RING*2*TIME*21:53:08*  
CID: *DATE*05042011*TIME*2153*LINE*VOIP*NMBR*RING*MESG*NONE*NAME*No Caller ID*  
RING  
CIDINFO: *LINE*VOIP*RING*3*TIME*21:53:14*

If ncidd is configured to not generate a CID line for "No Caller ID" (ncidd.conf has gencid=0), you will get something like:

RING  
CIDINFO: *LINE*VOIP*RING*1*TIME*21:53:02*  
RING  
CIDINFO: *LINE*VOIP*RING*2*TIME*21:53:08*  
RING  
CIDINFO: *LINE*VOIP*RING*3*TIME*21:53:14*

Hang up the phone, and a second or two later you should see:

CIDINFO: *LINE*VOIP*RING*0*TIME*21:53:21*

Do a <CTRL-C> to break out and end the test:

^CReceived Signal 2: Interrupt  
Terminated: 05/04/2011 21:53:30

Modem Commands that configure Caller ID

AT#CID=1

Enables Caller ID in USR, Texas Instruments, Rockwell compatible modems (excluding software modems and Rockwell HCF), Hayes, several Pace modems, PowerBit, GVC, PCTel, IDC (VR series) devices, Diamond Supra (Rockwell compatible).

AT+VCID=1
or
AT+FCLASS=8;+VCID=1

Enables Caller ID in all IS-101 modems, Lucent LT, Rockwell HCF (V.90 or K56FLEX, e.g. PCI modems from Creative), some Pace modems (IS-101 compatible), Multitude, IDC, Cirrus Logic, most IDC modems.

AT#CLS=8#CID=1

Enables Caller ID in voice mode on some 56K USR modems, some Rockwell compatible (Boca Research, Cardinal, voice Zoom).

AT#CC1

Enables Caller ID on older non-voice Aspen modems, older Cirrus Logic, Motorola Voice Surfer, Phoebe.

AT*ID1

Enables Caller ID on some Motorola modems.

AT%CCID=1
or
AT%CCID=3

Enables Caller ID on Practical Peripherals modems.

AT$JSCID=4,1
or
AT$JSCD=1,0

Enables Caller ID on ELSA ML 56k Internet II (Netherlands) modems.

AT#CID=1
or
AT+VCID=1

Enables Caller ID on most modems not listed above.

AT+FCLASS=8
or
AT+FCLASS=8;+VCID=1
or
AT-STE=1;+VCID=1

Generic commands to select Active Service Class (Voice Mode) on most voice modems.

AT+VRID=0

The other AT commands above enable Caller ID during an incoming call. This command reports the most recently received Caller ID after a call has completed. It can sometimes be useful in testing.

Modem Country Codes

U.S. Robotics Country Codes

This extended syntax command selects and indicates the country of operation for the modem. It determines the settings for any operational parameters that need to be adjusted for national regulations or telephone networks.

Syntax

+GCI=CountryCode

Defined values for supported countries are:

Country        Code     Country       Code     Country        Code
Austria         0A      Iceland        52      Poland          8A
Belgium         0F      Ireland        57      Portugal        8B
Cyprus          2D      Israel         58      Spain           A0
Czech Republic  2E      Italy          59      Slovakia        FB
Denmark         31      Latvia         F8      Slovenia        FC
Estonia         F9      Liechtenstein  68      Sweden          A5
Finland         3C      Lithuania      F7      Switzerland     A6
France          3D      Luxembourg     69      TBR-21(Default) F6
Germany         42      Malta          B4      Turkey          AE
Greece          46      Netherlands    7B      United Kingdom  B4
Hungary         51      Norway         82      United States   B5

The factory default is F6 indicating TBR-21.

TBR-21 is a European telecommunications standard to which all telephone equipment must adhere to, to be allowed connection to Europe's public switched telephone network. It is the default even for U.S. Robotics modems sold in the United States.

Command to report current country code value

+GCI?

Command Response:
+GCI: CountryCode
Response Example for France:
+GCI: 3D

Command to report all supported country code values

+GCI=?

Command Response:
+GCI: (CountryCode[,CountryCode][,CountryCode])
Response Example:

This indicates the modem has been set for use in the United Kingdom, France or Germany.

+GCI: (B4,3D,42)

ACM5003-M Modem Country Code List (subset of the T.35 Country Code List used by most modems)

Code Country         Code Country             Code Country
00   Japan           53   India               9C   Singapore
07   Argentina       54   Indonesia           9F   South Africa
09   Australia       57   Ireland             A0   Spain
0A   Austria         58   Israel              A1   Sri Lanka
0F   Belgium         59   Italy               A5   Sweden
16   Brazil          61   Korea (Republic of) A6   Switzerland
1B   Bulgaria        62   Kuwait              A9   Thailand
20   Canada          64   Lebanon             AD   Tunisia
25   Chile           69   Luxembourg          AE   Turkey
26   China           6C   Malaysia            B3   United Arab Emirates
27   Columbia        73   Mexico              B4   United Kingdom
2D   Cyprus          77   Morocco             B5   Unites States
2E   Czech Republic  7B   Netherlands         B7   Uruguay
31   Denmark         7E   New Zealand         B8   Russia
36   Egypt           82   Norway              F9   Estonia
3C   Finland         84   Pakistan            FA   US Virgin Islands
3D   France          89   Philippines         FB   Slovakia
42   Germany         8A   Poland              FC   Slovenia
46   Greece          8B   Portugal            FD   (Universal)
50   Hong Kong       8E   Romania             FE   Taiwan
51   Hungary         98   Saudi Arabia
52   Iceland         99   Senegal

TiVo Modems

TiVo modems supported by NCID:

External modem connected to the TiVo serial 'headphone' Port (Method #1)

This method was given by 'nsysblh' in this thread: Caller-id program for DirecTivo

The modem must be set to ignore DTR before attaching it to the TiVo. Hook the modem up to a separate computer and use this string to set DTR:

AT&F0&D0&B1#CID=1&W

Wire a cable between the modem and the TiVo as follows:

        Modem DB25        TiVo Headphone Plug
        ----------        -------------------
        pin 2 TD    <---  Tip    (Center)
        pin 3 RD    --->  Ring   (Middle)
        pin 7 Gnd   --->  Ground (Outside) 

(Pins 3 and 7 are contributed by 'nsysblh'; pin 2 is contributed by an unknown author.)

External modem connected to the TiVo 'headphone' serial Port (Method #2)

This method was given by 'dgrover' in this thread: Tivo->modem cable

Wire a cable between the modem and the TiVo as follows:

        Modem DB25        TiVo Headphone Plug
        ----------        -------------------
        pin 2 TD    <---  Tip    (Center)
        pin 3 RD    --->  Ring   (Middle)
        pin 7 Gnd   --->  Ground (Outside) 

        pin 4 RTS   <--\
        pin 5 CTS   ---/

        pin 6 DSR   ---\
        pin 20 DTR  <--/

Attach the modem to the TiVo and test it using:

ncidd -D -I AT

Call yourself and verify that it works, then <CTRL-C> out of it.

TiVo Series 1 Internal Modem

The TiVo series 1 internal modem requires the following hardware modification to make it support Caller ID. It was contributed by 'ElectricLegs' and drawn by 'Saturn49' in thread Caller-id program for DirecTivo. Even with this hardware modification, the internal modem does not seem to be reliable for Caller ID.

      /-------# #------|47K ohm|-----\
      |       | |                    #
      |14    11 10                1  |
      | | | | | | | | | | | | | | |  ------
      | ---------------------------  | Q3 |
      | |                        *|  ------  
      | |         K2 952          |  |  |
      | |                         |
      | ---------------------------
      | | | | | | | | | | | | | | |
      |15        20               28
      |           |
      |           |      (-)
      \|JUMPER|---#---------| C29 |-

The #'s are points that will have to be soldered to the TiVo's board.

TiVo Series 2 Internal Modem

Supports Caller ID

TiVo Series 3 Internal Modem

Supports Caller ID

DirecTiVo Internal Modem

Some, maybe most, modems in DirecTivo work with Caller ID.

This is also in the thread:

Caller-id program for DirecTivo

NCID Gateways

Table of Contents

Gateways Index

email2ncid setup
ncid2ncid setup
obi2ncid setup
rn2ncid setup
sip2ncid setup
wc2ncid setup
yac2ncid setup


email2ncid setup

How to setup the email-to-NCID message gateway to convert an email into an NCID message and send it to the NCID server. If the notify option is used, it will only send the email subject line to the NCID server.

Sections:

REQUIREMENTS
CONFIGURATION
TESTING
STEP-BY-STEP SETUP FOR RASPBERRY PI

REQUIREMENTS:

CONFIGURATION:

Forward port 25 TCP/UDP to the computer running the MTA.

Run the following setup script to create or update $HOME/.procmailrc:

    ncid-setup email2ncid

The $HOME/.procmailrc file is configured to pipe to email2ncid when the subject line is NCID Message. A commented out recipe will pipe to email2ncid --notify if the From: email address matches. A second commented out recipe will forward the email if the From: email address matches.

TESTING:

You can test if email2ncid is configured for the email server and can connect to it. The test line and result should be similar to:

   $ echo test | email2ncid -t3
     > test
     test=3
     Configuration File: /etc/ncid/email2ncid.conf
     mesg=0 start=0 plain=0 html=0 multi=0 meta=0 status=0
     ncidserver: localhost:3334
         200 Server: ncidd (NCID) 1.5
         210 API: 1.3 Feature Set 1 2 3 4
         253 No Call log

Next, send an email to yourself at the host name you picked for the Dynamic DNS service. The subject line must be: NCID Message

If it does not work, save the email message. You can retest it by: > cat saved_email_message | email2ncid -t1

Review email2ncid.1 for more information.

STEP-BY-STEP SETUP FOR RASPBERRY PI:

How to setup the email2ncid gateway on the Raspberry Pi for user pi.

with the following settings:

Configuration Parameter Select or Type In
Mail Server Configuration info screen Ok
General type of mail configuration: mail sent by smarthost; received via SMTP or fetchmail
System mail name: raspberrypi Accept default
Mail Server Configuration info screen Ok
IP-addresses to listen on for incoming SMTP connections: 127.0.0.1 ; ::1 Replace with 0.0.0.0
Other destinations for which mail is accepted: raspberrypi Add a semicolon and then your Internet host name: raspberrypi;foobar.freedynamicdns.us
Machines to relay mail for: Leave blank
IP address or host name of the outgoing smarthost: Change to blanks if no outgoing mail or enter your service provider outgoing smarthost
Hide local mail name in outgoing mail? No
Mail Server Configuration info screen Ok
Keep number of DNS-queries minimal (Dial-on-Demand)? No
Delivery method for local mail: mbox format in /var/mail/
Split configuration into small files? No
Root and postmaster mail recipient: Add user id, for Raspberry Pi it is usually pi


ncid2ncid setup

How to setup the ncid2ncid gateway to forward caller ID and messages from multiple NCID sending servers (four maximum) to a single NCID receiving server.

Sections:

REQUIREMENTS
CONFIGURATION
TESTING
START/STOP/RESTART/STATUS/AUTOSTART

REQUIREMENTS:

One NCID receiving server and at least one NCID sending server.

CONFIGURATION:

The ncid2ncid process connects to a receiving server as a gateway, that is, a device that is a source of caller ID and messages. Typically, ncid2ncid is running on the receiving server and for this reason the default receiving server is 127.0.0.1:3333. This can be changed by using the tohost and toport variables in file ncid2ncid.conf, or by using the -t|--tohost [host][:port] arguments on the command line.

A receiving server is required.

The ncid2ncid process connects to sending servers as if it is a client. You specify sending servers using the fromhostX and fromportX variables in file ncid2ncid.conf, where X is a digit 1-4. You can also configure the sending servers from the command line by using multiple -f|--fromhost [host][:port] arguments.

Note the subtle difference: Only specify a digit 1-4 for variables in file ncid2ncid.conf; do not use them on the command line. The following examples are equivalent:

ncid2ncid.conf:

    set fromhost1 = 192.168.20.1  
    set fromport1 = 3334  
    set fromhost2 = 192.168.20.9:3335  

command line:

    ncid2ncid --fromhost 192.168.20.1:3334 --fromhost 192.168.20.9:3335

There are no default sending servers and at least one must be specified.

TESTING:

Start ncid2ncid in debug mode at verbose level 3:

    sudo ncid2ncid -Dv3

Debug mode will give a reason if ncid2ncid dies and will show it processing data.

If ncid2ncid does not work, you should have enough information to ask for help.

START/STOP/RESTART/STATUS/AUTOSTART:

Normally ncid2ncid is started using the provided init, service, rc, or plist script for your OS. For more information, refer to the INSTALL section for your OS. If no script is provided you need to start ncid2ncid manually:

    sudo ncid2ncid

If any options are needed, add them to ncid2ncid.conf.


obi2ncid setup

How to setup an Obihai device to send Caller ID and messages via the obi2ncid gateway.

Sections:

REQUIREMENTS
DEVICE CONFIGURATION
NCID CONFIGURATION
TESTING
OUTPUT TESTING
START/STOP/RESTART/STATUS/AUTOSTART

REQUIREMENTS:

An Obihai device is required. Only the OBi100, OBi110, OBi200 with and without OBILINE, and OBi202 were available for development and testing. Other OBIHAI products may or may not work.

It is possible to configure multiple OBi devices to work with NCID. Each device must have a unique port configured, and the DEVICE CONFIGURATION and NCID CONFIGURATION must use the same port. Ports 4335 through 4339 are normally used. Port 4339 is used by the test-obi-gw test script in the NCID source package.

You must install your OBi device on your local network, create a free OBiTALK account, and link your OBi to your account so that it appears on your OBiTALK Dashboard. Then you need to set up your voice service provider(s) (there are "wizards" that make it easy to set up the most common ones).

Make sure you can successfully make and receive calls before continuing.

DEVICE CONFIGURATION:

The OBi device needs to be configured for NCID use. You can do this using either the "Advanced Configuration" (a.k.a. "Expert") mode accessible through the OBiTALK dashboard, or by using a browser to login directly to the OBi device using its IP address. The OBiTALK Dashboard is the simplest and easiest method and is what will be used below.

On the OBiTALK dashboard, find your OBi device and click on the dark gray gear icon with the red "E" (for "Expert" or Advanced Configuration).

Navigate to System Management->Device Admin.

Navigate to Voice Service.

NCID CONFIGURATION:

The ncidd server defaults to using a modem to get Caller ID. If you have a standard telephone line (POTS) modem configured, you can keep the modem and also use the obi2ncid gateway.

If you do not use a modem and you are not using another gateway, you need to configure ncidd by uncommenting this line in ncidd.conf:

     # set noserial = 1

This tells ncidd to run without a serial device or modem connected.

Once you change ncidd.conf, you must start/restart ncidd to read it.

(Note: Do not confuse the noserial and nomodem settings. See Note 1 for an explanation of the differences.)

Normally obi2ncid does not need to be configured unless you set up the OBi device to use a syslog port other than 4335.

TESTING:

If this is the first time you set obi2ncid up, you should test obi2ncid without connecting it to ncidd. For example, if using a obi200:

     obi2ncid -t -L obi200.log

The above command puts obi2ncid in test mode at verbose level 3. It will display verbose statements on the terminal, ending with "Listening at port 4335". Test mode prevents obi2ncid from connecting with ncidd.

If obi2ncid terminates you should be able to see why and fix it.

If you have a problem that requires debugging you should use verbose level 5 and create a data file. For example, if using a obi200:

     obi2ncid -t -v5 -L obi200.log -R obi200.data

You can get a detailed usage message by executing:

     obi2ncid --help

or print out the manual page by executing:

     obi2ncid --man

If it looks OK, terminate obi2ncid with <CTRL><C>.

Next, restart obi2ncid in debug mode so it will connect to ncidd:

     obi2ncid -Dv3

Make a call and you should see the CALL and CALLINFO lines that are sent to the server. You should also see CID and END lines sent back from the server. If there is a problem an error message may be generated.

OUTPUT TESTING:

This is an advanced set of tests used when adding a new voice provider or device to the obi2ncid. It is also after fixing a problem with a voice provider, to make sure the fix did not break anything.

Suggested setup for easiest testing:

       perl obi2ncid.pl -t -L test.log -C obi2ncid.conf -o 4335
       perl obi2ncid.pl -t -L test.log -R test.data -C obi2ncid.conf -o 4335 -v5

Complete testing of the OBi110 and OBi200 requires checking that the name, number, and line id are the same for the CALL and CALLINFO lines. In addition CALLINFO should show CANCEL if there was no pickup or BYE if there was a pickup.

To verify all is working correctly you need to test the following:

       Incoming call:

originating caller hangup before answer originating caller hangup after answer receiving caller hangup after answer

       Outgoing call:

originating caller hangup before answer originating caller hangup after answer receiving caller hangup after answer

Additional tests for POTS calls. On the OBi110, connect the house Telco line to the OBi110 Telco Line connector. The OBi200 requires the OBiLINE FXO to USB Phone Line Adapter; connect the house Telco line to the OBiLINE.

       Incoming Telco Line

hangup with no answer hangup after house phone answers hangup after answer on the OBi device

       Outgoing Telco Line

hangup with no answer hangup after house phone answers hangup after answer on the OBi device

START/STOP/RESTART/STATUS/AUTOSTART:

Normally obi2ncid is started using the provided init, service, rc, or plist script for your OS. For more information, refer to the INSTALL section for your OS. If none is provided you need to start obi2ncid manually:

    sudo obi2ncid &

You can also set it up to start at boot, along with ncidd. If any options are needed, add them to obi2ncid.conf.

If obi2ncid does not work, you should have enough information to ask for help.


rn2ncid setup

How to setup Remote Notifier on an Android smart phone to send Caller ID and messages via the rn2ncid gateway.

Sections:

REQUIREMENTS
CONFIGURATION
TESTING
START/STOP/RESTART/STATUS/AUTOSTART

REQUIREMENTS:

The smart phone needs to be running Remote Notifier for Android from Google Play.

Install it and configure it for the IP address of the computer running ncidd.

CONFIGURATION:

The ncidd server defaults to using a modem to get Caller ID. If you have a standard telephone line (POTS) modem configured, you can keep the modem and use the rn2ncid gateway.

If you do not use a modem and you are not using another gateway, you need to configure ncidd by uncommenting this line in ncidd.conf:

     # set noserial = 1

This tells ncidd to run without a serial device or modem connected.

Once you change ncidd.conf, you must start/restart ncidd to read it.

(Note: Do not confuse the noserial and nomodem settings. See Note 1 for an explanation of the differences.)

Normally rn2ncid does not need to be configured unless you are using ncid-page to send calls and messages to your smart phone. In that case you need to edit the reject line at the end of rn2ncid.conf and specify the "from" of SMS/MMS messages to be rejected and not passed through to the NCID server. (If you do not do this, the result will be an endless loop which could result in excessively high data or text charges by your cell phone carrier.) The setting for reject is usually of the form root@[hostname] where [hostname] is the result of executing the Unix hostname command on the computer running ncidd.

For example:

* * hostnamesmurfzoo.private * *

Edit rn2ncid.conf:

     reject = root@smurfzoo.private

TESTING:

If this is the first time you set rn2ncid up, you should test rn2ncid without connecting it to ncidd.

     rn2ncid --test

The above command puts rn2ncid in test and debug modes at verbose level 3. It will display verbose statements on the terminal, ending with "Listening at port 10600". It should show configured options. Test mode prevents rn2ncid from connecting with ncidd.

If rn2ncid terminates you should be able to see why and fix it.

You can get a detailed usage message by executing:

     rn2ncid --help

or print out the manual page by executing:

     rn2ncid --man

On your smart phone, launch Remote Notifier and choose "Send test notification". rn2ncid should show something like this:

     NOT: PHONE 0123: PING Test notification

(Note: 0123 is the phone ID and will be different for your phone.)

If it looks OK, terminate rn2ncid with <CTRL><C>.

Next, restart rn2ncid in debug mode so it will connect to ncidd:

     rn2ncid -Dv3

Do the "Send test notification" again and it should be sent to the server and its clients. If you do not get a "NOT" (short for "NOTIFY") message sent to the server, you should instead get an error message saying what is wrong.

If you had the PING "Test notification" sent to a client, setup is complete.

START/STOP/RESTART/STATUS/AUTOSTART:

Normally rn2ncid is started using the provided init, service, rc, or plist script for your OS. For more information, refer to the INSTALL section for your OS. If none is provided you need to start rn2ncid manually:

     sudo rn2ncid &

You can also set it up to start at boot, along with ncidd. If any options are needed, add them to rn2ncid.conf.

If rn2ncid does not work, you should have enough information to ask for help.


sip2ncid setup

How to setup VoIP Caller ID using sip2ncid.

Sections:

REQUIREMENTS
CONFIGURATION
TESTING
START/STOP/RESTART/STATUS/AUTOSTART

REQUIREMENTS:

VoIP telephone service using SIP.

Configure your LAN for SIP.
See ATA (Analog Terminal Adapter).

CONFIGURATION:

The ncidd server defaults to a using a modem to get Caller ID. if you have a standard telephone line (POTS) modem configured, and you have at least one VoIP telephone line, all you need to do is start sip2ncid to get Caller ID from VoIP. The server will handle a modem and the sip2ncid gateway easily.

If you are only using VoIP and do not want to use a modem, you need to configure ncidd by uncommenting this line in ncidd.conf:

     # set noserial = 1

This tells ncidd to run without a serial device or modem connected.

Once you change ncidd.conf, you must start/restart ncidd to read it.

(Note: Do not confuse the noserial and nomodem settings. See Note 1 for an explanation of the differences.)

Use the sip2ncid --listdevs or -l option to see your network devices:

     sudo sip2ncid --listdevs

If you are using a DirecTiVo and the command does not return anything, you need to load the af_packet kernel module as described here:

     insmod /lib/modules/af_packet.o  

TESTING:

To determine if you can receive any network packets, use the --testall or -T option:

     sudo sip2ncid --testall

This will display a packet count and a packet type. It does not know all packet types so you may get some UNKNOWN packet types. It also sets debug mode and verbose level 3. You can increase the verbose level to see more detail, but if you decrease it below 3, you will not see any packets.

To determine if you can receive SIP data packets, use the --testudp or -t option:

     sudo sip2ncid --testudp

This will display SIP packets and what, if anything, it does. It also sets debug mode and verbose level 3. You can also change the verbose level. If you set verbose to 1, sip2ncid will display lines sent to the server instead of the packet contents:

     sudo sip2ncid -tv1

If no packets are received in about 45 seconds:

     No SIP packets at port XXXX in XX seconds

If sip2ncid terminates you should be able to see why and fix it.

You can get a detailed usage message by executing:

     sip2ncid --help

Sometimes it picks the wrong default interface. If you are using eth0:

     sudo sip2ncid -ti eth0

If you need to see what interfaces are present you can use the --interface or -i option:

     sudo sip2ncid --listdevs

The display is:

     <interface> : <description>

The interface name is everything up to the first space.

If you do not see any SIP packets, change to port 5061 and try again:

     sudo sip2ncid --testudp --sip :5061

You should see something like:

     Network Interface: eth0  
     Filter: port 10000 and udp

Then about every 20 seconds you should see something like:

     Packet number 1:
     Protocol: UDP  
     SIP/2.0 200 OK  
     Via: SIP/2.0/UDP 70.119.157.214:10000;branch=z9hG4bK-22b185d1  
     From: 321-555-7722 <sip:13215551212@atlas2.atlas.vonage.net:10000>;tag=46f26356c0a3394bo0  
     To: 321-555-7722 <sip:13215551212@atlas2.atlas.vonage.net:10000>  
     Call-ID: fa72d1c2-ead1bdcf@70.119.157.214  
     CSeq: 86785 REGISTER  
     Contact: 321-555-1212 <sip:13215551212@70.119.157.214:10000>;expires=20  
     Content-Length: 0

     Registered Line Number: 13215551212

The Registered Line Number line will only appear in packet number 1.

If you do not get the above, you may need to specify an address and/or port for sip2ncid to listen for the SIP Invite. You cannot continue unless you get the above.

If you are using the Linksys RT31P2 Router, you will not see any packets unless the computer is in its DMZ (Demilitarized Zone). Port forwarding the UDP port will not work. You must set up the DMZ. If you are using a different VoIP router, try to put the computer in the DMZ and see if that works. If not, view the SIP tutorial:

Configure your home network for SIP-based Caller ID.

Once you receive the above packets, call yourself. If you do not get a Caller ID message sent to ncidd, you should get an error message saying what is wrong. This has been tested with Vonage and may need tweaking for other VoIP service providers.

If you had Caller ID sent to a client, setup is complete. You can then restart sip2ncid without the test option so it will not display anything. You can also set it up to start at boot, along with ncidd. If any options are needed at boot, add them to sip2ncid.conf.

START/STOP/RESTART/STATUS/AUTOSTART:

Normally sip2ncid is started using the provided init, service, rc, or plist script for your OS. For more information, refer to the INSTALL section for your OS. If none is provided you need to start sip2ncid manually:

     sudo sip2ncid &

You can also set it up to start at boot, along with ncidd. If any options are needed, add them to sip2ncid.conf.

If sip2ncid does not work, you should have enough information to ask for help.


wc2ncid setup

How to setup one or more Whozz Calling Ethernet Link (WC) devices for Caller ID using wc2ncid.

Sections:

REQUIREMENTS
CONFIGURATION
TESTING
START/STOP/RESTART/STATUS/AUTOSTART

REQUIREMENTS:

A Whozz Calling Ethernet Link (WC) device (see: http://callerid.com) connects to POTS (Plain Old Telephone System) lines and can handle 2, 4, or 8 lines. Some models only handle incoming calls while others handle incoming and outgoing calls.

The Whozz Calling user manual tells how to hook up the device. You plug your POTS telephone lines into the device and you connect the device to your local network.

CONFIGURATION:

All WC devices must have an IP address within your network in order for them to be configured for use by wc2ncid. This limitation will be removed in a future release. When you try to configure a device with an address outside your network, wc2ncid will either give a warning or an error message and terminate. You can then use the wct script to change the IP address to one that is in your network. Use the discover option of wct to locate the device:

     wct --discover

The ncidd server defaults to using a modem to get Caller ID. If you have a standard telephone line (POTS) modem configured, you can keep the modem and use the WC device to handle additional POTS or VoIP lines, or you can replace the modem with the WC device.

It is recommended that you not use a modem so you need to configure ncidd by uncommenting this line in ncidd.conf:

     # set noserial = 1

This tells ncidd to run without a serial device or modem connected.

Once you change ncidd.conf, you must start/restart ncidd to read it.

(Note: Do not confuse the noserial and nomodem settings. See Note 1 for an explanation of the differences.)

Next, edit wc2ncid.conf to configure one or more devices. Look for this line:

     wcaddr = 192.168.0.90

If your network is on 192.168.0 and the above address is not used, you can leave it. If your network is on 192.168.1 you can set the IP address for WC device number 1 (WC-1), for example, by changing the line to be:

     wcaddr = 192.168.1.90

If you have 2 devices and want to use addresses 192.168.2.90 and 192.168.2.91, WC device 1 is 192.168.2.90 and WC device 2 is 192.168.2.91.

     wcaddr = 192.168.2.90, 192.168.2.91

TESTING:

Once you set the IP address for the WC device in wc2ncid.conf, start wc2ncid and tell it to configure the WC device:

     wc2ncid [--test] --set-wc

The --test parameter is optional, but it is a good idea to use it so wc2ncid does not connect to the NCID server during the configuration process.

If you have 2 or more WC devices, and they are both set to the same address or the factory default of 192.168.0.90, you need to change both addresses in wc2ncid.conf. For example:

     wcaddr = 192.168.0.91, 192.168.0.92

Turn on one device and execute:

     wc2ncid [--test] --set-wc

Terminate wc2ncid with <CTRL><C>. Leave the first device turned on, then turn on the second device and execute:

     wc2ncid [--test] --set-wc

Both devices should be configured and operational. Terminate wc2ncid with <CTRL><C>.

If this is the first time you set wc2ncid up, you should test wc2ncid without connecting it to the ncidd server:

     wc2ncid --test

The above command puts wc2ncid in test and debug modes at verbose level 3. It will display verbose statements on the terminal, ending with "Waiting for calls". It should show the configured address for each device. Test mode prevents wc2ncid from connecting with ncidd.

If wc2ncid terminates you should be able to see why and fix it.

You can get a detailed usage message by executing:

     wc2ncid --help

or print out the manual page by executing:

     wc2ncid --man

Call yourself. You should see more verbose messages as the call is processed. If it looks OK, terminate wc2ncid with <CTRL><C>.

Next, restart wc2ncid in debug mode so it will connect to ncidd:

     wc2ncid -Dv3

Call yourself. If you do not get a Caller ID message sent to ncidd, you should get an error message saying what is wrong.

If you had Caller ID sent to a client, setup is complete.

START/STOP/RESTART/STATUS/AUTOSTART:

Normally wc2ncid is started using the provided init, service, rc, or plist script for your OS. For more information, refer to the INSTALL section for your OS. If none is provided you need to start wc2ncid manually:

     sudo wc2ncid &

You can also set it up to start at boot, along with ncidd. If any options are needed, add them to wc2ncid.conf.

If wc2ncid does not work, you should have enough information to ask for help.


yac2ncid setup

How to setup a YAC modem server for Caller ID using yac2ncid.

Sections:

REQUIREMENTS
CONFIGURATION
TESTING
START/STOP/RESTART/STATUS/AUTOSTART

REQUIREMENTS:

A YAC server on a Windows computer running Microsoft Windows 98 or later.

The YAC server has not been updated since approximately 2002. You can try to download it from the original YAC homepage, from a saved site copy at the Internet Archive's Wayback Machine, or from any of several global download sites such as http://yac.software.informer.com/. Follow the installation instructions.

CONFIGURATION:

Configure the YAC server by giving it the IP address where ncidd is running. Do this by right-clicking the YAC icon in the System Tray, and then select "Listeners...".

To configure NCID, uncomment this line in ncidd.conf:

     # set noserial = 1

This tells ncidd to run without a serial device or modem connected.

Once you change ncidd.conf, you must start/restart ncidd to read it.

(Note: Do not confuse the noserial and nomodem settings. See Note 1 for an explanation of the differences.)

Normally yac2ncid does not need to be configured, but you should review yac2ncid.conf to see if you want to change any of its defaults.

After modifying ncidd.conf and yac2ncid.conf, you must start/restart ncidd first and then the yac2ncid gateway.

TESTING:

Make sure the YAC server is running on the Windows computer.

Run the yac2ncid gateway with the verbose option:

     yac2ncid -v

Call yourself. If you do not get a Caller ID message sent to ncidd, you should get an error message saying what is wrong.

If you had Caller ID sent to a client, setup is complete. You can then restart yac2ncid without the verbose option so it will not display anything. You can also set it up to start at boot, along with ncidd.

START/STOP/RESTART/STATUS/AUTOSTART:

Normally yac2ncid is started using the provided init, service, rc, or plist script for your OS. For more information, refer to the INSTALL section for your OS. If none is provided you need to start yac2ncid manually:

     sudo yac2ncid &

You can also set it up to start at boot, along with ncidd. If any options are needed, add them to yac2ncid.conf.

If yac2ncid does not work, you should have enough information to ask for help.


Note 1:

In ncidd.conf there is an important difference between the settings noserial and nomodem:

Supported Clients

Table of Contents

Clients Index

Overview
ncid
NCIDpop
NCID Android
LCDncid
NCIDdisplay

Overview

The primary NCID distribution includes one "universal" Graphical User Interface (GUI) client that runs under the Unix scripting language called Wish (Windowing Shell). In addition, there are four optional clients, available as separate downloads, all of which are actively maintained by the NCID Development Team.

There is a 3rd Party Addons page that links to clients, gateways, and related NCID projects by other developers and users. Contact us with a URL showing your project and we will provide a link to it.

The five clients are ncid, NCIDpop, NCID Android, LCDncid, and NCIDdisplay.

ncid

NCID

The ncid client is cross-platform for Linux, Mac OSX, and Windows. It is included with the NCID distribution. The Windows version can only run the client without output modules.

Description, Features and Screenshots

Basic steps for starting the client:

NCIDpop

NCID

NCIDpop is an optional cross-platform popup client for Linux, Mac OSX, and Windows.

Description, Features, and Screenshots

Basic steps for starting the client:

NCID Android

NCID

NCID Android is an optional client for Android running on smartphones and tablets.

Description, Features, and Screenshots

Basic steps for starting the client:

LCDncid

NCID

LCDncid is an optional client that requires an LCD module connected to a Raspberry Pi or other computer.

Description, Features, and Screenshots

Basic steps for starting the client:

ncidhost = 192.168.1.5

NCIDdisplay

NCID

NCIDdisplay is an optional giant (3"x18"!) homebrew LED display made up of at least 4 LCD modules.

Description, Features, and Screenshots

Basic steps for starting the client:

Client Output Modules

Table of Contents

Description

Usage

Description

The ncid client supports output modules.

An output module receives the Caller ID information from the ncid client and gives the client new functionality. For example, one module sends the Caller ID or message to a smart phone as an SMS message or sends it as an email message. Another module speaks the Caller ID or message.

There are various output modules included with NCID. See the ncid-modules man page for a current list of the distributed modules. Each module is described in the man pages.

There are also third party client modules. Some third party modules can be found at NCID Addons.

Usage

Modules are called by the client using a command line of this form:

       ncid --no-gui --program ncid-<name>

Most modules have a configuration file normally at /etc/ncid/conf.d:

       /etc/ncid/conf.d/ncid-<name>.conf

As an example, if the <name> is page and you want to run the command in the background, then the command line would be:

       ncid --no-gui --program ncid-page &

All distributed modules have a boot script that contains the proper command line to start and stop the module as well as giving its status. The boot scripts differ by operating systems. See the INSTALL document for more information on this for your operating system.

The boot script name is always the same name as the module name. Use the AUTOSTART link for your operating system on how to start the module at boot. Use the START/STOP/RESTART/RELOAD/STATUS link for how to start and stop the module. Normally you would enable the module to start at boot after you configure it.

Fedora: AUTOSTART START/STOP/RESTART/RELOAD/STATUS

FreeBSD: AUTOSTART START/STOP/RESTART/RELOAD/STATUS

Raspbian: AUTOSTART START/STOP/RESTART/RELOAD/STATUS

Ubuntu: AUTOSTART START/STOP/RESTART/RELOAD/STATUS

Using NCID

Table of Contents

Description

Description

NCID's main job is to display the Caller ID on multiple devices, but it has advanced features.

NCID can send and receive one line messages. It can also forward a message through a gateway. Review the Messages section for more information.

NCID can give the caller a new name, called an alias. It can do the same with the caller's number or the line of the received call. Review the Alias section for more information.

NCID can automatically hang up on the caller if the number or name is entered into its blacklist. Review the Hangup section for more information.

NCID can execute a hangup extension as another way to determine if it should hangup on a call. Review the Server Extensions section for more information.

NCID provides two command line tools for viewing the alias file and the call log. Two tools are also provided to modify the alias file, the blacklist file, the whitelist file, and the call log. Review the Command Line Tools section for more information.

NCID provides a call log, /var/log/cidcall.log, for calls and messages. It is processed each month if the operating system uses logrotate for the system log files. Review the Log Files section for more information.

Messages
Aliases
Hangup
Server Extensions
Command Line Tools
Log Files

NCID Messages

Table of Contents

Description

Description

NCID supports three different types of messages. All messages must be a single line. All messages must begin with either a MSG:, NOT:, or RLY: label.

MSG:

The server accepts a single line text message from a client and broadcasts it to all connected clients. All messages must begin with the MSG: label.

Gateways can send MSG: lines, too. For example, ncid2ncid will send MSG: lines to indicate the connection status as it passes caller ID data between two or more NCID servers.

Programs external to NCID, such as netcat (a.k.a. nc and ncat), can be used to send a message. Telnet is not recommended. If netcat is used, please note there are different versions with different options.

This shell script example creates a 10 minute food timer. The -w1 is a one second idle timeout to wait before disconnect:

sleep 600; echo "MSG: Food Ready" | nc -w1 localhost 3333 > /dev/null

An equivalent batch file using netcat for Windows would be:

CHOICE /T 600 /C AB /N /D A > NUL echo MSG: Food Ready | nc -w1 192.168.1.100 3333 > NUL

Note: The recommended netcat version for Windows is the security-safe version by Jon Craton. It is available for download from his website here. When extracting, use the password "nc" (without quotes).

You can send a HELLO: CMD: no_log line prior to a MSG: line. This can improve performance because it forces the server not to send the call log before processing the MSG:.

Unix:

sleep 600; echo -e "HELLO: IDENT: client food timer 1.1\nHELLO: CMD: no_log\nMSG: Food Ready" | nc -w1 localhost 3333 > /dev/null

Windows batch file:

CHOICE /T 600 /C AB /N /D A > NUL (echo HELLO: IDENT: client food timer 1.1&echo HELLO: CMD: no_log&echo MSG: Food Ready) | nc -w1 192.168.1.100 3333 > NUL

NOT:

Utilizing the same format as MSG:, when a smartphone gateway (e.g., NCID Android) sends a copy of an SMS text message received or sent by a smartphone, it uses the NOT: line label.

RLY:

When a client (e.g., NCIDpop) sends a message to be forwarded over the cellular network, it uses the RLY: label to send it to a smartphone gateway (e.g., NCID Android). It uses a very different format compared to MSG: and NOT:.

Aliases

Table of Contents

Alias Index

Alias Overview
Alias Types

number alias
name alias
number & name alias
number if name alias
name if number alias
line alias

Alias Expressions

Alias Overview

The name, number, and telephone line of a call are checked for an alias. If a match is found it will be replaced by its alias before the call is added to the call log and before the call information is sent to the clients.

A leading # is allowed in a name or number provided it is enclosed in double quotes. Sometimes a spoofed number starts with one or more # to prevent it from being blacklisted.

Alias names can be a maximum of 50 characters.

You can manually edit the ncidd.alias file to create, edit, or remove entries using an editor.

When the alias file is modified, ncidd needs to be informed. It will reload the alias table when it receives a SIGHUP signal.

One way to send the reload signal to ncidd:

pkill --signal SIGHUP ncidd

You can also just restart ncidd.

Aliases can also be created, edited, or removed by these NCID clients. They provide ways to force the server to reload the alias table.

In addition, when running the NCID server in the US or Canada, the ignore1 option can be set in ncidd.conf to ignore a leading 1 in the Caller ID number or the alias number.

Alias Types

The three general formats for entries in ncidd.alias are:

Where:

When TYPE is NAME and depends is present:

When TYPE is NMBR and depends is present:

When TYPE is missing, the NMBRNAME rule applies:

...and/or...

The three general formats allow for six types of aliases:

Type                    Format
number alias NMBR "received number" = "replacement number"
name alias NAME "received name" = "replacement name"
number & name alias "received data" = "replacement data"
number if name alias NMBR = "*" = "replacement number" if "depends"
name if number alias NAME = "*" = "replacement name" if "depends"
lineid alias LINE = "received call lineid" = "replacement lineid"

Number Alias

The number alias changes the number of the caller to an alias. The number can be a word.

Format: alias NMBR "received number" = "replacement number"

Example: alias NMBR "4075550000" = "4075551212"

Name Alias

The name alias changes the name of the caller to an alias.

Format: alias NAME "received name" = "replacement name"

Example: alias NAME "John Bright" = "Big Bad John"

Number and Name Alias

The number and name alias checks both the caller number and caller name for a match. If either matches, it is replaced by the alias.

This alias type is useful when both the name and number are the same. For example, if the name and number are both "OUT-OF-AREA".

Another use is if you do not care if the string you are looking for is a name or number. You want it replaced if it is either a name or number.

Format: alias "received data" = "replacement data"

Example: alias "OUT-OF-AREA" = "UNAVAILABLE"

Number if Name Alias

The number if name alias changes the number of the caller if the name matches depends. Quotes around the "*" are optional.

Format alias NMBR "*" = "replacement number" if "depends"

Example: alias NMBR * = "secret" if "Bond James"

Name if Number Alias

The name if number alias is the most popular alias. It changes the name of the caller if the number matches depends. Quotes around the "*" are optional.

Format alias NAME "*" = "replacement name" if "depends"

Example: alias NAME * = "john on cell" if "4075556767"

Line Alias

The line alias changes the telephone line tag to an alias.

Format alias LINE "received call lineid" = "replacement lineid"

Example: alias LINE "-" = "POTS"

Alias Expressions

Simple expressions (set regex = 0 in ncidd.conf)

These are permitted in either:

the depends section of an alias line

...or...

the received data section, if the alias line does not contain depends

The allowed expressions are:

^ = partial match from beginning
* = partial match after the *
^1? = optional leading 1 for US/Canada numbers

* = partial match from beginning to before the *

Regular Expressions (set regex = 1 in ncidd.conf)

They are used in place of Simple Expressions. The syntax for Simple Expressions is not compatible with Regular Expressions except for , 1?, and 1?.

The POSIX Extended Regular Expression syntax is used. It is a section in Regular Expression.

If you are new to Regular Expressions, see Regular-Expressions.info for an introduction.

Hangup

Table of Contents

Hangup Index

Hangup Overview
Modem Configuration
Hangup Choices

Normal Hangup
Fax Hangup
Announce Hangup

Blacklist and Alias Files Usage
Whitelist File Usage
Blacklist and Whitelist Expressions

Hangup Appendix A: Server Log File Sample
Hangup Appendix B: Creating a Voice File from Scratch
Hangup Appendix C: Raw Modem Data Formats
Hangup Appendix D: Modem AT+VSM Command Explained

Hangup Overview

Hangup (a.k.a. call termination) is disabled/enabled by settings in the server configuration file ncidd.conf. It requires a modem to be connected to the phone line so it can pickup and hangup the line.

At a high-level, there are two sets of procedures available to hangup calls. Both are optional, and one or both can be enabled at the same time. They are:

When Caller ID is received from a modem, the following steps take place and in this order:

You can manually edit the blacklist and whitelist files to create, edit, or remove entries using an editor.

When either file is modified, ncidd needs to be informed. It will reload the blacklist and whitelist tables when it receives a SIGHUP signal.

One way to send the reload signal to ncidd:

sudo pkill --signal SIGHUP ncidd

You can also just restart ncidd.

Blacklist and whitelist entries can also be created or removed by the following NCID clients. They provide ways to force the server to reload the tables:

In addition, when running the NCID server in the US or Canada, the ignore1 option can be set in ncidd.conf to ignore a leading 1 in the Caller ID, alias, blacklist, or whitelist.

Modem Configuration

A modem is required to hangup the line. Hangup is enabled and configured in ncidd.conf by the hangup variable.

Hangup is disabled by default, with and without a configuration file. Hangup can also be disabled by the line:

set hangup = 0

You may also need to set the ttyport variable if the correct one is not set in ncidd.conf. For example, using Linux:

set ttyport = /dev/ttyACM0

The location of ncidd.conf will vary depending on the operating system. It is typically found in either /etc/ncid/ or /usr/local/etc/ncid/. The ncidd.conf file location is also shown in /var/log/ncidd.log when ncidd starts. If ncidd.conf is missing, ncidd.log will have an appropriate message.

Announce Hangup has some additional requirements for modem configuration.

Hangup Choices

If enabled, there are three types of hangups:

If the type of hangup is not supported by the modem, ncidd will change the hangup to Normal Hangup.

Normal Hangup

A normal hangup is configured in ncidd.conf by the line:

set hangup = 1

When ncidd receives a blacklisted Caller ID, it will immediately hangup.

FAX Hangup

A FAX hangup will generate a FAX tone for 10 seconds and then hangup. It is configured in ncidd.conf by the line:

set hangup = 2

Not all FAX modems are supported. If no FAX tones are generated, set pickup to 0 in ncidd.conf. It is usually needed for older modems.

set pickup = 0

After changing the pickup value, if it still does not work then the modem is not supported for FAX Hangup by ncidd.

Announce Hangup

Announce Hangup will play a recorded message and then hangup.

Configuration
Voice Files

CX93001 Chipset Voice Files
US Robotics USR5637 Voice Files
Creating a Voice File from Scratch

Configuration
Modem

Make sure the modem supports hardware flow control and that it is enabled. Look for the line Modem ACTIVE PROFILE: in ncidd.log. For most modems, hardware flow control is indicated by the presence of &K3 in the profile. You may need to set &K3 in the active profile. If &K (or whatever is appropriate for your modem) is not returned, then the modem is not supported by NCID.

ncidd.conf

Announce Hangup is configured by the line:

set hangup = 3

In addition, two other variables, announce and audiofmt, are used to configure the announcement file. For example:

set announce = NumberDisconnected.rmd
set audiofmt = "AT+VSM=130"

If the announcement file is missing, ncidd will change Announce Hangup to Normal Hangup. This will be indicated in ncidd.log.

The default voice file is for 8-bit unsigned PCM at an 8000 Hz sample rate. It also seems to work for 8-bit LINEAR at an 8000 Hz sample rate.

The audiofmt variable determines the voice file's compression method and sampling rate. The shorthand for this is Voice Sampling Method or VSM.

Voice Files
CX93001 Chipset Voice Files

The default voice file supplied, NumberDisconnected.rmd, works for modems that use the CX93001 chipset. See the Incomplete list of working modems for known modems that use this chipset.

Variable audiofmt defaults to AT+VSM=130 to work with this chipset.

US Robotics USR5637 Voice Files

The default voice file will also work with the US Robotics USR5637 modem, but it must have firmware 1.2.23 or newer, and audiofmt must be changed.

To check the firmware level, examine ncidd.log for this line:

Modem Identifier: U.S. Robotics 56K FAX USB V1.2.23

If you need to upgrade the firmware, download it from the US Robotics USR5637 support page.

The VSM line used is

128,"8-BIT LINEAR",(7200,8000,11025)

It has () around the supported voice sampling rates with three choices. You need to select 8000 for use with the default NumberDisconnected.rmd file. Make the following change in ncidd.conf:

set audiofmt = "AT+VSM=128,8000"

Creating a Voice File from Scratch

This is a rather lengthy procedure so we have dedicated Hangup Appendix B: Creating a Voice File from Scratch to this topic.

Blacklist and Alias Files Usage

File ncidd.blacklist is a list of names and/or numbers that will be terminated using one of the Hangup Choices above. By making use of expressions and wildcards, you can achieve more complex matching logic with even fewer entries in the blacklist. See the the ncidd.blacklist.5 man page for more info.

Comments are supported and must begin with a #. Comments can be an entire line, or a comment can be at the end of an entry line.

A leading # is allowed in a name or number provided it is enclosed in double quotes. Sometimes a spoofed number starts with one or more # to prevent it from being blacklisted.

Beginning with NCID version 1.3, a match name is a special kind of comment that replaces the caller name or alias when it matches an entry in either the blacklist or whitelist. It can only be at the end of an entry line and must begin with #=.

All phone numbers below are intended to be fictitious.

ncidd.blacklist Optional Comment
2125550163 # Free home security system
2265196565  
2145559648 # Win a free cruise
3402090504  
8772954057 # Acme Market Research
9792201894 # Political survey
"#########8" # The quotes are required

When a call comes in, NCID will apply any alias transformations before checking the blacklist file. You can use this to your advantage to simplify the number of entries needed in ncidd.blacklist. Another advantage this gives you is that NCID clients (e.g., NCIDpop) will show the caller name as TELEMARKETER to indicate the reason for the hangup.

ncidd.alias Matching phone#
alias NAME * = "TELEMARKETER" if 2125550163
alias NAME * = "TELEMARKETER" if 2265196565
alias NAME * = "TELEMARKETER" if 2145559648
alias NAME * = "TELEMARKETER" if 3402090504
alias NAME * = "TELEMARKETER" if 8772954057
alias NAME * = "TELEMARKETER" if 9792201894

ncidd.blacklist  
"TELEMARKETER"  

Beginning with NCID version 1.3, Method 2 can be simplified further by using the blacklist line comment field to be a match name. This behaves like an alias but you don't need to make entries in ncidd.alias. The trick is to use the two characters #= as a special comment line. Spaces are optional between #= and the match name.

The blacklist match name overrides the incoming caller ID name and any ncidd.alias match that might exist.

ncidd.blacklist Match Name in Comment
2125550163 #= Free home security system
2265196565 #= TELEMARKETER
2145559648 #= Win a free cruise
3402090504 #= TELEMARKETER
8772954057 #= Acme Market Research
9792201894 #= Political survey
"#########8" #= Tried to avoid the blacklist

Whitelist File Usage

File ncidd.whitelist is a list of names and/or numbers that will prevent a blacklist entry from causing a hangup. By making use of expressions and wildcards, you can achieve more complex matching logic with even fewer entries in the whitelist. See the ncidd.whitelist.5 man page for more info.

Comments are supported and must begin with a #. Comments can be an entire line, or a comment can be at the end of an entry line.

A leading # is allowed in a name or number provided it is enclosed in double quotes, just like in the blacklist.

The whitelist match name is entered the same way as a blacklist match name, using #=.

The whitelist match name overrides the incoming Caller ID name and any ncidd.alias match that might exist.

This example shows how to blacklist an entire area code while allowing specific numbers. It also shows how to indicate when there is a match in the whitelist.

ncidd.blacklist Match Name in Comment
"999" #= Blacklist area code 999
"998" #= Blacklist area code 998

ncidd.whitelist Match Name in Comment     
9995556732 #= WHT 999-555-6732
9985550000 #= WHT James Bond

Blacklist and Whitelist Expressions

The Blacklist and Whitelist can have either Simple Expressions or Regular Expressions (but not both) for an entry.

In addition, when running the NCID server in the US or Canada, the ignore1 option can be set in ncidd.conf to ignore a leading 1 in the Caller ID, alias, blacklist, or whitelist.

Simple Expressions (set regex = 0 in ncidd.conf):

^ = partial match from beginning
1? = optional leading 1 (for US/Canada numbers)

Regular Expressions (set regex = 1 in ncidd.conf):

Regular Expressions are used in place of Simple Expressions. The syntax for Simple Expressions is not compatible with Regular Expressions except for , 1?, and 1?.

Hangup Appendix A: Server Log File Sample

The ncidd.log is useful for indicating ncidd configuration settings, modem features, modem settings, and debugging information.

This is a portion of the output for a tty port and an LB LINK USB Modem. The output is at the default verbose 1 level. It is useful for reviewing the tty port parameters, the modem identifier, country code, Voice Sampling Methods supported, the VSM selected, and the setting of the hangup option:

TTY port opened: /dev/ttyACM0
TTY port speed: 115200
TTY lock file: /var/lock/lockdev/LCK..ttyACM0
TTY port control signals enabled
CallerID from AT Modem and optional gateways
Handles modem calls without Caller ID
Modem initialized.
Modem Identifier: CX93001-EIS_V0.2013-V92
Modem country code: B5 United States
Modem ACTIVE PROFILE:
B1 E1 L2 M1 N0 Q0 T V1 W0 X4 Y0 &C1 &D2 &G0 &J0 &K3 &Q5 &R1 &S0 &T5 &X0
S00:0 S01:0 S02:43 S03:13 S04:10 S05:8 S06:2 S07:50 S08:1 S09:6
S10:14 S11:85 S12:50 S18:0 S25:5 S26:1 S36:7 S38:20 S46:138 S48:7
S95:0
Modem supports Data Mode
Modem supports FAX Mode 1
Modem supports FAX Mode 2
Modem supports VOICE Mode
Hangup option = 3 - play an announcement then hangup on a blacklisted call
Internal Hangup recording file: /usr/share/ncid/recordings/NumberDisconnected.rmd
Manufacturer: CONEXANT
Modem Voice Sampling Methods:
0,"SIGNED PCM",8,0,8000,0,0
1,"UNSIGNED PCM",8,0,8000,0,0
129,"IMA ADPCM",4,0,8000,0,0
130,"UNSIGNED PCM",8,0,8000,0,0
131,"Mu-Law",8,0,8000,0,0
132,"A-Law",8,0,8000,0,0
133,"14 bit PCM",14,0,8000,0,0
Modem Voice Sampling Method selected: AT+VSM=130

Hangup Appendix B: Creating a Voice File from Scratch

You may wish to check the Network Caller ID page at Wikipedia to see if someone has already documented the steps for your modem.

Prerequisites

This procedure uses Linux to convert the files.

The sox and mgetty-voice packages need to be installed.

An audio file, preferrably one channel (mono), a sample rate of 8000 Hz (8 kHz), and a sample size of 8 bits. This file can be either of the following:

The chipset identifier returned by the modem's ATI3 response.

The Voice Sampling Methods returned by the modem's AT+VSM=? response, and the directory to store the Raw Modem Data (.rmd) file.

  sudo pkill ncidd  
  sudo ncidd -Dv1 -p 3334 -N1 -H3

Examine the Modem's Voice Sampling Methods (VSM)

Your ultimate goal in creating a custom voice file is to take a Portable Voice File (.pvf) and use the pvftormd command line program to convert it to a Raw Modem Data (.rmd) file that is specific to your modem type (chipset).

The tricky part is in trying find a compression method for pvftormd that is comparable to one of the Voice Sampling Methods and codecs returned by the modem's (often cryptic) AT+VSM=? response. Compounding the challenge are the facts that:

In the discussion below, we'll see examples of this challenge as we use one of the .pvf files supplied with NCID to create the .rmd file that works on two different modem chipsets: Conexant CX93001 and USR5637.

Conexant CX93001

The pvftormd tool requires a modem type. The supported modem types and raw modem data formats are listed with the -L option:

pvftormd -L

Refer to Hangup Appendix C: Raw Modem Data Formats. You'll notice that there's nothing listed in Column 1 that has "Conexant" as part of its name.

So what modem type was used to create the .rmd files supplied with NCID and why/how was it chosen? The answer to the first part of the question is "V253modem" and the answer to the second part is "by experimenting" (or perhaps, "luck").

If your modem isn't listed, which is highly likely, you have to start somewhere so try something for an 8 bit PCM format:

Next, you want to look at the modem's VSM info to see if you can find a match on 8 bit, linear, PCM, signed or unsigned.

Here's the VSM info from ncidd.log for a modem with a Conexant CX93001 chipset:

 0,"SIGNED PCM",8,0,8000,0,0

1,"UNSIGNED PCM",8,0,8000,0,0
129,"IMA ADPCM",4,0,8000,0,0
130,"UNSIGNED PCM",8,0,8000,0,0
131,"Mu-Law",8,0,8000,0,0
132,"A-Law",8,0,8000,0,0
133,"14 bit PCM",14,0,8000,0,0

The line for 130 looks promising so we'll try that first. The line for 1 might also work since it "looks" the same as line 130. Probably the only reason 130 was chosen is that users seem to have better luck with values 100 and greater.

In conclusion, we've decided to try these settings for the Conexant CX93001 chipset:

USR5637

For the USR5637 chipset, it just so happens that trying the .rmd for the Conexant CX93001 chipset works just fine, but it does require a different VSM setting. Looking at ncidd.log for this modem we see:

 128,"8-BIT LINEAR",(7200,8000,11025) 

129,"16-BIT LINEAR",(7200,8000,11025) 130,"8-BIT ALAW",(8000) 131,"8-BIT ULAW",(8000) 132,"IMA ADPCM",(7200,8000,11025)

The Conexant CX93001 codec we picked to try was "UNSIGNED PCM" but as you can see, that's not an option for the USR5637. We'll pick line 128, "8-BIT LINEAR" and hope it'll work.

A little more work needs to be done, though. The presence of the () for line 128 means we have to specify one of the three sampling rates, but which one? Recall the line we used for the Conexant CX93001:

 130,"UNSIGNED PCM",8,0,8000,0,0  

The sampling rate is fixed at 8000 so we'll try that for the USR5637.

In conclusion, we've decided to try these settings for the USR5637 chipset:

Creating a Portable Voice File (.pvf)

You would do the steps here if you want to use a .wav file or other audio file format supported by sox.

You can either record an announcement or download a .wav file from the internet. A good place to start is This Is a Recording.

Once you have the .wav file, you need to convert it to a .pvf. We'll use the parameters listed under Prerequisites: one channel (mono), a sample rate of 8000 Hz (8 kHz), and a sample size of 8 bits.

Assuming the file is called custom.wav:

sox custom.wav -t pvf -c 1 -r 8000 -b 8 custom.pvf

You can use the play command to listen to it:

play custom.pvf

Make sure the playback is clear and no spoken words get dropped. If the playback doesn't sound good as a .pvf, it is probably not going to sound good when you convert it to an .rmd for playback through the modem. You may need to use a different source .wav file and/or you'll need to experiment with the sox parameters.

Note: It is probably not going to work very well if you try the the play command on a virtual Linux machine because playing back audio can cause a performance hit on the virtual machine's CPU and other resources. Instead, you will want to play it on a physical machine. As an alternative to the play command, you could play it back using cross-platform versions of Audacity or VideoLAN.

Generally speaking, you only need to create a .pvf file once. It can then be used to create .rmd files for multiple modem chipets.

If you need to examine the properties of a .pvf file, use the soxi tool:

$ soxi CallingDeposit.pvf Input File : 'CallingDeposit.pvf' Channels : 1 Sample Rate : 8000 Precision : 8-bit Duration : 00:00:09.90 = 79203 samples ~ 742.528 CDDA sectors File Size : 79.2k Bit Rate : 64.0k Sample Encoding: 8-bit Signed Integer PCM $

Creating a Raw Modem Data (.rmd) File

Once you have a .pvf file, you must convert it to an .rmd that is specific for your modem's chipset.

Assuming the file is called custom.wav:

pvftormd V253modem 8 custom.pvf custom.rmd

The NumberDisconnected.pvf voice file was used to create NumberDisconnected.rmd. The .pvf files for the distribution are in the documentation directory which is usually:

/usr/share/doc/ncid/recordings

or

/usr/local/share/doc/ncid/recordings

Use NumberDisconnected.pvf to create a raw modem data (.rmd) file for your modem if the default one, NumberDisconnected.rmd, is not usable.

Convert it to .rmd:

pvftormd V253modem 8 NumberDisconnected.pvf NumberDisconnected.rmd  

If you need to examine the properties of an .rmd file, use the rmdfile tool:

$ rmdfile CallingDeposit.rmd CallingDeposit.rmd: RMD1 modem type is: "V253modem" compression method: 0x0008 sample speed: 8000 bits per sample: 8 $

Configuring NCID to use a Custom Voice File

Copy the custom .rmd file to the directory to store the Raw Modem Data (.rmd) file (see Prerequisites).

Edit ncidd.conf to enable Announce Hangup, indicate the name of the custom .rmd file and the AT+VSM command to use.

Example:

set hangup = 3
set announce = custom.rmd
set audiofmt = "AT+VSM=128,8000"

Testing a Custom Voice File

The best way to test a custom voice file is to temporarily add your phone number to the blacklist file and call yourself. Use a handset or headset to listen to the call and not speakerphone or handsfree mode.

If you experience any of the following, you will need to experiment with different parameters when running pvftormd and/or different AT+VSM settings:

Hangup Appendix C: Raw Modem Data Formats

You would probably refer to this appendix only if you're using the Announce Hangup option.

The pvftormd command line program requires a modem type. The supported raw modem data formats are listed with the -L option:

pvftormd -L

Column headings added to chart for readability:

  1. Modem type or manufacturer.
  2. One or more numbers representing different compression methods (these values are unique to pvftormd and have no relation to a modem's compression number in its AT+VSM=? reponse).
  3. Description of the compression method and usually lists the bit levels supported by pvftormd.

Output of pvftormd -L follows:

  pvftormd experimental test release 0.9.32 / with duplex patch
  supported raw modem data formats:
Column 1 Column 2 Column 3
- Digi 4 G.711u PCM
- Digi 5 G.711A PCM
- Elsa 2, 3, 4 2/3/4-bit Rockwell ADPCM
- ISDN4Linux 2, 3, 4 2/3/4-bit ZyXEL ADPCM
- ISDN4Linux 5 G.711A PCM
- ISDN4Linux 6 G.711u PCM
- Lucent 1 8 bit linear PCM
- Lucent 2 16 bit linear PCM
- Lucent 3 G.711A PCM
- Lucent 4 G.711u PCM
- Lucent 5 4 bit IMA ADPCM
- MT_2834 4 4 bit IMA ADPCM
- MT_5634 4 bit IMA ADPCM
- Rockwell 2, 3, 4 2/3/4-bit Rockwell ADPCM
- Rockwell 8 8-bit Rockwell PCM
- UMC 4 G.721 ADPCM
- US_Robotics 1 USR-GSM
- US_Robotics 4 G.721 ADPCM
- V253modem 2, 4 2/4-bit Rockwell ADPCM
- V253modem 5 4-bit IMA ADPCM
- V253modem 6 G.711u PCM
- V253modem 7 G.711A PCM
- V253modem 8 8-bit linear unsigned PCM
- V253modem 9 8-bit linear signed PCM
- V253modem 12 16-bit linear signed PCM Intel Order
- V253modem 13 16-bit linear unsigned PCM Intel Order
- ZyXEL_1496 2, 3, 4 2/3/4-bit ZyXEL ADPCM
- ZyXEL_2864 2, 3, 4 2/3/4-bit ZyXEL ADPCM
- ZyXEL_2864 81 8-bit Rockwell PCM
- ZyXEL_Omni56K 4 4-bit Digispeech ADPCM (?)
  example:
          pvftormd Rockwell 4 infile.pvf outfile.rmd

Hangup Appendix C: Modem AT+VSM Command Explained

Here is a breakdown of what each parameter means in the AT+VSM command:

Command: AT+VSM=? Response: ,,,,,,

Decimal number identifying the compression method (1, 129, 130, 140, or 141).

Alphanumeric string describing the compression method (UNSIGNED PCM, IMA ADPCM, UNSIGNED PCM, 2 Bit ADPCM, or 4 Bit ADPCM).

Decimal number defining the average number of bits in the compressed sample not including silence compression (2, 4 or 8).

Decimal number (0) reporting the time interval, in units of 0.1 second, between timing marks. A value of 0 reports that timing marks are not supported.

containing the supported range of voice samples per second of the analog signal (8000).

containing the supported range of sensitivity settings for voice receives (0). A 0 indicates not supported.

containing the supported range of expansion values for voice transmits (0). A 0 indicates not supported.

Server Extensions

Table of Contents

Description
Hangup Extension

Description

The ncidd server supports Server Extensions. A Server Extension is an external script or program that is called by ncidd to perform a function and return a result. Server Extensions are a way for users to add functionality to NCID without requiring changes to NCID itself. Server Extensions are isolated from the main NCID distribution, and because of this they do not normally require any changes when NCID is upgraded to a later version.

You can use any scripting or programming language desired.

Hangup Extension

The first Server Extension distributed with NCID is the Hangup Extension.

A Hangup Extension can be used with and without using Internal Hangup. (Internal Hangup is defined as call termination using the ncidd.blacklist and ncidd.whitelist files.)

It works like this:

When Caller ID is received from a modem and it is not terminated by the Internal Hangup logic and is not in 'ncidd.whitelist', the server will check to see if a Hangup Extension has been enabled. If so, the server will pass the current call info to the Hangup Extension, execute it, and wait for a response. If the Hangup Extension results in a positive match by returning the word hangup, call termination will take place automatically.

Hangup Extensions use all of the same Internal Hangup modes (normal, fax, announce). Be sure to review the required Modem Configuration parameters.

Three settings in ncidd.conf control Hangup Extensions:

Setting Values
set hupmode
0 = disabled
1 = Normal Hangup
2 = Fax Hangup
3 = Announce Hangup

default: 0
 
set hupname
the name of the hangup script or program

default: hangup-skel
 
set huprmd
optional voice file to be played if hupmode = 3

default: "announce" file used by Internal Hangup (usually NumberDisconnected.rmd)
 

When you enable a Hangup Extension, you also need to indicate the hangup script to use. The default is hangup-skel which will run, but it will never trigger a hangup. When testing your script you can give the full path name to where it is located. When it's working OK, copy it to the path appropriate for your operating system:

/usr/share/ncid/extensions

or

/usr/local/share/ncid/extensions

Once the file is there you give the name of the script in ncidd.conf:

set hupname = hangup-custom

You create your own Hangup Extension script/program external to NCID in whatever language you would like. It can have whatever logic you wish for terminating a call. You can even have it return the name of a customized voice message file for individual phone numbers. It is not necessary for your Hangup Extension to check ncidd.whitelist because the NCID server already does this for you and will have automatically applied any Simple Expressions or Regular Expressions to the incoming call.

The technical details of creating a Hangup Extension are outside the scope of this document (see NCID-API).

However, one ready-to-use Hangup Extension and three template Hangup Extensions are included with NCID. Template Hangup Extensions have a file name ending in '-skel' (short for "skeleton"). These will always be replaced when NCID is updated. Before customizing a template, it is essential that you copy or rename the template script so that it does not end in '-skel'.

Below is a summary of the Hangup Extensions included with NCID:

Log Files

Table of Contents

Requirement

Description

Yearly Logs

Requirement

NCID uses logrotate to prune its log files each month. When it prunes the log, it saves a backup. Up to five backups are saved.

Another system log rotation program can be used but it must be configured to zero (empty) the log each month in order to use the ncid-yearlog program.

Description

Here is an alphabetical list of NCID log files stored in /var/log: > Log file name |Log type|Description --------------|--------|:---------- cidcall.log | server |Calls and messages ciddata.log | server |Raw data received by ncidd server as captured from modems and gateways* lcdncid.log | client |LCDproc client activity ncid2ncid.log | gateway|NCID-to-NCID gateway activity ncidd.log | server |Server activity obi2ncid.log | gateway|OBihai gateway activity rn2ncid.log | gateway|Remote Notifier gateway activity sip2ncid.log | gateway|SIP gateway activity wc2ncid.log | gateway|Whozz Calling gateway activity

*Note: If /var/log/ciddata.log exists, ncidd will write to it. It must be manually created prior to launching ncidd:

       sudo touch /var/log/ciddata.log

Each month logrotate uses /etc/logrotate.d/ncid to prune files as required in /etc/ncid/ncidrotate.conf. Only two variables are expected to change: RotateOff  and Lines2keep.

If the user does not want a log rotated, set RotateOff=1. This will let the log keep growing until the operating system decides it is too large.

The default for Lines2keep is 0. Some users like to keep some lines in the log when it is pruned. If you would like to keep the last 10 lines at the start of the month, set Lines2keep=10

If you turned rotation off or do not prune a log to zero each month, you should backup the log to someplace that is not /var.

Yearly Logs

NCID can keep yearly logs automatically in $HOME/ncid/log/ by running /usr/share/ncid/sys/ncid-yearlog on the first of every month from the user's crontab.

If ncidrotate.conf has RotateOff=0 and Lines2keep=0, you can enable ncid-yearlog by creating or editing a crontab and adding this line (NOTE: /usr/share can be /usr/local/share on some operating systems):

       11 5 1 * * /usr/share/ncid/sys/ncid-yearlog

Command Line Tools

Table of Contents

Tools Index

Overview
cidalias
cidcall
cidupdate
ncidutil
ncid-yearlog

Overview

NCID has a few command line Perl scripts (also called tools) that can list or modify the ncidd.alias, ncidd.blacklist, ncidd.whitelist, and cidcall.log files. These scripts are in all distributions except the TiVo distribution. The TiVo does not support Perl.

If you edit and modify ncidd.alias, ncidd.blacklist, or ncidd.whitelist with an editor:

sudo pkill --signal SIGHUP ncidd

There are four tools: cidalias, cidcall, cidupdate, and ncidutil.

cidalias

The cidalias tool displays aliases in the alias file in one of three different formats: raw, human readable, and delimited.

See the cidalias.1 man page for a complete description and all options.

cidcall

The cidcall tool is used to view the cidcall.log file in one of two different formats: raw and human readable. The default is to display BLK, CID, HUP, OUT, PID, and WID lines in a human readable format. Messages and Smartphone Notes will be viewed when their option is selected.

See the cidcall.1 man page for a complete description and all options.

EXAMPLES:

To view all call types, but not message types: cidcall

To view messages and notes: cidcall --MSG --NOT

cidupdate

The cidupdate tool is used to update the cidcall.log file with newly created aliases. It is also used by the server whenever clients want the call logfile update.

Command Line Usage:

sudo pkill --signal SIGHUP ncidd

See the cidupdate.1 man page for a complete description and all options.

ncidutil

The ncidutil is only used by the server to add, modify, or remove entries from ncid.alias. It is also used by the server to add or remove entries from ncidd.blacklist and ncidd.whitelist.

See the ncidutil.1 man page for a complete description and all options.

ncid-yearlog

The ncid-yearlog tool automatically creates a yearly call log from the monthly call logs. It is called from the user's crontab on the first of the month. Review Yearly Logs and ncid-yearlog.1

NCID FAQ

Table of Contents

FAQ Index

General

Server

Gateways

Client

Client Output Modules

General

This is best explained in this Caller ID article on Wikipedia.

NCID is a Network Caller ID package that distributes Caller ID over a network to a variety of devices and computers.

NCID consists of:

The Universal Client has output modules that can be used to push CID to other computers and devices. Here is a partial list:

The NCID package only comes with one client, but other clients are available such as NCIDPop and LCDncid.

Third party clients are also available:

There should only be one server per phone line.

NCID is designed to have multiple clients. For example: a client on a TiVo, a client on each computer in your network, and a client to handle your cell phone.

The GUI client is the only part of NCID that runs directly under Windows. Output modules are not supported.

If you want to run the complete NCID distribution, you need to install Cygwin. You need to configure the NCID server so it will only use its gateways to obtain the Caller ID. If you want to use a modem, you need to also install a YAC server.

The modem documentation should tell you if the modem supports Caller ID and how to set it up. NCID will try two ways to configure a modem for Caller ID, and the configuration file (ncidd.conf) has other methods you can try.

NCID documentation has a section called Modems that gives some information on configuring a modem for Caller ID, and there is also a section called Modem Caller ID Test that tells how to use ncidd to test the modem.

An NCID gateway obtains the Caller ID information and sends it to the NCID server as a CID message. Currently included gateways are:

Yes. NCID has a YAC output module and a YAC Gateway.

The YAC output module is used with the NCID client to obtain the CID information from the NCID server and send it to YAC listeners.

The YAC gateway receives the CID information from a YAC modem server, formats it and sends it to the NCID server as a CID message. If your windows PC has a modem, you can install YAC and configure it to send the CID to the YAC Gateway.

Yes, NCID supports one modem or serial device, multiple SIP Gateways, multiple YAC Gateways, and multiple Whozz Calling (WC) devices using a WC gateway.

Each SIP Gateway can support multiple VoIP telephone connections.

Each WC device can support either 2, 4, or 8 POTS (Plain Old Telephone Service) lines.

Server

An "alias" allows you to replace a generic Caller ID name with a custom one that is more meaningful. You can configure several hundred aliases if you want. Aliases are stored in the ncidd.alias file.

For example, if an incoming call has the name "WIRELESS CALLER" you can use an alias to change it to the real name of the caller. You would use this form of alias:

    alias NAME "FROM" = "TO" if "TELEPHONE_NUMBER"

Since we do not care what name is there, we will use '*' in the FROM field. The TO field can contain spaces so in our case we want it to say: "John on cell". The most important field is the TELEPHONE_NUMBER; this must match the number ncidd receives, and in most cases, it includes a '1', even though it is not displayed. Putting in the values, our alias looks like this:

    alias NAME * = "John on cell" if 14075551212

The complete documentation for aliases is in the ncidd.alias man page, and as comments in the ncidd.alias file.

The blacklist is a list of names or numbers that NCID will automatically hangup. The blacklisted names and numbers are stored in the ncidd.blacklist file.

The blacklist supports simple expressions (the default) or extended Posix Regular Expressions (an option).

Using Simple Expressions:

The name or number in the blacklist is treated as a substring of the caller name or number. For example, using a 10 digit US number:

            3215551212 - will only match 3215551212
            321555     - will match any number with 321555 in it
            ^321555    - will match any number beginning with 321555

Using Posix Extended Regular Expressions:

            ^3215551212$ - will only match 3215551212
            .*321555.*   - will match any number with 321555 in it
            ^321555      - will match any number beginning with 321555

The ncidd.blacklist file comes preconfigured for PRIVATE names, a spoofing area code, and a few expensive area codes.

The complete documentation for the blacklist is in the ncidd.blacklist man page, and as comments in the ncidd.blacklist file.

The whitelist is a list of names or numbers in the ncidd.whitelist file. If a call matches a name or number in the ncidd.blacklist file, the whitelist file is consulted to see if the call should be allowed.

The whitelist file uses the same expressions as the blacklist file.

As an example, the blacklist file comes preconfigured to blacklist the entire 999 unused area code. If you want to allow a specific number from area code 999, you would add it to ncidd.whitelist:

Using Simple Expressions: 9995551212

Using Posix Extended Regular Expressions: 9995551212 or ^9995551212$

You might notice there are 2 entries in the blacklist file for each of the blacklisted area codes. This is because in the US some systems send a leading 1 and some do not. Not knowing which system a user might have, two entries are made to work with both types. Thus the above example using simple expressions becomes:

    9995551212 19995551212

The complete documentation for the whitelist is in the ncidd.whitelist man page, and as comments in the ncidd.whitelist file.

The server hangup feature is configured in the "Automatic Call Hangup" section of the ncidd.conf file. Just remove the '#' from the line:

    # set hangup = 1

Once you change ncidd.conf, you must start/restart ncidd to read it.

You need to enter the caller name or telephone number in the ncidd.blacklist file, usually one name or number per line.

If there is a match on the name or number when a call comes in, it will immediately be terminated. When a call is terminated, an "HUP" entry is made in the ncidd.log file.

Gateways

You need to configure your network, ncidd, and the sip2ncid gateway for the ports that SIP Invite uses.

You can test for network packets in general, or SIP packets for a particular port, using sip2ncid. You would need to use the -T|--testall or the -t|--testudp option. Once you determine the ports being used, enter them in sip2ncid.conf.

If you have SIP packets on your home network, your network is already configured and ready to use. However, a home network may need to be configured to receive SIP packets. For a router/phone device you may need to put your computer in the Demilitarized Zone (DMZ) to see SIP packets; usually port forwarding will not work. You should also review this tutorial: Configuring your home network for SIP-based callerID

If you are using a POTS (Plain Old Telephone Service) line and SIP, no additional ncidd configuration is necessary. If you are only using SIP you need to set noserial in ncidd.conf. Once you change ncidd.conf, you must start/restart ncidd to read it.

You need to configure ncidd, yac2ncid, and your YAC server.

If you are using a POTS (Plain Old Telephone Service) line and YAC, no additional ncidd configuration is necessary. If you are only using YAC, or SIP and YAC, you need to set noserial in ncidd.conf. Once you change ncidd.conf, you must start/restart ncidd to read it.

If the YAC server is on the same computer as ncidd, no configuration is necessary. If it is on a different computer, the IP address of NCID needs to be inserted into the yac2ncid.conf file.

The NCID YAC Gateway is a YAC Listener, so the YAC server needs the address IP address of the computer running yac2ncid.

You need a Whozz Calling Ethernet Link device. You can get either a basic or a deluxe 2, 4, or 8 port model. You can configure as many as you would like, in any combination of 2, 4, or 8 port units.

You need to configure ncidd, wc2ncid, and the Whozz Calling device.

Because the POTS (Plain Old Telephone Service) lines are connected directly to the Whozz Calling device, you need to set noserial in ncidd.conf. Once you change ncidd.conf, you must start/restart ncidd to read it.

If your local network uses 192.168.0.x you do not need to configure wc2ncid.conf. If you have a different network, say 192.168.1.x, then you need to modify wc2ncid.conf:

   Edit wc2ncid.conf:

   change the line: wcaddr = 192.168.0.90
   to: wcaddr = 192.168.1.90

The wc2ncid gateway script needs to be run at least once before using it with NCID. It also needs to be run whenever you change wcaddr in wc2ncid.conf.

   wc2ncid --set-wc

Make sure the Whozz Calling device is set properly. Start wc2ncid in test mode:

   wc2ncid -t

You need to install the free Remote Notifier for Android app from Google Play.

You need to configure the Remote Notifier app, ncidd, and rn2ncid.

Launch Remote Notifier configure the IP address of the computer running the NCID server.

If you are using a POTS (Plain Old Telephone Service) line and Remote Notifier, no additional ncidd configuration is necessary. If you are only using Remote Notifier, set noserial in ncidd.conf. Once you change ncidd.conf, you must start/restart ncidd to read it.

Normally rn2ncid does not need to be configured unless you are using ncid-page to send calls and messages to your smart phone. In that case you need to edit the reject line at the end of the rn2ncid.conf file: Specify the "from" of SMS/MMS messages to be rejected and not passed through to the NCID server. This is usually an email address dedicated to the SMS-to-email service of your carrier.

Test rn2ncid without connecting it to the ncidd server.

rn2ncid --test

Choose the Remote Notifier "Send test notification" option.

Client

The client receives the Caller ID from the server and displays it in one of three ways:

An output module can also send the information to a smart phone, pager, email address, and more.

Client Output Modules

An output module receives the Caller ID information from the ncid client and gives the client new functionality.

There are various output modules than come with NCID and there are also third party ones.

The following output modules are distributed:

Output modules are configured using files in the conf.d/ directory. There will be a separate file for each module that needs one, for example, conf.d/ncid-tivo.conf.

For more information, see the comments in the individual files in the conf.d/ directory and the man page for each module.

If you are using Debian, Fedora, Ubuntu, FreeBSD, OSX, or Raspbian you would use the OS specific ncid service script to activate the service.

For distributions not based on Debian, Fedora, or BSD the modules need to be started manually, Here are three examples:

    ncid --no-gui --program ncid-page &
    ncid --no-gui --program ncid-notify &
    ncid --no-gui --program ncid-speak &

Each of the above commands start ncid using an output module and puts it in the background. The first line starts ncid using the page output module. The second line starts ncid using the notify output module. The third line starts ncid using the speak output module.

You need to modify one line in ncid-page.conf and maybe one line in ncid.conf.

Find this line in ncid.conf:

   PageTo=

PageTo needs to be set to your mobile provider SMS e-mail address. Here are addresses for the major ones in the US:

   Sprint: phonenumber@messaging.sprintpcs.com
   Verizon: phonenumber@vtext.com
   T-Mobile: phonenumber@tmomail.com
   AT&T: phonenumber@txt.att.net
For example, if your provider is AT&T and your cell number is 1-321-555-1212, then your PageTo line becomes:
PageTo=13215551212@txt.att.net

If you want a page anytime the phone rings, you are finished.

if you only want a page if the phone call is unanswered or is at a certain ring count, you need to uncomment the ncid_page line in ncid.conf, then change the ring count as desired.

Be careful, all Caller ID devices do not indicate rings. If RING is not sent by the modem, a ring count will not work and the page will never be sent.

If you are using a modem, there is no indication of whether the the phone was answered or not. The modem sends RING to ncidd each time it gets the ringing signal. When RING is not sent anymore ncidd will indicate the end of ringing. A ring count of 4 is a good value to assume the phone was not answered. Remove the '#' so you have this line:

    set ncid_page {set Ring 4}

If you are using SIP, you can configure it to send the page on hangup without an answer by modifying the above line to:

    set ncid_page {set Ring -1}

See the comments in the ncid.conf file for more information on configuring the ring option line.

Verbose Levels

Table of Contents

Index

ncid verbose levels

Higher levels include lower levels.

LEVEL9:

    not used

LEVEL8:

    not used

LEVEL7:

    not used

LEVEL6:

    not used

LEVEL5:

    display the line type as a numeric
    show CIDINFO line

LEVEL4:

    shows fixed font family
    display history entries in milliseconds

LEVEL3:

    not used

LEVEL2:

    not used

LEVEL1:

    indicate if using PID file or not
    display about
    indicate if a output module is being used and which one
    indicate if optional module variable is not being used
    indicate if optional module variable is being used and ring count
    indicate width of name, number, line type, and history window
    display received data if in raw mode
    indicate when call log is completely received
    show CIDINFO line on ring count match
    show data sent to module
    indicate if phone line label not found
    show message sent to module
    show CID data sent to module
    show unsupported line labels
    show unsupported alias types
    display popup message

ncid2ncid gateway verbose levels

Higher levels include lower levels.

LEVEL9:

    (can only be set by the command line)
    not used

LEVEL8:

    (can only be set by the command line)
    not used

LEVEL7:

    not used

LEVEL6:

    not used

LEVEL5:

    not used

LEVEL4:

    indicate reading socket
    show call log lines received

LEVEL3:

    show all data received from all servers

LEVEL2:

    indicate line sent to receiving NCID server

LEVEL1:

    indicate cannot create or open existing logfile
    show start date and time
    show server version
    show command line
    indicate Debug mode
    indicate no config file
    indicate config file processed
    indicate set command skipped in config file
    show error line in config file
    show verbose level
    indicate not using PID file, there was no '-P' option
    indicate found stale pidfile
    indicate wrote pid in pidfile
    show Receiving Host host:port
    show server greeting line
    show configured Sending Hosts host:port
    show configured servers greeting line
    indicate client disconnected
    indicate client reconnected
    indicate Hung Up
    indicate Poll Error
    indicate Removed client, invalid request
    indicate Removed client, write event not configured
    indicate line cannot be sent to receiving NCID server
    indicate removed pidfile
    show terminated with date and time

ncidd server verbose levels

Higher levels include lower levels.

LEVEL9:

    (can only be set by the command line)

    show poll() events flag

LEVEL8:

    (can only be set by the command line)

    exit if verbose == LEVEL8

LEVEL7:

    show alias, blacklist, and whitelist tables

LEVEL6:

    indicate client sent empty line
    show optional files failed to open
    indicate sending data to each client

LEVEL5:

    display data as a hexdump
    show modem command return codes for hangup
    show lastring and ring count if ring detected
    

LEVEL4:

    indicate if name and nmbr received but no date or time
    indicate date, time, nmbr received
    indicate date, time, name or date, time, name, mesg received
    indicate date, time, nmbr, mesg received
    indicate date, time, nmbr, name or date, time, nmbr, name, mesg received
    Detected TCI serial device format
    Detected NetCallerID or gateway format
    Begin: and End: with time

LEVEL3:

    show number of tries to init modem
    show modem responses
    show modem query commands for software version, country code, operation modes
    Show client connection messages
    Show client HELLO line and Client Option accepted and removed
    indicate Non 7-bit ASCII message deleted
    indicate Gateway sent CALL data
    indicate Gateway sent CALLINFO data
    indicate Client sent text message
    indicate client sent unknown data
    show call data input
    show CIDINFO line
    show CID line
    show ACK line
    show checked whitelist and blacklist for match or whitelist empty
    indicate match in blacklist or whitelist with values

LEVEL2:

    show lines that start with a 3 digit number
    show client connect/disconnect
    indicate if client sent a HELLO Identification line
    indicate if client sent a HELLO Command line
    indicate if client command accepted
    indicate client command removed
    show number of times socket was zero in sequence when trying to remove client from poll
    show client removed on write error
    show client not found in poll table
    indicate network client hung up
    indicate device or modem returned no data
    indicate end of call log or call log empty or no call log sent
    indicate end of connection startup
    show line sent to cidupdate
    show line sent to ncidutil
    show OPT lines
    show REQ: lines
    show INFO: lines
    show WRK: lines
    show RESP: lines

LEVEL1:

    show started with date and time
    show server version
    indicate if could not create ncidd logfile
    indicate name and location of ncidd logfile
    indicate if no config file
    indicate config file processed
    indicate set command skipped in config file
    show error line in config file
    indicate error in opening ncidd log file
    indicate what is configured to send to the clients
    show verbose level
    indicate data type sent to clients
    indicate alias file messages
    indicate if leading 1 needed for aliases
    indicate blacklist  and whitelist file messages
    indicate alias, blacklist, and whitelist total/maximum entries, if any
    indicate cid logfile messages
    indicate of no call logfile
    indicate name and location of call logfile
    indicate if no data logfile
    indicate name and location of data logfile
    show Telephone Line Identifier
    show TTY port opened
    show TTY port speed
    show name and location of TTY lockfile
    indicate TTY port control signals enabled or disabled
    indicate CallerID from serial device and optional gateways
    indicate CallerID from AT Modem and optional gateways
    indicate Handles modem calls without Caller ID
    indicate Does not handle modem calls without Caller ID
    indicate CallerID from Gateway
    indicate hangup option
    show network port
    indicate not using PID file if no '-P' option
    indicate pid file already exists
    indicate found stale pidfile
    indicate cannot write pidfile
    indicate wrote pid in pidfile
    indicate end of startup
    indicate TTY in use with date and time
    indicate TTY free with date and time
    indicate cannot init TTY and terminated with date and time
    indicate Modem initialized.
    indicate Initialization string for modem is null.
    indicate Modem set for CallerID.
    indicate Modem does or does not support FAX
    indicate CallerID initialization string for modem is null.
    indicate CallerID TTY port initialized
    indicate serial device hung up and terminated with date and time
    indicate device error and terminated with date and time
    indicate serial device error and terminated with date and time
    indicate poll error
    indicate invalid request from serial device,terminated  with date and time
    indicate Invalid Request, removed client
    indicate Write event not configured, removed client
    indicate device or modem read error
    indicate Device returns no data, Terminated with date and time
    indicate network connect error
    indicate network NOBLOCK error
    indicate too many network clients
    indicate network client read error
    indicate cid log is too large
    indicate sending log to client
    indicate removed pidfile
    indicate signal received and terminate program with date and time
    indicate SIGHUP received and reload alias files
    indicate SIGPIPE received and ignored with date and time
    indicate Failed to remove stale lockfile
    indicate Removed stale lockfile

obi2ncid gateway verbose levels

Higher levels include lower levels.

LEVEL9:

    not used

LEVEL8:

    not used

LEVEL7:

    Show call log from ncidd, if received

LEVEL6:

    Indicate start and end of received packets
    Filter received packets

LEVEL5:

    Show call or message line from ncidd
    Show log lines received from the obi

LEVEL4:

    Show what matched on a log line from the obi
    Show variables set by the match

LEVEL3:

    Show CALL: line generated
    Show CALLINFO: line generated
    Indicated Outgoing call not completed

LEVEL2:

    not used

LEVEL1:

    Show Started
    Show command line and any options on separate lines
    Show logfile name and opened as append or overwrite or could not open
    Show processed config file or config file not found
    Show name and version
    Show verbose level
    Show default lineid
    Show NCID address:port
    Show delay time between retrying failed connection
    Show debug mode if in debug mode
    Show test mode if in test mode
    Show PID or some PID problem or not using PID file
    Show connected to NCID address:port or error exit
    Show greeting line from NCID
    Show listening port or error exit
    Show exit on error
    Show signals ingnored
    Show NCID server disconnected if it goes away and trying to reconnect
    Show terminated and signal that caused it

rn2ncid gateway verbose levels

Higher levels include lower levels.

LEVEL9:

    not used

LEVEL8:

    not used

LEVEL7:

    not used

LEVEL6:

    not used

LEVEL5:

    Show call log from ncidd, if received
    Show call or message line from ncidd
    Show messgae line from remote notification

LEVEL4:

    not used

LEVEL3:

    Show notification type
    Show Call: line generated if type RING
    Show NOT: line generated if type PING, Battery, SMS, MMS, or VOICEMAIL
    Show notice of a SMS or MMS message
    Show unknown notification type
    Show notification type was rejected

LEVEL2:

    not used

LEVEL1:

    Show Started
    Show command line and any options on separate lines
    Show logfile name and opened as append or overwrite or could not open
    Show processed config file or config file not found
    Show name and version
    Show verbose level
    Show debug mode if in debug mode
    Show test mode if in test mode
    Show reject option values or none
    Show pid or some PID problem
    Show connected to NCID address:port or error exit
    Show greeting line from NCID
    Show listening port or error exit
    Show NCID server disconnected if it goes away and trying to reconnect

sip2ncid gateway verbose levels

Higher levels include lower levels.

LEVEL9:

    (can only be set by the command line)

    show lines received from the NCID server

LEVEL8:

    not used

LEVEL7:

    not used

LEVEL6:

    not used

LEVEL5:

    show linenum array and number as they are compared for a call
    indicate checked for "Call ID: call-" and outcall value

LEVEL4:

    UDP packet from address
    UDP packet to address
    IP protocol
    UDP source port
    UDP destination port
    UDP data size in bytes
    indicate Alarm Timeout and msgsent flag
    show call log if sent

LEVEL3:

    show UDP SIP packets
    give character count of lines received from the NCID server
    show alarm timeout, pcap\_loop() return value, and msgsent flags

LEVEL2:

    indicate cannot write pidfile
    show packet number received
    show Duplicate INVITE Packet <pkt#> with <invpkt#>
    show Ignoring Trying Packet <pkt#>
    show Ignoring Ringing Packet <pkt#>
    show Warning: could not connect to the NCID server

LEVEL1:

    indicate cannot create or open existing logfile
    show start date and time
    show server and API versions
    indicate test mode
    indicate Debug mode
    indicate no config file
    indicate config file processed
    indicate set command skipped in config file
    show error line in config file
    indicate Reading from dumpfile
    indicate Writing to dumpfile
    show verbose level
    show status: Warn clients: 'No SIP packets' & 'SIP packets returned'
    show status:  Remove duplicate INVITE Packets?
    show NCID server host:port
    show network interface used
    show applied filter
    indicate no filter applied
    indicate No SIP packets received
    indicate SIP packets returned
    indicate not using PID file, there was no '-P' option
    indicate pid file already exists
    indicate found stale pidfile
    indicate wrote pid in pidfile
    alarm SIP packets returned
    Warning: SIP Packet truncated
    Warning: simultaneous calls exceeded
    invalid IP header length
    show registered line number
    indicate Number of telephone lines exceed
    show CID line sent to NCID
    indicate packet parse problems
    indicate caller hangup before answer
    indicate hangup after answer
    Warning: cannot get CallID
    Warning: Warning no SIP packets
    indicate pcap\_loop error
    indicate removed pidfile
    indicate program terminated with date and time

wc2ncid gateway verbose levels

Higher levels include lower levels.

LEVEL9:

    not used

LEVEL8:

    not used

LEVEL7:

    not used

LEVEL6:

    not used

LEVEL5:

    Show call log from ncidd, if received
    Show Caller ID line from ncidd

LEVEL4:

    Show hex dump of received packet

LEVEL3:

    Show unit and serial numbers from Whozz Calling device
    Show Call line from Whozz Calling device

LEVEL2:

    Show CALL and CALLINFO lines sent to ncidd
    Show Phone Off Hook
    Show Phone On Hook

LEVEL1:

    Show Started
    Show command line and any options on separate lines
    Show version
    Show verbose level
    Show debug mode if in debug mode
    Show test mode if in test mode
    Show logfile name and whether opened as append or overwrite
    Show logfile could not be opened
    Show processed config file or config file not found
    Show connected to NCID address:port or error exit
    Show greeting line from NCID
    Show opened broadcast port
    Show closed broadcast port
    Show opened WC device port
    Show closed WC device port
    Show commands sent
    Show Pause after sending ^^Id-V
    Show checking and setting required flags
    Indicate command data received or timeout in seconds
    Show data from some commands

NCID Contributors

Table of Contents

Any omissions are entirely my fault. Please notify of any corrections or additions.

Mace Moneta

Rick Matthews

Michael Nygren

Mitch Riley

Roger Knobber

Jonathan Wolf

New Feature Requests, Bug Reports, Testing Fixes, and Testing New features

Adam 'Starblazer' Romberg
Andy Nunez
Andy Writter
Aron Green
Carl Johnson
Charlie Heitzig
Dan Lawrence
David LaPorte
George Johnson
Joe Nardone
Jonathan Wolf
Ken Appell
Lloyd Stahlbush
Mace Moneta
Marko Koski-Vähälä
Matt Short
Michael Lasevich
Nicholas Davies
Paul Miller
Phil Fitzpatrick
Rick Matthews
Steve Forman
Steve Major
Troy Carpenter

Feedback On Working Modems

Derek Huxley

TODO

Table of Contents

TODO Lists

The TODO list (in no particular order)

The Maybe list (in no particular order)

GNU GENERAL PUBLIC LICENSE

Version 3, 29 June 2007

Copyright (C) 2007 Free Software Foundation, Inc.

Everyone is permitted to copy and distribute verbatim copies of this license document, but changing it is not allowed.

Preamble

The GNU General Public License is a free, copyleft license for software and other kinds of works.

The licenses for most software and other practical works are designed to take away your freedom to share and change the works. By contrast, the GNU General Public License is intended to guarantee your freedom to share and change all versions of a program--to make sure it remains free software for all its users. We, the Free Software Foundation, use the GNU General Public License for most of our software; it applies also to any other work released this way by its authors. You can apply it to your programs, too.

When we speak of free software, we are referring to freedom, not price. Our General Public Licenses are designed to make sure that you have the freedom to distribute copies of free software (and charge for them if you wish), that you receive source code or can get it if you want it, that you can change the software or use pieces of it in new free programs, and that you know you can do these things.

To protect your rights, we need to prevent others from denying you these rights or asking you to surrender the rights. Therefore, you have certain responsibilities if you distribute copies of the software, or if you modify it: responsibilities to respect the freedom of others.

For example, if you distribute copies of such a program, whether gratis or for a fee, you must pass on to the recipients the same freedoms that you received. You must make sure that they, too, receive or can get the source code. And you must show them these terms so they know their rights.

Developers that use the GNU GPL protect your rights with two steps:

  1. assert copyright on the software, and
  2. offer you this License giving you legal permission to copy, distribute and/or modify it.

For the developers' and authors' protection, the GPL clearly explains that there is no warranty for this free software. For both users' and authors' sake, the GPL requires that modified versions be marked as changed, so that their problems will not be attributed erroneously to authors of previous versions.

Some devices are designed to deny users access to install or run modified versions of the software inside them, although the manufacturer can do so. This is fundamentally incompatible with the aim of protecting users' freedom to change the software. The systematic pattern of such abuse occurs in the area of products for individuals to use, which is precisely where it is most unacceptable. Therefore, we have designed this version of the GPL to prohibit the practice for those products. If such problems arise substantially in other domains, we stand ready to extend this provision to those domains in future versions of the GPL, as needed to protect the freedom of users.

Finally, every program is threatened constantly by software patents. States should not allow patents to restrict development and use of software on general-purpose computers, but in those that do, we wish to avoid the special danger that patents applied to a free program could make it effectively proprietary. To prevent this, the GPL assures that patents cannot be used to render the program non-free.

The precise terms and conditions for copying, distribution and modification follow.

TERMS AND CONDITIONS

0. Definitions.

This License refers to version 3 of the GNU General Public License.

Copyright also means copyright-like laws that apply to other kinds of works, such as semiconductor masks.

The Program refers to any copyrightable work licensed under this License. Each licensee is addressed as you. Licensees and recipients may be individuals or organizations.

To modify a work means to copy from or adapt all or part of the work in a fashion requiring copyright permission, other than the making of an exact copy. The resulting work is called a modified version of the earlier work or a work based on the earlier work.

A covered work means either the unmodified Program or a work based on the Program.

To propagate a work means to do anything with it that, without permission, would make you directly or secondarily liable for infringement under applicable copyright law, except executing it on a computer or modifying a private copy. Propagation includes copying, distribution (with or without modification), making available to the public, and in some countries other activities as well.

To convey a work means any kind of propagation that enables other parties to make or receive copies. Mere interaction with a user through a computer network, with no transfer of a copy, is not conveying.

An interactive user interface displays Appropriate Legal Notices to the extent that it includes a convenient and prominently visible feature that

  1. displays an appropriate copyright notice, and
  2. tells the user that there is no warranty for the work (except to the extent that warranties are provided), that licensees may convey the work under this License, and how to view a copy of this License.

If the interface presents a list of user commands or options, such as a menu, a prominent item in the list meets this criterion.

1. Source Code.

The source code for a work means the preferred form of the work for making modifications to it. Object code means any non-source form of a work.

A Standard Interface means an interface that either is an official standard defined by a recognized standards body, or, in the case of interfaces specified for a particular programming language, one that is widely used among developers working in that language.

The System Libraries of an executable work include anything, other than the work as a whole, that (a) is included in the normal form of packaging a Major Component, but which is not part of that Major Component, and (b) serves only to enable use of the work with that Major Component, or to implement a Standard Interface for which an implementation is available to the public in source code form. A Major Component, in this context, means a major essential component (kernel, window system, and so on) of the specific operating system (if any) on which the executable work runs, or a compiler used to produce the work, or an object code interpreter used to run it.

The Corresponding Source for a work in object code form means all the source code needed to generate, install, and (for an executable work) run the object code and to modify the work, including scripts to control those activities. However, it does not include the work's System Libraries, or general-purpose tools or generally available free programs which are used unmodified in performing those activities but which are not part of the work. For example, Corresponding Source includes interface definition files associated with source files for the work, and the source code for shared libraries and dynamically linked subprograms that the work is specifically designed to require, such as by intimate data communication or control flow between those subprograms and other parts of the work.

The Corresponding Source need not include anything that users can regenerate automatically from other parts of the Corresponding Source.

The Corresponding Source for a work in source code form is that same work.

2. Basic Permissions.

All rights granted under this License are granted for the term of copyright on the Program, and are irrevocable provided the stated conditions are met. This License explicitly affirms your unlimited permission to run the unmodified Program. The output from running a covered work is covered by this License only if the output, given its content, constitutes a covered work. This License acknowledges your rights of fair use or other equivalent, as provided by copyright law.

You may make, run and propagate covered works that you do not convey, without conditions so long as your license otherwise remains in force. You may convey covered works to others for the sole purpose of having them make modifications exclusively for you, or provide you with facilities for running those works, provided that you comply with the terms of this License in conveying all material for which you do not control copyright. Those thus making or running the covered works for you must do so exclusively on your behalf, under your direction and control, on terms that prohibit them from making any copies of your copyrighted material outside their relationship with you.

Conveying under any other circumstances is permitted solely under the conditions stated below. Sublicensing is not allowed; section 10 makes it unnecessary.

No covered work shall be deemed part of an effective technological measure under any applicable law fulfilling obligations under article 11 of the WIPO copyright treaty adopted on 20 December 1996, or similar laws prohibiting or restricting circumvention of such measures.

When you convey a covered work, you waive any legal power to forbid circumvention of technological measures to the extent such circumvention is effected by exercising rights under this License with respect to the covered work, and you disclaim any intention to limit operation or modification of the work as a means of enforcing, against the work's users, your or third parties' legal rights to forbid circumvention of technological measures.

4. Conveying Verbatim Copies.

You may convey verbatim copies of the Program's source code as you receive it, in any medium, provided that you conspicuously and appropriately publish on each copy an appropriate copyright notice; keep intact all notices stating that this License and any non-permissive terms added in accord with section 7 apply to the code; keep intact all notices of the absence of any warranty; and give all recipients a copy of this License along with the Program.

You may charge any price or no price for each copy that you convey, and you may offer support or warranty protection for a fee.

5. Conveying Modified Source Versions.

You may convey a work based on the Program, or the modifications to produce it from the Program, in the form of source code under the terms of section 4, provided that you also meet all of these conditions:

A compilation of a covered work with other separate and independent works, which are not by their nature extensions of the covered work, and which are not combined with it such as to form a larger program, in or on a volume of a storage or distribution medium, is called an aggregate if the compilation and its resulting copyright are not used to limit the access or legal rights of the compilation's users beyond what the individual works permit. Inclusion of a covered work in an aggregate does not cause this License to apply to the other parts of the aggregate.

6. Conveying Non-Source Forms.

You may convey a covered work in object code form under the terms of sections 4 and 5, provided that you also convey the machine-readable Corresponding Source under the terms of this License, in one of these ways:

A separable portion of the object code, whose source code is excluded from the Corresponding Source as a System Library, need not be included in conveying the object code work.

A User Product is either

  1. a consumer product, which means any tangible personal property which is normally used for personal, family, or household purposes, or
  2. anything designed or sold for incorporation into a dwelling.

In determining whether a product is a consumer product, doubtful cases shall be resolved in favor of coverage. For a particular product received by a particular user, normally used refers to a typical or common use of that class of product, regardless of the status of the particular user or of the way in which the particular user actually uses, or expects or is expected to use, the product. A product is a consumer product regardless of whether the product has substantial commercial, industrial or non-consumer uses, unless such uses represent the only significant mode of use of the product.

Installation Information for a User Product means any methods, procedures, authorization keys, or other information required to install and execute modified versions of a covered work in that User Product from a modified version of its Corresponding Source. The information must suffice to ensure that the continued functioning of the modified object code is in no case prevented or interfered with solely because modification has been made.

If you convey an object code work under this section in, or with, or specifically for use in, a User Product, and the conveying occurs as part of a transaction in which the right of possession and use of the User Product is transferred to the recipient in perpetuity or for a fixed term (regardless of how the transaction is characterized), the Corresponding Source conveyed under this section must be accompanied by the Installation Information. But this requirement does not apply if neither you nor any third party retains the ability to install modified object code on the User Product (for example, the work has been installed in ROM).

The requirement to provide Installation Information does not include a requirement to continue to provide support service, warranty, or updates for a work that has been modified or installed by the recipient, or for the User Product in which it has been modified or installed. Access to a network may be denied when the modification itself materially and adversely affects the operation of the network or violates the rules and protocols for communication across the network.

Corresponding Source conveyed, and Installation Information provided, in accord with this section must be in a format that is publicly documented (and with an implementation available to the public in source code form), and must require no special password or key for unpacking, reading or copying.

7. Additional Terms.

Additional permissions are terms that supplement the terms of this License by making exceptions from one or more of its conditions. Additional permissions that are applicable to the entire Program shall be treated as though they were included in this License, to the extent that they are valid under applicable law. If additional permissions apply only to part of the Program, that part may be used separately under those permissions, but the entire Program remains governed by this License without regard to the additional permissions.

When you convey a copy of a covered work, you may at your option remove any additional permissions from that copy, or from any part of it. (Additional permissions may be written to require their own removal in certain cases when you modify the work.) You may place additional permissions on material, added by you to a covered work, for which you have or can give appropriate copyright permission.

Notwithstanding any other provision of this License, for material you add to a covered work, you may (if authorized by the copyright holders of that material) supplement the terms of this License with terms:

All other non-permissive additional terms are considered further restrictions within the meaning of section 10. If the Program as you received it, or any part of it, contains a notice stating that it is governed by this License along with a term that is a further restriction, you may remove that term. If a license document contains a further restriction but permits relicensing or conveying under this License, you may add to a covered work material governed by the terms of that license document, provided that the further restriction does not survive such relicensing or conveying.

If you add terms to a covered work in accord with this section, you must place, in the relevant source files, a statement of the additional terms that apply to those files, or a notice indicating where to find the applicable terms.

Additional terms, permissive or non-permissive, may be stated in the form of a separately written license, or stated as exceptions; the above requirements apply either way.

8. Termination.

You may not propagate or modify a covered work except as expressly provided under this License. Any attempt otherwise to propagate or modify it is void, and will automatically terminate your rights under this License (including any patent licenses granted under the third paragraph of section 11).

However, if you cease all violation of this License, then your license from a particular copyright holder is reinstated

Moreover, your license from a particular copyright holder is reinstated permanently if the copyright holder notifies you of the violation by some reasonable means, this is the first time you have received notice of violation of this License (for any work) from that copyright holder, and you cure the violation prior to 30 days after your receipt of the notice.

Termination of your rights under this section does not terminate the licenses of parties who have received copies or rights from you under this License. If your rights have been terminated and not permanently reinstated, you do not qualify to receive new licenses for the same material under section 10.

9. Acceptance Not Required for Having Copies.

You are not required to accept this License in order to receive or run a copy of the Program. Ancillary propagation of a covered work occurring solely as a consequence of using peer-to-peer transmission to receive a copy likewise does not require acceptance. However, nothing other than this License grants you permission to propagate or modify any covered work. These actions infringe copyright if you do not accept this License. Therefore, by modifying or propagating a covered work, you indicate your acceptance of this License to do so.

10. Automatic Licensing of Downstream Recipients.

Each time you convey a covered work, the recipient automatically receives a license from the original licensors, to run, modify and propagate that work, subject to this License. You are not responsible for enforcing compliance by third parties with this License.

An entity transaction is a transaction transferring control of an organization, or substantially all assets of one, or subdividing an organization, or merging organizations. If propagation of a covered work results from an entity transaction, each party to that transaction who receives a copy of the work also receives whatever licenses to the work the party's predecessor in interest had or could give under the previous paragraph, plus a right to possession of the Corresponding Source of the work from the predecessor in interest, if the predecessor has it or can get it with reasonable efforts.

You may not impose any further restrictions on the exercise of the rights granted or affirmed under this License. For example, you may not impose a license fee, royalty, or other charge for exercise of rights granted under this License, and you may not initiate litigation (including a cross-claim or counterclaim in a lawsuit) alleging that any patent claim is infringed by making, using, selling, offering for sale, or importing the Program or any portion of it.

11. Patents.

A contributor is a copyright holder who authorizes use under this License of the Program or a work on which the Program is based. The work thus licensed is called the contributor's contributor version.

A contributor's essential patent claims are all patent claims owned or controlled by the contributor, whether already acquired or hereafter acquired, that would be infringed by some manner, permitted by this License, of making, using, or selling its contributor version, but do not include claims that would be infringed only as a consequence of further modification of the contributor version. For purposes of this definition, control includes the right to grant patent sublicenses in a manner consistent with the requirements of this License.

Each contributor grants you a non-exclusive, worldwide, royalty-free patent license under the contributor's essential patent claims, to make, use, sell, offer for sale, import and otherwise run, modify and propagate the contents of its contributor version.

In the following three paragraphs, a patent license is any express agreement or commitment, however denominated, not to enforce a patent (such as an express permission to practice a patent or covenant not to sue for patent infringement). To grant such a patent license to a party means to make such an agreement or commitment not to enforce a patent against the party.

If you convey a covered work, knowingly relying on a patent license, and the Corresponding Source of the work is not available for anyone to copy, free of charge and under the terms of this License, through a publicly available network server or other readily accessible means, then you must either

  1. cause the Corresponding Source to be so available, or
  2. arrange to deprive yourself of the benefit of the patent license for this particular work, or
  3. arrange, in a manner consistent with the requirements of this License, to extend the patent license to downstream recipients.

Knowingly relying means you have actual knowledge that, but for the patent license, your conveying the covered work in a country, or your recipient's use of the covered work in a country, would infringe one or more identifiable patents in that country that you have reason to believe are valid.

If, pursuant to or in connection with a single transaction or arrangement, you convey, or propagate by procuring conveyance of, a covered work, and grant a patent license to some of the parties receiving the covered work authorizing them to use, propagate, modify or convey a specific copy of the covered work, then the patent license you grant is automatically extended to all recipients of the covered work and works based on it.

A patent license is discriminatory if it does not include within the scope of its coverage, prohibits the exercise of, or is conditioned on the non-exercise of one or more of the rights that are specifically granted under this License. You may not convey a covered work if you are a party to an arrangement with a third party that is in the business of distributing software, under which you make payment to the third party based on the extent of your activity of conveying the work, and under which the third party grants, to any of the parties who would receive the covered work from you, a discriminatory patent license

Nothing in this License shall be construed as excluding or limiting any implied license or other defenses to infringement that may otherwise be available to you under applicable patent law.

12. No Surrender of Others' Freedom.

If conditions are imposed on you (whether by court order, agreement or otherwise) that contradict the conditions of this License, they do not excuse you from the conditions of this License. If you cannot convey a covered work so as to satisfy simultaneously your obligations under this License and any other pertinent obligations, then as a consequence you may not convey it at all. For example, if you agree to terms that obligate you to collect a royalty for further conveying from those to whom you convey the Program, the only way you could satisfy both those terms and this License would be to refrain entirely from conveying the Program.

13. Use with the GNU Affero General Public License.

Notwithstanding any other provision of this License, you have permission to link or combine any covered work with a work licensed under version 3 of the GNU Affero General Public License into a single combined work, and to convey the resulting work. The terms of this License will continue to apply to the part which is the covered work, but the special requirements of the GNU Affero General Public License, section 13, concerning interaction through a network will apply to the combination as such.

14. Revised Versions of this License.

The Free Software Foundation may publish revised and/or new versions of the GNU General Public License from time to time. Such new versions will be similar in spirit to the present version, but may differ in detail to address new problems or concerns.

Each version is given a distinguishing version number. If the Program specifies that a certain numbered version of the GNU General Public License or any later version applies to it, you have the option of following the terms and conditions either of that numbered version or of any later version published by the Free Software Foundation. If the Program does not specify a version number of the GNU General Public License, you may choose any version ever published by the Free Software Foundation.

If the Program specifies that a proxy can decide which future versions of the GNU General Public License can be used, that proxy's public statement of acceptance of a version permanently authorizes you to choose that version for the Program.

Later license versions may give you additional or different permissions. However, no additional obligations are imposed on any author or copyright holder as a result of your choosing to follow a later version.

15. Disclaimer of Warranty.

THERE IS NO WARRANTY FOR THE PROGRAM, TO THE EXTENT PERMITTED BY APPLICABLE LAW. EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES PROVIDE THE PROGRAM AS IS WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE PROGRAM IS WITH YOU. SHOULD THE PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING, REPAIR OR CORRECTION.

16. Limitation of Liability.

IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MODIFIES AND/OR CONVEYS THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES, INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER PROGRAMS), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.

17. Interpretation of Sections 15 and 16.

If the disclaimer of warranty and limitation of liability provided above cannot be given local legal effect according to their terms, reviewing courts shall apply local law that most closely approximates an absolute waiver of all civil liability in connection with the Program, unless a warranty or assumption of liability accompanies a copy of the Program in return for a fee.

END OF TERMS AND CONDITIONS

How to Apply These Terms to Your New Programs

If you develop a new program, and you want it to be of the greatest possible use to the public, the best way to achieve this is to make it free software which everyone can redistribute and change under these terms.

To do so, attach the following notices to the program. It is safest to attach them to the start of each source file to most effectively state the exclusion of warranty; and each file should have at least the copyright line and a pointer to where the full notice is found.

<one line to give the program's name and a brief idea of what it does.>
Copyright (C) <year>  <name of author>

This program is free software: you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation, either version 3 of the License, or
(at your option) any later version.

This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
GNU General Public License for more details.

You should have received a copy of the GNU General Public License
along with this program.  If not, see <http://www.gnu.org/licenses/>.

Also add information on how to contact you by electronic and paper mail.

If the program does terminal interaction, make it output a short notice like this when it starts in an interactive mode:

<program>  Copyright (C) <year>  <name of author>
This program comes with ABSOLUTELY NO WARRANTY; for details type `show w'.
This is free software, and you are welcome to redistribute it
under certain conditions; type `show c' for details.

The hypothetical commands show w and show c should show the appropriate parts of the General Public License. Of course, your program's commands might be different; for a GUI interface, you would use an about box.

You should also get your employer (if you work as a programmer) or school, if any, to sign a copyright disclaimer for the program, if necessary. For more information on this, and how to apply and follow the GNU GPL, see http://www.gnu.org/licenses/.

The GNU General Public License does not permit incorporating your program into proprietary programs. If your program is a subroutine library, you may consider it more useful to permit linking proprietary applications with the library. If this is what you want to do, use the GNU Lesser General Public License instead of this License. But first, please read http://www.gnu.org/philosophy/why-not-lgpl.html.