==== Introduction ====
The ircDDB-Network is a amateur radio network for exchanging routing information. There are several amateur radio systems that are able to reach individual ham radio operators, due to the use of unique callsigns around the world. These systems need to be fed with the latest data where ham radio operators are reachable. For example, ICOM introduced the first radios with digital voice (D-Star) on the amateur radio market, which are capable of addressing QSO partners directly (call sign routing). The ircDDB-Network provides a solution to distribute the essential routing information across its entire network.

==== Motivation ====
In our opinion, from the users point of view, the really new exciting thing about digital voice on ham radio is the ability to address QSO partners directly (call sign routing). It is a shame that ICOM's software implementation to exchange D-Star routing information doesn't work satisfactorily. The current situation makes call sign routing an annoying game of chance, due to delayed synchronisation intervals of routing information, as well as several bugs that we found in the ICOM software. There is even a lack of transparency for the user to discover routing problems. Both problems must be resolved in order to become accepted by the users. Our plan is to provide a solution for these problems.

Moreover, we like to collaborate with other developers around the world. To make this possible, we will publish our documentation and source code under open licenses. Despite the D-Star RF-protocol, the network-protocol introduced by ICOM has never been published. Our network protocol will be well documented, allowing developers to integrate the protocol into their software. We want to make it clear that operating a large network doesn't conflict with the idea of Open Source. The most prominent example is the internet, which is based on a complete open protocol suite. We want to provide a smooth path to allow D-Star to move forward without interfering with existing networks.

==== Description ====
=== The ircDDB-Network ===
The idea is to reduce the needed data to be exchanged for a working call sign routing to a minimum. This set of data contains for D-Star one table with "Call sign + Module" and one table with "Gateway + Internet-IP-address". The ircDDB-Network provides this data to all its clients making them able to route digital voice to the correct destination.

The exchange of data is done using the Internet Relay Chat technology (IRC). A network of distributed IRC servers can handle thousands of users without any problem.

Every gateway taking part on this network needs software being able to speak the IRC protocol with our IRC-Servers. For the US-Trust gateways we provide an IRC client. We call it the //ircDDB-Add-On//. For standalone systems we recommend to use the //G4KLX ircDDB Gateway// (Demo video: http://www.youtube.com/watch?v=k1yCCUvFVzA).

=== The ircDDB-Add-On ===
Our //Add-On// software allows D-Star gateways being part of the US-Trust network while taking part on the //ircDDB-Network// without any interference. The //Add-On// ensures that the US-Trust network will __**not**__ be disturbed in any way and makes only __**local**__ changes on the system which is using the //Add-On//.

We decided to implement the IRC client in Java using RFC2812. The client is currently used to receive routing updates from the ircDDB-Network. To send routing updates, the dstarmonitor (DSM) is used on Icom based gateways and sends it's updates to a postgres server which interacts with the IRC servers. We decided to choose Java and DSM because these components are already mandatory on the US-Trust-Network and we try to add as less new software as we can.

Injected routing updates to the ircDDB-network are scanned for bad values on the server side __**before**__ they are distributed on the IRC-channel to the clients. The client on the gateways will only send __small__ updates to the __**local**__ "dstar_global" database on a __few__ fields (see documentation) if there is new routing information. It will __**not**__ add any new entries which could cause "dsipsvd" (closed software daemon) to send wrong data to other trustservers. You can see this piece of software as an application interface for developers which takes care, that the other network will not be disturbed.

The client is Open Source and can be reviewed to make sure that nothing can go wrong.

Our work has been reviewed by the US-Trust-Network-Maintainers. The //"ircDDB"-Add-On// is accepted and may be installed on any Gateway of the US-Trust-network.

=== The G4KLX ircDDB Gateway ===
The ircDDB Team recommends to use the G4KLX software with homebrew solutions.

There is another gateway sofware from KI4LKF available in the Download section.

==== Goals ====
  * The ircDDB-Network is an intermediate step to a real open D-Star network without having the problem of a loss of connectivity. It combines the need for a stable network (US-Trust-Network) and other developments which can move D-Star forward. It should be accepted as an //Add-On//-application on all existing networks.
  * The ircDDB-Network provides a robust interface, which can't break the network, even if developers make something wrong. It should encourage more people to give D-Star development on the network side a try.
  * We want to get a high penetration allowing self-made D-Star gateways to communicate with many systems.
  * The ircDDB-Network is designed as a distributed network allowing it to run several servers in different countries. We want to find reliable partners to setup more servers around the globe.
  * We want to get a worldwide D-Star network with at least a functional call sign routing with a roaming time below five seconds.

==== Features ====
=== ircDDB-Network ===
  * Supports all current call sign routing enabled D-Star Networks
  * Provides the call sign routing feature to developers (might be useful for D-Star-Hotspots or DV-Dongle-Users)
  * Allows to attach gateways without US-Trust connectivity making the ircDDB-Network their default
  * Realtime roaming: Available for users between gateways and different modules
  * Dynamic IP support: Realtime update of gateways IP-address on DSL reconnect
  * Access control: Password protected logins for the gateway clients
  * Load balancing: Supports thousands of gateways/users (using multiple network servers)
  * Scalability: The network uses proven technology on distributed servers.
  * Visualisation: Provides MH-data to Visualisation Servers
  * Visualisation: Provide URCALL, RPT1, RPT2, MYCALL fields to Visualisation Servers

=== ircDDB-Add-On ===
  * Runs on US-Trust gateways
  * Does __**not**__ conflict with the US-Trust-Network
  * Uses only components which are mandatory on the US-Trust-Network
  * Will be installed as root, but will run as user "ircDDB" with user privilege
  * Easy Install Script available
Might be implemented if requested:
  * Intercept bad database entries which will cause the DNS-server not being able to start (e.g. pc_hostname = 'dg8ngn-' in "sync_mng")
  * Cleanup the local database from expired entries
  * Securing the network by blocking access to UDP port 40000 for non ircDDB-Network-members

==== Documentation ====
  * [[projects:dstar:ircddb:addondoku|Add-On Documentation]]
  * {{:projects:dstar:ircddb:ircddb-addon.pdf|ircDDB addon - data flow}}

==== Solutions ====
=== Overview ===
{{:projects:dstar:ircddb:ircddb-network.png?800|Digital Voice Data Flow in the D-Star Network}}

**Please keep in mind that only the "ircDDB - standalone version" needs no user registration.**

__To communicate through a gateway being part of the US-Trust network both participating users need to be registered on the US-Trust network.__

=== ircDDB - multihomed version (US-Trust) ===
The ircDDB - multihomed version is designed for US-Trust gateways running the ICOM G2 software. See http://www.dstarusers.org for more information.

mandatory components:
  * __ICOM software__ (dsgwd, dsipsvd, postgres, httpd) **or** __G4ULF software__
  * Java / DStarMonitor
  * ircDDB (multihomed version)
repeater:
  * ICOM controller **or** DV-Adapter (G4ULF)
possible add-ons:
  * dplus
  * dextra_ng (under investigation & testing until approved)
data flow diagram (click twice for maximum zoom level):

{{:projects:dstar:ircddb:us-trust-linux-icom.png?200|Data flow example US-Trust}}

setup instructions for new installations and updates:
  * http://download.ircddb.net/ircddb-icom/install/ircDDB_Installation_Icom-en.pdf

=== ircDDB - standalone version ===
The ircDDB - standalone version is designed for gateways which don't need or can not be connected with the US-Trust network.

The G4KLX gateway software and the G4KLX repeater software can run on localhost or on another machine within the LAN.

data flow diagram (click twice for maximum zoom level):

{{:projects:dstar:ircddb:ircddb-g4klx.png?200|Data flow example G4KLX}}

== Linux ==
gateway software:
  * G4KLX ircDDB Gateway
repeater software / hardware:
  * G4KLX "D-Star Repeater" (Soundcard) **or** G4KLX "GMSK Repeater" (USB DV Adapter) **or** ICOM Controller "RP2C"

__**[[projects:dstar:ircddb:ircddb-lin-g4klx|Setup instructions]]**__

== Windows ==
gateway software:
  * G4KLX ircDDB Gateway
repeater software / hardware:
  * G4KLX "D-Star Repeater" (Soundcard) **or** G4KLX "GMSK Repeater" (USB DV Adapter) **or** ICOM Controller "RP2C"

__**[[projects:dstar:ircddb:ircddb-win-g4klx|Setup instructions]]**__

==== Network policy ====
=== Testing network ===
There is a testing network from Armando, IK2XYP (ircDDB-Italia Team), available. If you want to test the ircDDB gateway software with your personal call sign instead of a repeater call sign you can use this network. The server is listening on the following machine: server1-ik2xyp.free-dstar.org TCP port 9007.

=== Gateway Callsigns ===
Due to a technical limitation a user call sign can't be used as a gateway call sign. Therefore we need to take care which call signs we can register with the ircDDB network. Please help us to define simple rules for each country (press edit):

^Country        ^Syntax                             ^Regulations            ^Online Check    ^
|Argentina      |FIXME                              |                       |                |
|Australia      |**VK#R$**                          |                       |[[http://web.acma.gov.au/pls/radcom/register_search.main_page|Register of Radiocommunications Licences]]                |
|Austria        |**OE#X$**                          |                       |                |
|Belgium        |**ON0$**                           |                       |                |
|Brazil         |PY#$,PP#$,PQ2$,PQ8$,PR7$,PR8$,PS7$,PS8$,PT#$,PU#$,PV8$,PW8$   |                       |[[http://sistemas.anatel.gov.br/easp/novo/consultaindicativo/tela.asp?sisqsmodulo=11265]]                |
|Bulgaria       |//LZ0$//                           |                       |                |
|Canada         |**VE#$, VA#$**                     |                       |[[http://apc-cap.ic.gc.ca/pls/apc_anon/query_amat_cs$.startup|Amateur Radio Operator Certificates]]                |
|Croatia        |**9A0D$**                          |                       |                |
|Czech Republic |**OK0$**                           |                       |                |
|Denmark        |**OZ#RE$**, **OZ#DS$**, **OZ#DH$** |                       |[[http://frekvensregister.erst.dk/Search/Search.aspx]]                |
|France         |**F#Z$**                           |[[http://draf.asso.fr/index.php?post/2011/12/15/Nouvelle-R%C3%A9glementation-%3A-Question-R%C3%A9ponses|New French rules to come in October 2012]]                     |[[http://amatpres.anfr.fr|station répétitrices]] |
|Finland        |FIXME                              |                       |                |
|Germany        |**DB0$**, **DF0$**, **DM0$**, **DO0$**    |[[http://www.bundesnetzagentur.de/cae/servlet/contentblob/38232/publicationFile/2597/Vfg122005ge228ndertdurcId1833pdf.pdf|Vfg Nr. 34/2005]] |[[http://ans.bundesnetzagentur.de/Amateurfunk/Rufzeichen.aspx|Bundesnetzagentur Amateurfunk-Rufzeichen]]                |
|Greece         |//SV#$//, //SW#$//, //SZ#$//                 |                       |                |
|Italy          |**IR#$**                           |                       |                |
|Japan          |**7J#Y$**, **7K#Y$**, **7L#Y$**, **7M#Y$**, **7N#Y$**, **8J#$**, **JA#Y$**, **JD1Y$**, **JE#Y$**, **JF#Y$**, **JG#Y$**, **JH#Y$**, **JI#Y$**, **JJ#Y$**, **JK#Y$**, **JL#Y$**, **JM#Y$**, **JN#Y$**, **JO#Y$**, **JP#Y$**, **JQ#Y$**, **JR#Y$**, **JS#Y$**, **7J#Z$**, **7K#Z$**, **7L#Z$**, **7M#Z$**, **7N#Z$**, **JA#Z$**, **JD1Z$**, **JE#Z$**, **JF#Z$**, **JG#Z$**, **JH#Z$**, **JI#Z$**, **JJ#Z$**, **JK#Z$**, **JL#Z$**, **JM#Z$**, **JN#Z$**, **JO#Z$**, **JP#Z$**, **JQ#Z$**, **JR#Z$**, **JS#Z$** |       |       |
|Netherlands    |**PI1$**                           |                       |[[http://www.agentschaptelecom.nl/onderwerpen/radiozendamateurs/Onbemand+frequentiegebruik|Onbemand frequentiegebruik]] [[http://www.agentschaptelecom.nl/binaries/content/assets/agentschaptelecom/Radiozendamateurs/onbemande-amateurstations-20120216.xls|Table]]                |
|New Zealand    |**ZL#$**                           |                       |https://www.rsm.govt.nz/smart-web/smart/page/-smart/domain/licence/SearchCertificateAndIdentifierPage.wdk                |
|Norway         |**LD#$**                           |http://www.npt.no/ikbViewer/Content/125168/forskrift-om-amatoerlisens-eng.pdf |                |
|Poland         |**SR#$**                           |                       |http://download.pzk.org.pl/public/przemienniki/Lista_przemiennikow_nr61-30.06.2010.pdf                |
|Portugal       |**CQ0D$**, **CQ1D$**, **CQ2D$**    |                       |                |
|Romania        |**YO#$**                           |                       |                |
|Slovenia       |//S55$//                           |                       |                |
|Spain          |**ED#$**                           | [[http://www.boe.es/boe/dias/2006/06/09/pdfs/A22051-22068.pdf|Art.28]] & [[http://www.boe.es/boe/dias/2006/10/31/pdfs/A37758-37771.pdf|Art.13.3]]  | |
|South Africa   |**ZS#$**, **ZU9$**                 |                       |                |
|Sweden         |All SM ITU Prefixes allowed        |                       |[[http://www.ssa.se/sm-callbook]]                |
|Switzerland    |**HB9$**                           |                       |                |
|United Kingdom |**GB3$**, **GB7$**, **MB6$**       |                       |[[http://www.dcc.rsgb.org/showgmsk.asp]] |
|United States  |n.a.                               |                       |[[http://www.arrl.org/fcc/search|ARRL License Data Search]] [[http://wireless2.fcc.gov/UlsApp/UlsSearch/searchLicense.jsp|FCC License Data Search]]|

callsign = 4 to 6 characters, # = 1 number, $ = 1, 2 or 3 letters, n.a. = not available

Best guess ircDDB Team: //cursive// <- to be replaced by the community. Please **edit** or give feedback by email. Tnx

=== User Callsigns ===

<code>
^(([1-9][A-Z])|([A-Z][0-9])|([A-Z][A-Z][0-9]))[0-9A-Z]*[A-Z][ ]*[ A-RT-Z]$
</code>

The user callsign must have 3 to 7 characters.
==== Joining ====
=== Gateway Users ===
Tune to your next ircDDB enabled D-Star repeater and push PTT to make your call sign visible to the network. You are now reachable by call sign routing. Each time you change to another D-Star repeater or another RF module of the same D-Star repeater, you need to push PTT again. This information is saved within the network. You don't need to push PTT again.

Please make sure you're call sign and terminal is registered with the US-Trust network if you want to be reachable from US-trust based repeaters.

=== Gateway Operators ===
Despite the current existing networks the ircDDB-Network provides real access control by the use of usernames and passwords to authenticate gateways during the log-in process. We prepared a Gateway Registration section on our mainpage: http://www.ircddb.net. Please make sure you use not a personal call sign for your gateway (see Network Policy).

If you want to test the ircDDB gateway software with your personal call sign you can use the testing network (see Network Policy).

=== Network Operators ===
There is currently no gateway available to exchange routing information between IRC based networks and other type of networks. This might change in future.

==== Download ====
Presentation:
  *{{:projects:dstar:ircddb:hamradio_2010-ircddb.pdf|Hamradio Friedrichshafen ircDDB 2010(german)}}
  *{{:projects:dstar:ircddb:hamradio2012-ircddb.pdf|Hamradio Friedrichshafen ircDDB 2012 - Status und Neuigkeiten (german)}}
  *{{:projects:dstar:ircddb:g4klx_ircddb_gateway_and_repeater.pdf|Hamradio Friedrichshafen ircDDB 2012 - G4KLX ircDDBGateway & Repeater (english)}}

Software:
  * http://download.ircddb.net (US-Trust Addon, Support: DL1BFF, DG8NGN, DL5DI)
  * http://db0fhn.efi.fh-nuernberg.de/~g4klx/ircDDB%20Gateway (G4KLX ircDDBGateway, Support: DL1BFF, DG8NGN, DL5DI, G4KLX)
  * http://ircddb.sourceforge.net (KI4LKF g2_ircddb Gateway, Support: KI4LKF, W4WWM, IW7DZR, VA3UV)

==== Support =====
  * IRC channel #ircddb on Freenode (http://freenode.net) IRC-network
    * Webchat: http://webchat.freenode.net/?nick=ircddb.&channels=ircddb&uio=d4
  * Mailing List:
    * Yahoo Group: http://groups.yahoo.com/group/ircddb (ircDDB network related)
    * Yahoo Group: http://groups.yahoo.com/group/ircDDBGateway (G4KLX ircDDBGateway related)
    * Yahoo Group: http://groups.yahoo.com/group/ircddb-italia (ircDDB network related in Italian language)
  * E-Mail:
    * Jann Traschewski, DG8NGN: <jann@gmx.de> (Network Manager, Documentation, Publication, Testing)
    * Hans-Juergen Barthen, DL5DI: <dl5di@gmx.de> (Network Manager, Packaging, Visualisation)
    * Michael Dirska, DL1BFF: <dl1bff@mdx.de> (Network Manager, Development)
    * Jonathan Naylor, G4KLX: <naylorjs@yahoo.com> (G4KLX ircDDBGateway software)
    * Scott Lawson, KI4LKF: <ham44865@yahoo.com> (KI4LKF g2_ircddb Gateway software)
    * Torsten Schultze, DG1HT <info@dg1ht.de> (DVRPTR Repeater software)
    * 
==== Sourcecode & Development ====
== Papers ==
  * http://www.jarl.com/d-star/STD4_3C.pdf
  * http://www.jarl.com/d-star/shogen.pdf
  * http://d-star.dyndns.org/misc/shogen_4_2_8.pdf
  * http://www.aprs-is.net/downloads/DStar/CHAPTER5.pdf
  * http://www.aprs-is.net/downloads/DStar/DSTARUncovered.pdf
  * http://www.aprs-is.net/downloads/DStar/D-PRS.pdf
  * {{:projects:dstar:ircddb:dstar_dv_frame3_en.pdf|dstar_dv_frame3_en.pdf}}
  * http://www.qsl.net/kb9mwr/projects/voip/dstar/Slow%20Data.pdf

== Check comments in the source code ==
  * DL1BFF: http://github.com/dl1bff
  * G4KLX: http://db0fhn.efi.fh-nuernberg.de/~g4klx/ircDDB%20Gateway
  * KI4LKF: http://ircddb.sourceforge.net
  * DG1HT / DJ0ABR: http://tech.groups.yahoo.com/group/DVRPTR/files/
==== Visualisation ====
  * The network status can be found here: http://status.ircddb.net
  * The live view can be found here: http://ircddb.net/live.htm
  * Activation of visualisation: http://ircddb.net/live-vis.html
  * Can you hear me now? http://www.dstardb.com


==== FAQ ====
  * __**Q**__: Why do we still need to be a registered user even when we do communicate between gateways taking part on the //ircDDB-Network//?\\ __**A**__: We can't add new users to gateways running the ICOM software since the "dsipsvd"-process would send bad data to the Trust-Server of the network. So each time you will communicate from/to a gateway being part of the US-Trust-Network you need to ensure you and your QSO partner are registered on that network.
  * __**Q**__: Why can't I register on the ircDDB network with my personal call sign?\\ __**A**__: We need to stay compatible with the ICOM G2 architecture. A repeater call sign can not be used as a user. See http://dsyncg2.dstarusers.org/JoiningTheNetwork3.pdf as a reference.
  * __**Q**__: How can I then **login to DPlus** with my gateway?\\ __**A**__: DPlus connectivity only works for US trust gateways and registered users. This is for a basic authentication and security as long as nothing better is in place. However, there are methods for non-US-trust gateways. In ircDDBGateway you may enter a registered callsign for DPlus login, which is not the gateway callsign. There is a field in the DPlus configuration mask for this callsign. The gateway will log in to the network as a dongle user using that callsign.
  * __**Q**__: Why is my callsign shown in **red color** in ircDDB-live and the lists?\\ __**A**__: Red color always means that the transmission was addressed from or to a callsign at a US trust gateway, where this callsign is not registered. It may occur in the source or destination field. \\  Unfortunately the databases of the gateways are not all in sync, so you might see the callsign in red on one US trust gateway, in black on another. In that case one of the admins needs to resync the database with the trust server. A description how to do it can be found on the US trust info page. \\ The registration information is supplied by the US trust gateway itself, it is not stored anywhere in the ircDDB system, we only make that information visible. On ircDDB-only gateways all callsigns and '*' will always be shown in black, there is no user registration. However, you should be registered in the US trust network to be able to use all gateways. The ircDDB gateway addon on Icom-G2 will not bypass the US trust registration.
  * __**Q**__: Why is my callsign not shown, only a group of '*' instead ?\\ __**A**__: For privacy reasons you need to activate VISibility in the system once. \\ Every time that you access ircDDB-live, the lastheard table or the log you may find a blue hint bar on your screen. Please klick on the link in that bar to get more information on the **'VIS-feature'**. \\
  * __**Q**__: Why can't I use **'tactical callsigns'** or any other names of my choice for starnet destinations?\\ __**A**__: The ircDDB network does not allow to use callsigns which do not meet the ITU specifications. \\ ircDDB does not use any user registration, there is no database for that. Basic address verification is based on pattern match against the international rules. \\ 'Tactical callsigns' would make an additional database for that kind of destinations necessary, which needs to be implemented to all network components. The data would have to be maintained, updated and distributed. We want to keep the administration effort as low as possible. \\ The pattern "STN####" have been implemented in addition to the known international callsign specs. This may be used for internet-only destinations, which have no need for a legal callsign. Other destination addresses are not accepted by the network. 
  * __**Q**__: Which STN-adresses are already in use?\\ __**A**__: A **list of STN-adresses** can be found here: http://db0fhn.efi.fh-nuernberg.de/doku.php?id=projects:dstar:starnet \\ Please add new addresses there and help to keep it unique.
  * __**Q**__: How does the **registration** process for a new gateways work? How long does it take?\\ __**A**__: Fill out the registration form on our website http://regsrv.ircddb.net.\\ After submitting the registration information make sure that the page confirms the registration and does not return any error messages at the top of the page. \\ Please use an email address which accepts the automatically generated emails from the registration system! Do not use an address which works with white-lists or make sure that 'register  at  ircddb.net' will be accepted! \\ The registration system immediatly sends out a notification to local responsible admins and the ircDDB team. Currently we have more than 10 admins in different countries who do the approvals locally.\\ Our goal is to approve a request within 24 hours. If all information are supplied correct this is done by a mouse click, in special cases it may take longer.\\ We all have to do it in our free fime, every day. However, if you did not get any email within 2-3 days you should contact us. \\ After the approval you will get an email with the login credentials for the gateway and the admin. The gateway callsign will also appear in the lists on the ircddb website in grey color. \\ Without activation it will stay there for 60 days. After 30 days it will be marked, after 60 it will disappear. It will return on activation.
  * __**Q**__: Where can I check my **ircDDB login password** ?\\ __**A**__: Only in the email notification from the registration server. Nowhere else!\\ Ask your bank for a lost PIN, you won't get it.\\ Please make sure to store the login credentials at a secure place. We do not store passwords in human readable form. The database and the login servers only keep a crypted hash. \\ However, we have the chance to search copies of the notification emails in really urgent cases, but this is an effort which costs us a lot of time. 
  * __**Q**__: How can I **delete a gateway** from the network ?\\ __**A**__: Contact the admin team, you can not delete a gateway yourself. This is the same like with US trust gateways. \\ Registered ircDDB gateways can not really be deleted but the admin team can make it invisible.\\ We would very much prefer if the request would come from the person who registered the gateway, just to prevent that an unauthorized person asks to delete gateways from others.\\ 6 months after the last login to the network gateways will be set to invisable status automatically.\\ An invisible gateway will become visible again as soon as it logs in to the ircDDB network next time.