The Nortel Millennium payphones utilize a Manager to facilitate installation, reporting, call cost rating, and credit card processing. This Millennium payphone calls into the Manager using a 1200-baud phone modem. Unlike some other COCOT payphones, the Manager never calls the payphone.

mm_manager runs on Windows, Linux, and MacOS X.

The mm_manager has been tested with a Nortel Multi-Pay (coin, credit card) Terminal with both V1.0 Control PCP (Through-hole, 1.20 firmware) and V1.1 Control PCP (Surface-mount, 2.11 firmware.) It partially works with other terminal types and firmware versions, see table for limitations:

1. Nortel Millennium Terminal running stock firmware (v1.20 or v2.20 is best, but other versions may work.) Some Millennium Terminals purchased from online phone stores may have been re-programmed with “demo” firmware that does not need a Manager. If you have one of these phones, you’ll have to program the phone back to stock firmware.
2. 24VDC @500mA Power Supply for Millennium Terminal
3. 4-pin plug-in screw terminal block to connect 24VDC power and Tip/Ring to the terminal.
4. Two phone lines (one for mm_manager, one for the Millennium terminal.) They can be real POTS lines, or lines from your own PBX, but the Millennium should be able to dial the manager with a 1- to 15-digit number.
5. 1200-baud or faster modem that supports Bell 212A modulation. I like the Lenovo 56K USB modems, but any 56K modem with Conexant chipset should work. Note for Linux users - Conexant soft-modems have never had a fully open-source driver, and the out-of-tree driver has not been maintained since kernel v2.4 - something like the US Robotics 5637 or another "real" modem where the device actually is responsible for encoding and decoding the data works well.
6. mm_manager software and a Windows, Linux machine (Raspberry Pi works great) or MacOS machine. This machine should be available 24x7 so the terminal can call in when needed.
7. All terminals except desk: T-Key such as the Jonard JIC-719A to open the payphone. I don’t recommend the flat, stamped T-keys as they are prone to bending.
8. All terminals except desk: Keys for your terminal’s upper and lower locks, if locks are present.
9. Desk Terminal Only: A “Key Card” to enter the craft access menu. This can be any credit card– best to use an expired one. Specify the first 10-digits of the credit card number to mm_manager with the -k option. The default key card number is 4012888888. You can also program a magnetic stripe card with that number.

Simply download the source files and example tables from GitHub.

From the shell, type:

cmake .
make

to compile mm_manager, and several utilities.

Compile mm_manager with Microsoft Visual Studio 2019 or later with CMake, using “Open Folder.”

usage: mm_manager [-vhmq] [-f <filename>] [-i "modem init string"] [-l <logfile>] [-p <pcapfile>] [-a <access_code>] [-k <key_code>] [-n <ncc_number>] [-d <default_table_dir] [-t <term_table_dir>] [-u <port>]
        -a <access_code> - Craft 7-digit access code (default: CRASERV)
        -b <baudrate> - Modem baud rate, in bps.  Defaults to 19200.
        -c - Always download complete table set.
        -d <default_table_dir> - default table directory.
        -e <error_inject_type> - Inject error on SIGBRK.
        -f <filename> modem device or file
        -h this help.
        -i "modem init string" - Modem initialization string.
        -k <key_code> - Desk Terminal 10-digit key card code (default: 4012888888)
        -l <logfile> - log bytes transmitted to and received from the terminal.  Useful for debugging.
        -m use serial modem (specify device with -f)
        -n <Primary NCC Number> [-n <Secondary NCC Number>] - specify primary and optionally secondary NCC number.
        -p <pcapfile> - Save packets in a .pcap file.
        -q - Don't display sign-on banner.
        -r - Rating test mode: Amount charged determined by last 4 digits of dialed number.
        -s - Download only minimum required tables to terminal.
        -t <term_table_dir> - terminal-specific table directory.
        -u <port> - Send packets as UDP to <port>.
        -v verbose (multiple v's increase verbosity.
        -w - don't monitor the modem for carrier loss.

The Nortel Millennium payphones require a standard POTS line, with answer supervision in the form of polarity reversal to indicate that the far end has answered the call. This is required for the Millennium to know when to collect or refund coins. Most SIP ATAs and Cisco Voice Routers can be configured for polarity reversal. If your phone line does not support polarity reversal, an answer supervision detection module is available from Nortel.

If you are using VoIP, make sure to use the u-law PCM codec, disable silence suppression, disable comfort noise generation, and disable echo cancellation. This is required to condition the line for modem operation. You may also need to increase the jitter buffer size, and use a fixed jitter buffer, rather than adaptive.

The Nortel Millennium terminal requires 24VDC at 500mA to supply power to the phone. Only limited functionality is provided for emergency service when this power is not present.

The Millennium Terminal is an advanced payphone that contains a multitude of sensors to determine if the phone is installed and operating properly. This includes sensors to make sure that a coin box is installed, and also a sensor to ensure the coin vault door is in place. If your Millennium does not have a coin box, please obtain one. The coin boxes are standard Western Electric / Northern Electric Single Slot, readily available. In a pinch, the coin box sensor switch can be taped in the closed position. The same goes for the coin vault door. The coin vault door must be in place and locked. If your phone is missing the coin vault lock, as is quite common for these phones purchased on the second-hand market, please obtain the correct lock, or tape the switch closed.

If these sensors are not happy, the phone will alarm, and will go “Out of Service.”

Provisioning the Millennium Terminal is accomplished through the craft access menu on the terminal itself. For this, you will need the terminal’s access code, and a PIN. The default Access Code is 2727378 (CRASERV).

With the upper housing of the phone locked, take the handset off the cradle and replace it. Then key in 2727378 (CRASERV.) You will be prompted for a PIN, use anything above 50000, like 55555. Unlock the upper housing with a T-Key when prompted. You do not need to open the upper housing.

Generate NPA and LCD tables (see below,) unless you want to use the default tables included with mm_manager.

Start mm_manager:

./mm_manager -m -n 18005551234 -f /dev/ttyACM0 -vv -l install.dlog -p install.pcap

Where:

18005551234 should be replaced by the phone number of your Manager (1-15 digits).

`/dev/ttyACM0` should be replaced by your modem device.  For Windows, it will be something like `\\.\COMx` where ‘`x`’ is the COM port number of your modem.

install.dlog is a log file that contains all of the data received and sent by the manager.

install.pcap is a packet capture that can be loaded into [Wireshark](https://github.com/hharte/mm_manager/tree/master/wireshark) for debugging.

Follow the Terminal’s on-screen prompts to install.

Key in this Terminal’s telephone number (10-digits) NPA-NXX-XXXX.

Key in this Terminal’s 10-digit serial number (1234567890 is fine.)

Key in the Manager’s phone number (I use 1-800-555-1234, which I intercept in the Asterisk dialplan and send to the modem connected to the computer running mm_manager.)

Communication with the Nortel Millennium involves sending and receiving tables. Tables are numbered 1 through 155, and contain configuration information sent to the terminal or query / status information received from the terminal. Tables are of fixed size, depending on the type of table.

Each packet response from the Manager includes the Terminal’s phone number, followed by a byte containing the Table ID of the current table being sent by the Manager. Multiple tables may be packed into a single packet (the maximum packet table payload length is 245 bytes.)

In the case of large table download (> 245 bytes) to the Millennium terminal, the table payload is split into 245-byte chunks, but the Table ID is only included in the first packet.

The following are some of the tables used by the Millennium terminal. They should be customized (using a hex editor) for your specific phone. Some parameters (like NCC numbers and Access Code) can be changed via command-line parameters to mm_manager.

Some of the important tables for configuring a Millennium terminal include:

• Page number references are to Millennium Database Design Report MSR 2.1.

Python3 scripts are included to generate NPA and LCD tables automatically, using spreadsheets available from the North American Numbering Plan Administrator. For Canada, spreadsheets are available from the Canadian Numbering Administrator. These scripts require the Python3 libraries: pandas, requests, and xmltodict to be installed.

To generate an NPA table that classifies US and Canadian numbers as domestic:

./generate_npa.py --countries US CANADA

The generate_lcd_lata.py script is used to generate LCD tables for a given NPA-NXX in the United States. LCD tables generated using this script will properly classify Local, Intra-LATA and Inter-LATA calls. This script does not work in Canada as all of Canada is a single LATA.

For example, to generate LCD tables for San Jose, California, USA for a terminal with phone number of (408) 535-XXXX :

./generate_lcd_lata.py --npa=408 --nxx=535

To generate LCD tables for Ottawa, Canada, use generate_lcd_lir.py:

./generate_lcd_lir.py --npa 613 --nxx 562

mm_manager has the ability to support multiple terminals with different provisioning. mm_manager searches for configuration tables as follows:

1. tables/NPANXXXXXX - where NPANXXXXXX is the 10-digit Terminal ID (phone number.)

2. tables/<model-specific-dir> - where <model-specific-dir> is one of:

   multipay, card_only, desk, coin, inmate.

3. tables/default - will be used as a last resort if tables cannot be found in the previous directories.

mm_manager stores the last table update date/time in the terminal-specific directory. This allows for quicker iteration during testing by using "force download" in the terminal’s craft interface. This will download only the table that changed and a few tables that are generated within mm_manager itself.

Two multipay terminals with different Advertising messages, and otherwise configured the same:

tables/4085359990/mm_table_1d.bin - Advertising messages for terminal ID 4085359990

tables/4085359995/mm_table_1d.bin - Advertising messages for terminal ID 4085359995

tables/default/ - All of the default tables are in this directory (including mm_table_1d.bin)

The low-level protocol sent over the modem is a stream of bytes framed within START and END bytes.

*CRC-16 IBM with the 0xA001 polynomial per this site. Includes all bytes including START through the DATA.

FLAG Bits:

Separate sequence numbers are counted for each of tx_seq and rx_seq. ACKs should always be sent with the same sequence as the last received Rx packet. Tx seq is incremented after every successful packet transmission, and reset when the terminal disconnects.

mm_manager can log all bytes sent to or received from a Millennium terminal using the -l <logfile.dlog> option. This can be used to record a transcript of the session, that can be “played back” to mm_manager by specifying this file to the -f option, without supplying -m (modem.) This allows quick iteration when debugging and testing mm_manager, as a real Millennium terminal is not needed.

One useful trick is to parse the transcript with mm_manager, and save it to a file. Then the code can be modified and improved and tested by re-running the transcript through mm_manager and comparing it with the previous run using a tool such as tkdiff.

mm_manager can save all packets sent and received to a packet capture (.pcap) file for viewing in Wireshark using the -p <pcapfile.pcap> option. This .pcap file can be opened with Wireshark, and dissected using the Millennium LUA Dissector Plugin.

In addition, mm_manager can send all packets via UDP to the localhost port 27273 (“CRASE”) so Wireshark can view them in real-time while communicating with a terminal.

If you find a bug, please provide the following information when you report the bug on GitHub:

1. Please make sure you run mm_manager with the -l <filename> option to generate the session transcript of all the data sent to and from the manager. Please attach this file to your bug report.
2. Use mm_manager’s -p <pcapfile.pcap> option to save a packet capture and attach this file to your bug report.
3. Please provide information about the type of Millennium phone you have and what ROM version it’s running. Some of this information is displayed by mm_manager after it connects to the phone.
4. Please provide details about the operating system you are using, what kind of modem you are using, and if you are using a serial modem, what type of serial port you are using (built-in PC serial port, USB serial port, etc.)
5. Please provide details about the phone lines you are using: Are they VoIP, POTS, going through your own PBX, or going over the PSTN? Analog and TDM switches are preferable to VoIP, if at all possible.
6. Steps to reproduce the issue.

1. When installing a Millennium Terminal, the answer supervision test will call the Manager, and disconnect. It may take a few seconds for mm_manager’s modem to detect this condition and go back on-hook. You may want to wait a few seconds after the test completes before proceeding with the installation.
2. Some older firmware versions will fail to install on the first try. They will usually install correctly on a retry.
3. Lots of tables are not well understood. Please help figure more out if you can.

1. Improve modem robustness.
2. Lots of other things, please file bugs as you find them.

Nortel Millennium on Wikipedia

Chaos Computer Club Muenchen

muccc / millennium on GitHub

Description of Millennium Tables

millenniium-panel on GitHub

Armeniki’s Nortel Millennium information on GitHub

Millennium Database Design Report MSR 2.1

Millennium Multi-Pay Terminal Installation, Operation, and Maintenance Guide

Millennium Desk Terminal: Installing and Repairing Terminal Hardware

pyMM