Skip to content

Commit e11d5d9

Browse files
a8jana8jan
committed
documentation update
1 parent 902c16f commit e11d5d9

File tree

4 files changed

+224
-16
lines changed

4 files changed

+224
-16
lines changed

‎Install.md‎

Lines changed: 25 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -1,52 +1,63 @@
11
# Installation
22

3-
FujiNet-PC Launcher is bundled together with Fujinet-PC, NetSIO hub and custom device file for Altirra into one FujiNet-PC bundle.
3+
FujiNet-PC Launcher is bundled together with Fujinet-PC binaries, NetSIO hub and custom device file for Altirra into one FujiNet-PC **bundle**. Python runtime and necessary libraries are included too.
44

55
## Windows
66

77
### 1) Get the bundle file and unzip it
88

9-
![1-unzip](img/1-unzip.png)
9+
[Download](https://github.com/a8jan/fujinet-pc-launcher/releases/latest) the **bundle**.
10+
Extract the files. Create or use the directory of your choice for extracted files, e.g. `C:\Atari\FujiNet`.
1011

11-
Create / use the directory of your choice for extracted files, e.g. `FujiNet`.
12+
![1-unzip](img/1-unzip.png)
1213

1314
### 2) Create shortcut to launcher.exe
1415

15-
![2-shortcut](img/2-shortcut.png)
16+
For your convenience create a shortcut to `launcher.exe` and move it to Desktop (or some other place of your choice). Shortcut can be given some nicer name, e.g `FujiNet`.
1617

17-
For your convenience create a shortcut to `launcher.exe` and move it to Desktop (or some other place of your choice). Shortcut can be given some nicer name.
18+
![2-shortcut](img/2-shortcut.png)
1819

1920
### 3) Start FujiNet-PC Launcher
2021

22+
Use the shortcut to run FujiNet-PC Launcher.
23+
24+
When started for the first time, the OS may ask for security confirmation.
25+
2126
![3-start](img/3-start.png)
2227

23-
When started for the first time, Operating System may ask for security confirmation.
28+
The Launcher will run FujiNet-PC and NetSIO hub programs in background. The leftmost LED (white) indicates that FujiNet-PC is running. Next LED (blue one) indicates that NetSIO hub is running. The LED on the right (amber) will be active when the SIO communication occurs.
29+
30+
Similar to real FujiNet use buttons for some basic actions. Right click empty area to open pop-up menu with few more options.
2431

2532
### 4) Connect Altirra with FujiNet
2633

27-
![4-atdevice](img/4-atdevice.png)
34+
Finally, the two pieces, Altirra and FujiNet, must be connected. For this custom device have to be plugged in to Altirra.
2835

29-
In Altirra, navigate to menu `System` > `Configure System...` In `Configure System` window navigate to `Peripherals` > `Devices` and `Add` custom device. Use `...` button to navigate to `emulator\Altirra-4.0x` and select `netsio.atdevice` file. Once added, the device will be listed as `NetSIO - SIO over network` custom device.
36+
In Altirra, navigate to menu `System` > `Configure System...` In `Configure System` window navigate to `Peripherals` > `Devices` and `Add` custom device. Use `...` button to navigate to `emulator\Altirra` and select `netsio.atdevice` file. Once added, the device will be listed as `NetSIO - SIO over network` custom device.
3037

31-
### 5) Disable Fast boot acceleration
38+
![4-atdevice](img/4-atdevice.png)
3239

33-
![5-fast-boot](img/5-fast-boot.png)
40+
### 5) Disable Fast boot acceleration
3441

3542
To allow emulated Atari boot from from FujiNet via custom device the Fast boot acceleration feature must be disabled.
3643

37-
### 6) Detach Altirra's D1: drive
44+
![5-fast-boot](img/5-fast-boot.png)
3845

39-
![6-disk-drives](img/6-disk-drives.png)
46+
### 6) Detach Altirra's D1: drive
4047

4148
To boot from FujiNet (acting as D1:), similar to real Atari, there cannot be multiple D1: drives attached to SIO bus. Detach other D1: if any.
4249

50+
![6-disk-drives](img/6-disk-drives.png)
51+
4352
### 7) Boot emulated Atari from FujiNet
4453

54+
To simulate power cycle of both Atari and FujiNet one can use `Cold Reset`. To "power cycle" Atari only use `Cold Reset (Computer Only)`.
55+
4556
![7-boot](img/7-boot.png)
4657

47-
To simulate power cycle of both Atari and FujiNet one can use `Cold Reset`. To "power cycle" Atari only use `Cold Reset (Computer Only)`.
58+
## Video ;-)
4859

49-
### Video with above steps
60+
Video with above steps:
5061

5162
[![FujiNet-PC bundle](img/fujinet-pc-launcher.png)](https://youtu.be/7sAMfXyewjE "FujiNet-PC bundle")
5263

‎README.md‎

Lines changed: 8 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -26,6 +26,12 @@ Note: Wine can be used to run Altirra on macOS and Linux.
2626
* parameters to control SD folder, config file, network ports
2727
* allows multiple Altirra-FujiNet instances to run simultaneously
2828

29-
## Installation
29+
## Download
3030

31-
Check the instructions [here](Install.md) to get it running (currently only Windows, rest will follow).
31+
**FujiNet-PC bundle** is available in [Releases](https://github.com/a8jan/fujinet-pc-launcher/releases) section. The bundle contains: FujiNet-PC binaries, Launcher GUI, NetSIO hub and NetSIO custom device for Altirra. Python with necessary libraries is part of the bundle. All in one bundle is currently available only for Windows.
32+
33+
Check for setup instructions [here](Install.md).
34+
35+
An alternative to all in one bundle is a variant which includes **scripts** only, also available in [Releases](https://github.com/a8jan/fujinet-pc-launcher/releases) section. The scripts package contains: Launcher GUI and NetSIO hub Python modules and NetSIO custom device for Altirra. It does not contain any binaries. To run scripts Python 3 with necessary libraries must be installed on the system and FujiNet-PC binaries ([downloaded](https://github.com/FujiNetWIFI/fujinet-pc/releases/latest) or [built](https://github.com/FujiNetWIFI/fujinet-pc#build-instructions)) have to be placed into `fujinet-pc` directory.
36+
37+
Check how to run FujiNet-PC Launcher or NetSIO hub as Python scripts [here](ScriptsUsage.md).

‎ScriptsUsage.md‎

Lines changed: 189 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,189 @@
1+
# FujiNet-PC scripts
2+
3+
The scripts package contains Launcher GUI and NetSIO hub Python modules and NetSIO custom device for Altirra. It does not contain any binaries. To run scripts Python 3 with necessary libraries must be installed on the system and FujiNet-PC binaries ([downloaded](https://github.com/FujiNetWIFI/fujinet-pc/releases) or [built](https://github.com/FujiNetWIFI/fujinet-pc#build-instructions)) have to be placed into `fujinet-pc` directory.
4+
5+
## Linux, macOS, Window
6+
7+
### Download and extract the files
8+
9+
[Download](https://github.com/a8jan/fujinet-pc-launcher/releases/latest) the **scripts** package and extract the files.
10+
11+
There are four subdirectories inside:
12+
13+
* `emulator` contains custom device for Altirra
14+
* `fujinet-pc` is placeholder for FujiNet-PC binary
15+
* `launcher` is Python module containing FujiNet-PC Launcher
16+
* `netsiohub` is Python module containing NetSIO hub
17+
18+
### Python
19+
20+
Python 3 is required to run Launcher and NetSIO hub.
21+
22+
Check if Python version 3.x is installed:
23+
24+
```sh
25+
$ python -V
26+
Python 3.10.4
27+
```
28+
29+
if command is not found or version 2.x.y is reported by `python` command try to use `python3` command instead:
30+
31+
```sh
32+
$ python3 -V
33+
Python 3.10.4
34+
```
35+
36+
On Ubuntu it is possible to enable Python 3 via `python` command by installing `python-is-python3` package:
37+
```sh
38+
$ sudo apt install python-is-python3
39+
```
40+
41+
Linux distros are likely shipped with some version of Python installed by default or at least available as ready to install package. For other systems if Python 3 is not installed yet it can be downloaded and installed from [https://www.python.org/](https://www.python.org/).
42+
43+
For recent Windows versions Python is available from Microsoft Store. Version 3.9 or 3.10 should work fine. It can be also installed using `winget`:
44+
45+
```sh
46+
$ winget install -i Python.Python.3.9
47+
```
48+
49+
Similar on macOS, if using package manager, e.g. homebrew, Python can be installed with it:
50+
51+
```sh
52+
$ brew install python3
53+
```
54+
55+
### NetSIO hub
56+
57+
Skip this step if you plan to use Launcher.
58+
59+
If not interested into Launcher GUI the NetSIO hub can be started manually. Enter the scripts directory - the one with `emulator`, `fujinet-pc`, `launcher` and `netsiohub` subdirectories (DO NOT enter `netsiohub` subdirectory).
60+
61+
Start NetSIO hub:
62+
63+
```sh
64+
$ python -m netsiohub # or python3 -m netsiohub
65+
```
66+
67+
NetSIO hub command line options:
68+
69+
```
70+
usage: netsiohub [-h] [--netsio-port NETSIO_PORT] [-d] [--port PORT] [-v]
71+
72+
Connects NetSIO protocol (SIO over UDP) talking peripherals with NetSIO Altirra custom device (localhost TCP).
73+
74+
options:
75+
-h, --help show this help message and exit
76+
--netsio-port NETSIO_PORT
77+
Change UDP port used by NetSIO peripherals (default 9997)
78+
-d, --debug Print debug output
79+
--port PORT Change TCP port used by Altirra NetSIO custom device (default 9996)
80+
-v, --verbose Log emulation device commands
81+
```
82+
83+
### FujiNet-PC
84+
85+
To allow the Launcher to control (start/stop and monitor) FujiNet-PC program the directory `fujinet-pc` must be populated with FujiNet-PC. Copy here the content of `build/dist` if it was built manually. Pre-build binaries for selected systems can be [downloaded](https://github.com/FujiNetWIFI/fujinet-pc/releases/latest) and files extracted here.
86+
87+
The content of `fujinet-pc` directory should look like this:
88+
89+
```sh
90+
% ls -l fujinet-pc
91+
drwx------ 3 a8jan staff 96 Aug 24 12:26 SD
92+
drwx------ 11 a8jan staff 352 Aug 24 12:26 data
93+
-rwx------ 1 a8jan staff 535 Aug 24 12:26 fnconfig.ini
94+
-rwx------ 1 a8jan staff 6189712 Aug 24 12:26 fujinet
95+
-rwx------ 1 a8jan staff 284 Aug 24 12:26 run-fujinet
96+
```
97+
On Windows there will be additional DLL files together with `fujinet.exe`
98+
99+
If you do not plan to use Launcher to start/stop FujiNet-PC the FujiNet-PC can be started manually. Enter `fujinet-pc` directory and start FujiNet-PC with `./run-fujinet` on Linux and Mac, use `run-fujinet.bat` on Windows.
100+
101+
FujiNet-PC command line options:
102+
103+
```
104+
Usage: fujinet [-V] [-u URL] [-c config_file] [-s SD_directory]
105+
```
106+
107+
### Launcher
108+
109+
FujiNet-PC Launcher uses [wxPython](https://wxpython.org/) library for its GUI. Check if it is installed:
110+
111+
```sh
112+
$ python -c "import wx; print(wx.version())"
113+
4.1.2a1.dev5310+af8cca51 msw (phoenix) wxWidgets 3.1.5
114+
```
115+
116+
If instead of version information the `ModuleNotFoundError: No module named 'wx` is printed then wxPython must be installed. Easiest way is to install additional software for Python is to use **pip** - package installer for Python.
117+
118+
Note: Similar story to `python` vs `python3` is with `pip` vs `pip3` or even `python -m pip` vs `python3 -m pip`. Use the right pip command to manage Python 3 packages on your system (check Python version with `pip -V` or `pip3 -V`).
119+
120+
To install wxPython using `pip` (or `pip3`):
121+
122+
```sh
123+
$ pip install -U wxPython # or pip3 install -U wxPython
124+
```
125+
126+
This should work fine on macOS and Windows. Unfortunately, not on Linux - details [here](https://wxpython.org/pages/downloads/).
127+
128+
There are two solutions to problem with wxPython installation on Linux:
129+
130+
a) Use package provided by Linux distribution
131+
132+
E.g on Ubuntu (quite old version):
133+
```sh
134+
$ sudo apt install python3-wxgtk4.0
135+
```
136+
137+
b) Use Linux distribution [specific pip package](https://extras.wxpython.org/wxPython4/extras/linux/gtk3/)
138+
139+
E.g on Ubuntu 22.04:
140+
```sh
141+
$ pip install -U -f https://extras.wxpython.org/wxPython4/extras/linux/gtk3/ubuntu-22.04/ wxPython
142+
```
143+
144+
Now, with Python and wxPython installed, the Launcher program can be started. Enter the scripts directory - the one with `emulator`, `fujinet-pc`, `launcher` and `netsiohub` subdirectories (DO NOT enter `launcher` subdirectory).
145+
146+
Start FujiNet-PC Launcher:
147+
148+
```sh
149+
$ python -m launcher # or python3 -m launcher
150+
```
151+
152+
If all is good the FujiNet shaped window will open and FujiNet-PC and NetSIO hub will be started in background.
153+
154+
155+
FujiNet-PC Launcher command line options:
156+
157+
```
158+
usage: launcher [-h] [-l LABEL] [-g GUI_SCALE] [-t] [-u URL] [-c FNCONFIG] [-s SD] [-p PORT] [-r NETSIO_PORT]
159+
[-i INSTANCE] [-v] [-d] [-V]
160+
161+
This launcher program controls FujiNet-PC and NetSIO hub
162+
163+
options:
164+
-h, --help show this help message and exit
165+
-l LABEL, --label LABEL
166+
Launcher label
167+
-g GUI_SCALE, --gui-scale GUI_SCALE
168+
GUI scale
169+
-t, --top-window Stay on top window
170+
-u URL, --url URL FujiNet web interface ([0.0.0.0][:8000])
171+
-c FNCONFIG, --fnconfig FNCONFIG
172+
Path to FujiNet configuration file (fnconfig.ini)
173+
-s SD, --sd SD Path to SD directory (SD)
174+
-p PORT, --port PORT TCP port used by Altirra NetSIO custom device (9996)
175+
-r NETSIO_PORT, --netsio-port NETSIO_PORT
176+
UDP port used by NetSIO peripherals (9997)
177+
-i INSTANCE, --instance INSTANCE
178+
FujiNet instance ID
179+
-v, --verbose Log emulation device commands
180+
-d, --debug Print debug output
181+
-V, --version Print program version and exit
182+
```
183+
184+
185+
### Custom device for Altirra emulator
186+
187+
Device file for Altirra emulator `netsio.atdevice` is located in `emulator/Altirra` directory.
188+
189+
To connect Altirra with FujiNet follow the instructions [here](Install.md#4-connect-altirra-with-fujinet).

‎requirements.txt‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,2 @@
1+
wxpython
2+
requests

0 commit comments

Comments
 (0)