Contiki-BBS Files

Contiki BBS 0.3.x quick startup guide
=====================================


Preamble:
---------
Contiki BBS is a tiny, little and text based bulletin board system (BBS) for the Commodore 64 homecomputer and a compatible ethernet cartridge (e.g. TFE, RRnet, 64NIC+). It can be accessed through a standard telnet connection and currently provides basic BBS functionality (select from multiple boards, post/read messages, page sysop).

This guide is intended to be used as a quick startup guide. It will cover the compilation and installation of Contiki BBS from source on a Linux system. This guide (c) 2018 by Niels Haedecke.

If you just want to run the software without compiling it (e.g. you have downloaded the .d64 disk image), skip to section 10.) of this document.

As of version 0.3.0, Contiki BBS can also be installed on and run from SD2IEC devices (e.g. in its own directory on the sdcard). 
The software now also supports multiple disk drive setups and thus allows you to store board/message data and user data on different drives (e.g. "9" for board data and "10" for user data).


Prerequisites:
--------------
The following tools are required for a successful compile and installation of Contiki BBS:

* GNU Make

* The cc65 (6502) C compiler

* Git revision control tool

* VICE Emulator installed (needed due to the included c1541 commandline program)

* A second machine (physical or VM) on the same network running a VICE Emulator with ethernet emulation enabled through libnet & libpcap (UNIX/Linux) or WinPCAP (Windows).

NOTE: On Linux you may have to use libnet0-1.0.2a from its original source code archives in order to get ethernet emulation working with VICE, since the libnet packages provided by recent Linux distros (e.g. libnet1) won't work (VICE will not be able to use the 'write_link_layer' function).

Alternatively, a Commodore 64 with a Commodore 1541/1570/1571/1581 disk drive and any compatible ethernet cartridge (e.g. TFE, RRnet, 64NIC+) will work as well. You just have to transfer the D64 image to a 5.25" / 3.5"   disk. Search the web for 'opencbm' for information on how to accomplish this.

The Contiki BBS sourcecode repository contains a folder named "d64" where the latest version of Contiki BBS can be found on  a D64 disk image to run the program in an emulator or write it back to a real 5.25" floppy disk. This folder now also contains a zipfile with all files and binaries required to run Contki BBS on a SD2IEC device (e.g. from within a folder on the sdcard). Just unzip the contents of the zipfile into a folder of your choice on your SD2IDE sdcard. 


How to build Contiki BBS from scratch
------------------------------------
This guide assumes your are using Linux as your development platform. Shell commands needed to be entered will be displayed with the well known UNIX commandline prompt at the beginning. E.g. the following example will show the 'ls' command being issued:

  $ ls


1.) Create a folder where you are going to keep your Contiki and Contiki BBS sources.

  $ mkdir src

2.) Go to your new source folder

  $ cd src

3.) Get sources from Contiki OS git repo:

  $ git clone https://github.com/contiki-os/contiki.git

4.) Get Contiki BBS sources:

  $ git clone git://git.code.sf.net/p/contiki-bbs/code contiki-bbs-code

5.) Go to the directory containing the Contiki BBS sources

  $ cd contiki-bbs-code/platform/c64/

6.) Build the binaries

  $ make

7.) Seperately build the Contiki BBS setup program

  $ make -f Makefile.bbs-setup

Voila! You have now built your own Contiki BBS binaries. Now, how do we get these on a D64 disk image?

8.) Still in the source directory, create a D64 disk image (make sure you have set your PATH to point to the c1541 commandline program)

  $ c1541 -format "contikibbs,30" ctkbbs.d64

9.) Write the neccessary files to your new D64 disk image. Depending on what ethernet hardware you are using, you may skip writing *.eth drivers to the image that you don't need in order to save disk space. TFE and RRnet devices require the cs8900a.eth driver to be present.

  $ c1541 ctkbbs.d64 -write contiki-bbs.c64 
  $ c1541 ctkbbs.d64 -write bbs-setup.c64
  $ c1541 ctkbbs.d64 -write default.cfg contiki.cfg,s
  $ c1541 ctkbbs.d64 -write cs8900a.eth cs8900a.eth,s 
  $ c1541 ctkbbs.d64 -write lan91c96.eth lan91c96.eth,s
  $ c1541 ctkbbs.d64 -write w5100.eth w5100.eth,s
  $ c1541 ctkbbs.d64 -write login.txt login.txt,s
  $ c1541 ctkbbs.d64 -write logout.txt logout.txt,s
  $ c1541 ctkbbs.d64 -write menu.txt menu.txt,s

Congratulations, you're done! Now you have a working D64 disk image containing Contiki BBS, ready to run in an emulator or to be written back to a real 1541 Disk in order to run it on a real Commodore 64. 

Okay, so this is how to build and prepare Contiki BBS for use on a Commodore 64. Now let's go through the setup process of Contiki BBS itself. So startup your VICE emulator and attach your ctkbbs.d64 disk image to drive 8. You are now at the Commodore 64 BASIC prompt.

10.) Load the Contiki BBS setup program

     LOAD "BBS-SETUP.C64",8,1

11.) Start it ...

     RUN
   

Contiki BBS configuration
------------------------

The main menu will appear
   
     *** Contiki BBS 0.3.0 setup ***

     1...BBS base setup
     2...BBS board setup
     3...TCP/IP setup
     4...User editor
     q...Quit


1...BBS base setup

The output below shows an example configuration for the BBS base setup. Here you set up your disk drives, BBS prompt and timeout values. If you have more than one disk drive you can now store all board/message data files and user data files on seperate disk drives. The only requirement is that drive 8 is used as the boot disk drive. In the example below we use a second disk drive (device number 9) for storing the board/message data files and a third disk drive (device number 10) to store the user data files. Of course, if you only have one floppy disk drive, the board and userdb drive number will be the same as the boot drive number: 8.

     * BBS base setup
     
     Enter boot drive #: 8
     Enter board drive #: 9
     Enter userdb drive #: 10

     Enter BBS prompt: BBS>

     Login timeout (seconds): 120
     Session timeout (seconds): 360

Once you have answered the above questions, you will be asked to confirm your input:

     Base data correct (y/n)? 

Enter 'y' if everything is okay or 'n' to re-enter the BBS base configuration values.


2...BBS board setup

Boards are an early predecessor of today's internet forums. It's the place people write their postings. Below you will see an example output showing the creation of one board. Please be patient, as the creation of the data files may take some time (especially when you run Contiki BBS on real hardware). You may add as many boards as you like as long as you have the disk space available.

    * BBS board editor

    (a)add, (l)ist or (q)uit :a
     
     Board #1
     Board name : lounge
     Access lvl.: 10

     Board data correct (y/n)? y

You may use the (l)ist option to print a list of all boards available. Following the example above, you will see the "lounge" board being listed.

    * BBS board editor

    (a)add, (l)ist or (q)uit :l

    ID#|Acc|Boardname 
    ---+---+----------------------------  
    001|010|lounge

    Press key


3...TCP/IP setup

This configuration step will configure your Commodore 64 ethernet hardware, including IP addresses, driver and memory location of the cartridge. The example below shows a typical LAN setup using a RRnet or 64NIC+ cartridge at memory address $de08. Both cartridges use the cs8900a.eth driver. ETH64 network devices may use the lan91c96.eth driver along with its appropriate memory address. 

NOTE: do not prefix your memory address with the '$' sign. E.g. if your ethernet cartridge resides at $de08 just enter 'de08' when being prompted for the memory address.

    * BBS network setup

    Host IP             : 192.168.200.64
    Netmask             : 255.255.255.0
    Gateway IP          : 192.168.200.1
    DNS IP              : 192.168.200.1
    Mem addr. ($de08)   : de08
    Driver (cs8900a.eth): cs8900a.eth
    Write to drive # (8): 8
    
    Network data correct (y/n)? y


4...User editor

The user editor is currently very limited. The only thing it does is add users to its database, nothing else. At the moment Contiki BBS does not care about usernames, it does not even distinguish between different users. This will change in future versions of the program. As for now a single user will be all we need. In the example below we just provide a simple 'guest' user with the password 'guest', so we can log in into our new BBS.

    * BBS user editor
    
    (a)add, (s)how, (l)ist or (q)uit :a

    User #  : 1
    Username: guest
    Password: guest
    Access lvl.: 10
  
    User data correct (y/n)? y

You have now set up your Contiki BBS system and are ready to run. Quit the BBS setup program from the main menu by entering 'q'.


Running Contiki BBS
------------------
Once you have set up your Contiki BBS, reset your machine or emulator and load the Contiki BBS server from the Commodore 64 BASIC prompt.

1.) Load and run Contiki BBS
    LOAD "CONTIKI-BBS.C64",8,1

2.) Start it...
    RUN

3.) Now use a second machine to connect to the IP address of your Commodore 64 (the Host IP address you entered in Step 3 of the BBS setup program) via telnet.

    $ telnet 192.168.200.64

                                        
          W e l c o m e   t o :         
                                        
           -=-=-=-=-=-=-=-=-=-          
                                        
            >> Contiki BBS <<           
                                        
    Contiki BBS  V0.3.0 (C) 2009-2018   
                   by                   
               N. Haedecke              
                                        

Contiki BBS 0.3.0

login: _

You are now connected to your Contiki BBS system and can log in using the username and password you entered in Step 4 of the BBS setup program. Well done, have fun!