OBI2NCID(1)

📦
version 1.18 · 2 versions
, in fedora 43

💖 OBI2NCID — the manual, bestie edition 💖

okay so you're reading the manual for obi2ncid, which is a User Contributed Perl Documentation page (the OBI2NCID(1) one, yes) and honestly? iconic. let's get into it.

✨ NAME ✨

obi2ncid — Obihai device to NCID gateway. that's the whole name, that's the whole vibe. 🦋

✨ SYNOPSIS ✨

 obi2ncid [--configfile        | -C <filename>]
          [--debug             | -D]
          [--delay             | -d <seconds>]
          [--help              | -h]
          [--hostname-flag     | -H <0|1>]
          [--linefx            | -f <string>]
          [--logfile-append    | -l <filename>]
          [--logfile-overwrite | -L <filename>]
          [--man               | -m]
          [--ncidhost          | -n <[host][:port]>]
          [--no-filter         | -N]
          [--obiport           | -o <port>]
          [--pidfile           | -p <filename>]
          [--rawfile-append    | -r <filename>]
          [--rawfile-overwrite | -R <filename>]
          [--test              | -t]
          [--verbose           | -v <1-9>]
          [--version           | -V]

no cap, that's a lot of flags and every single one of them is real. 🫶

✨ DESCRIPTION ✨

so the obi2ncid gateway is out here doing the most: it grabs Caller ID from an Obihai VOiP telephone adapter and sends it over to the NCID server. then the server does its thing and passes that CID info along to the NCID clients. teamwork, fr fr. 💅

this gateway was developed using Obi100, OBi110 and OBi200 devices that were available. that's what they had, and they ate with it.

the obi2ncid gateway uses either GTALK, the Voice Service AuthUserName, or the configurable default name for a line identifier.

the line identifier(s) can be aliased by the NCID server, so you can give each Voice Service a meaningful identification. like, give your lines a glow-up, they deserve names. ✨

the obi2ncid configuration file is prefix3=/etc/ncid/obi2ncid.conf. see the obi2ncid.conf man page for more details.

the obi2ncid gateway can run on any computer, but normally it is run on the same box as the NCID server. if it is not run on the same box as the NCID server, you must configure the server IP address in the configuration file. no skipping this step bestie.

🌸 LINEID 🌸

the obi2ncid gateway attempts to assign the lineid based on the following table. "SP" is an abbreviation for "Service Provider" and "PSTN" is an abbreviation for "Public Switched Telephone Network."

  • Google Voice in or out → lineid assigned: "GTALK"
  • VoIP in or out on default line → lineid assigned: <AuthUserName>
  • Incoming PSTN → lineid assigned: "FXO"
  • Outgoing PSTN using ##<number> → lineid assigned: "FXS"
  • Outgoing VoIP using **1<number> → lineid assigned: "SP1"
  • Outgoing VoIP using **2<number> → lineid assigned: "SP2"
  • Outgoing VoIP using **3<number> → lineid assigned: "SP3"
  • Outgoing VoIP using **4<number> → lineid assigned: "SP4"
  • Device setup using **5<number> → lineid assigned: "SP5"
  • Outgoing VoIP using **9<number> → lineid assigned: "OBITALK" (a.k.a. Obi-to-Obi)
NOTES: If line selected is the GTALK line, then GTALK replaces SP?. If line selected is **9, then OBITALK replaces SP9. PSTN requires an OBiLINE device connected to an Obi200.

for incoming/outgoing PSTN calls, see the description for --linefx. 👀

if **[0-9] is dialed on the keypad to select a line, the lineid becomes SP[0-9].

the number of SP lines are 1 to 4 plus 5 and 9, depending on the device. the default lineid for SP1 to SP4 can be changed only in the obi2ncid.conf configuration file. Google Talk is special in that "GTALK" can be detected on which SP line is used for it. the other voice providers must have their linesp[0-4] variable set to their lineid.

SP9 has the reserved lineid of "OBITALK" and can not be changed. periodt. 🚫

in cases where the lineid cannot otherwise be determined, the default lineid becomes OBIHAI.

⚠️ IMPORTANT ⚠️

This gateway does not work properly with a OBILINE add-on accessory that connects to a phone line. 😭 that's the whole warning. i'm just the messenger.

✨ REQUIREMENTS ✨

  • Obihai VoIP Telephone Adapter: Obi100, Obi110, Obi200, Obi202?
  • Google Voice or a SIP voice provider
    • (voip.ms, callcentric, others untested) — "others untested" is doing so much heavy lifting there bestie 😭
  • The NCID server
  • perl 5.6 or higher, perl(Config::Simple)

✨ OPTIONS ✨

  • --configfile <filename>, -C <filename> — specifies the configuration file to use. the program will still run if a configuration file is not found. (it's chill like that.)
    • Default: prefix3=/etc/ncid/obi2ncid.conf
  • --debug, -D — debug mode, displays all messages that go into the log file. use this option to run interactively. main character energy, you get to watch everything live. 🔥
  • --delay <seconds>, -d <seconds> — if the connection to the NCID server is lost, try every <delay> seconds to reconnect.
    • Default: 15
  • --help, -h — displays the help message and exits. bye bestie 🫶
  • --hostname-flag <0|1>, -H <0|1> — when the hostname flag is set to 1, the IDENT string sent to a server will include the hostname with the program name.
    • Default: 0
  • --linefx <string>, -f <string> — this option requires the OBiLINE FXO-to-USB Phone Line Adapter for the Obi2xx series. the Obi110 has it built in. normally "FXO" and "FXS" refer to line (telco) and phone (handset) respectively. OBiLINE changes the meaning of these to be "FXO" for incoming calls and "FXS" for outgoing calls, so by default "FXO" and "FXS" are used as the lineid and can not be changed. however, if --linefx is given a value, it replaces both "FXO" and "FXS" with that value. for example:
 --linefx POTS will cause the lineid for incoming and outgoing

calls to be POTS.

  • Default: no default
  • --logfile-append <filename>, -l <filename>
  • --logfile-overwrite <filename>, -L <filename> — specifies the logfile name to write. the program will still run if it does not have permission to write to it. if both options are present, --logfile-append takes precedence.
    • Default: Append to /var/log/obi2ncid.log
  • --man, -m — displays the manual page and exits. (hi, you're here 🎀)
  • --ncidhost <[host][:port]>, -n <[host][:port]> — specifies the NCID server. port may be specified by suffixing the hostname with :<port>. input must be <host> or <host:port>, or <:port>.
    • Default: localhost:3333
  • --no-filter, -N — useful for development and troubleshooting purposes. a list of zero or more filter lines is stored in obi2ncid.conf. an Obihai device periodically sends out packets when it is doing its own internal "housekeeping." such packets do not have anything to do with call activity, but they can clutter and confuse verbose output because of their sheer volume and frequency. however, in unusual circumstances it may be necessary to use the --no-filter option to include all housekeeping packets.
    • Default: filtering is ON
  • --obiport <port>, -o <port> — specifies the UDP port to listen on for Caller ID from an OBi device.
    • Default: 4335
  • --pcap-read <filename> — read packets from a libpcap capture file instead of the network. this also sets the test option and verbose to level 3. mostly only useful for development and debug purposes. (no short flag for this one, she's independent 💅)
  • --pidfile <filename>, -p <filename> — specifies the pidfile name to write. the program will still run if it does not have permission to write a pidfile. the pid filename that should be used is /var/run/obi2ncid.pid.
    • Default: no pidfile
  • --rawfile-append <filename>, -r <filename>
  • --rawfile-overwrite <filename>, -R <filename> — useful for development and troubleshooting purposes. writes packets to a file exactly as received from the gateway device. a filename extension of .data is suggested. the rawfile can be "played back" using test-obi-gw. raw packets from Obihai devices do not have a date/time stamp. when played back, the obi2ncid gateway script will treat the packets as arriving using the current date/time. if both options are present, --rawfile-append takes precedence.
    • Default: no raw file
  • --test, -t — test mode is a connection to the gateway device without a connection to the NCID server. it sets debug mode and verbose = 3. the verbose level can be changed on the command line.
    • Default: no test mode
  • --verbose <1-9>, -v <1-9> — output information, used for the logfile and the debug option. set the level to a higher number for more information. levels range from 1 to 9, but not all levels are used. (so real for that honestly 🙈)
    • Default: verbose = 1
  • --version, -V — displays the version and exits.

✨ EXAMPLES ✨

start obi2ncid in test mode at verbose level 3

 obi2ncid --test

start obi2ncid in test mode at verbose level 5 and keep a test log

 obi2ncid -t -v5 -L test.log

start obi2ncid in test mode and keep a file of the input data

 obi2ncid -t -R test.data

start obi2ncid in debug mode at verbose level 1

 obi2ncid -D

✨ FILES ✨

prefix3=/etc/ncid/obi2ncid.conf

✨ SEE ALSO ✨

obi2ncid.conf.5, ncidd.8, ncidd.conf.5, ncid_gateways.7 — go read these too, they're the supporting cast and they serve. 👑

okay that's the whole page bestie, you made it. this was written as User Contributed Perl Documentation, perl v5.42.0, dated 2025-08-06, and it lives in section OBI2NCID(1). go forth and gateway. slay 💖🦋✨

📦 where this page comes from