chore: updated docs

Author: maxgallup

docs/00-guide.md

@@ -1,17 +1,17 @@
 # Setup Guide
 
-The following describes how to setup a single Rover. Note, that the automated steps can be run in parallel.
+The following describes how to setup a single Rover. Note, that it can be applied to any number of rovers in parallel to speed up the automation process.
 
-First, download the "Debix-SD-V3.6-20240410.img" from google drive and flash the image onto an SD card with tools like [Balena Etcher](https://etcher.balena.io/). Then, put the SD card into the Rover, attach an ethernet cable to it and turn it on. After some time it should have booted the stock linux Ubuntu that it comes with and it should have an assigned IP address. Find this IP address by going into the Router's settings and finding the new device that has just connected. Let's say we are setting up Rover 7, and find that it is connected with the IP address `192.168.0.183`. Then, we must have the following entry in the `hosts.ini` file:
+First, download the "Debix-SD-V3.6-20240410.img" from the google drive or the debix website and flash the image onto an SD card with tools like [Balena Etcher](https://etcher.balena.io/). Then, put the SD card into the Rover, attach an ethernet cable to it and turn it on. After some time it should have booted the stock linux Ubuntu that it comes with and it should have an assigned IP address. Find this IP address by going into the Router's settings and finding the new device that has just connected. Let's say we are setting up Rover 7, and find that it is connected with the IP address `192.168.0.183`. Then, we must have the following entry in the `hosts.ini` file:
 
 ``` ini
 [rover07]
-192.168.0.183 ansible_user=debix custom_address=192.168.0.107 rover_id=7 rover_name=turing rover_password=a6caecf790605da0544a71b29fe91f21a44a0ec2d5934d77a06831a7d0afc2fa rover_password_plain=debix servo_trim=0.05
+192.168.0.183 ansible_user=debix rover_id=7 rover_name=turing rover_password=a6caecf790605da0544a71b29fe91f21a44a0ec2d5934d77a06831a7d0afc2fa rover_password_plain=debix servo_trim=0.05
 ```
 
-The first IP address at the beginning of the line is the address that Ansible will use to connect to the device. The `custom_address` field is the address that the Rover will have at the end of a successful run. This means that after the first run (given that it was successful), we need to change `192.168.0.183` to `192.168.0.107`.
+The first IP address at the beginning of the line is the address that Ansible will use to connect to the device (the one assigned by the router `...183`). Since we use mDNS to connect to the rovers using their hostnames, we don't *need* to remember IP addresses like `192.168.0.183`, we can just remember `rover07.local`. If however there are mDNS connection issues, then we must resort to connecting with the IP directly. In theory, after a successful run of the automation the Rover will be available at the `rover07.local` address which means we could change the IP address at the start of the line from `192.168.0.183` -> `rover07.local`. This is recommended since the router might assign it a different IP address some day.
 
-Once this edit has been made, run the following command to check which Rovers are reachable from Ansible:
+Then, we can use the following command to make sure we can access all of the rovers.
 
 ``` bash
 make ping

hosts.ini

@@ -9,94 +9,84 @@
 
 ; --------------------------------------------------------------------
 ; List of all debixes in the network, first IP is their currently
-; reachable address, while custom_address is the IP that it will be 
-; set to when running `tasks/network.yaml`. After the very first
-; run, the IP address needs to be updated to what is in the 
-; custom_address field. The rover_id should be the same as the last
-; `(octet of the custom_address) - 100`. The rover_name should be the
-; name of a famous computer scientist, and the rover_password currently
-; is set to the hash of 'debix'.
-;
-; As an example: the following line will ensure that the debix that is
-; currently at addess 1.2.3.4 will at the end of the script request
-; a static IP address of 5.6.7.8. It will change the hostname to 
-; 'roverexample' and always connect with the user 'debix'.
-; 
-; [roverexample]
-; rover01.local ansible_user=debix custom_address=192.168.0.101 rover_id=1 rover_name=Dijkstra rover_password=a6caecf790605da0544a71b29fe91f21a44a0ec2d5934d77a06831a7d0afc2fa rover_password_plain=debix
+; reachable address as assigned by the router, however after a successful
+; run of the setup, they will be reachable via "hostname.local" using mDNS.
+; So for example Rover 07 would be addressable via rover07.local
+;The rover_name should be the name of a famous computer scientist, and 
+; the rover_password currently is set to the hash of 'debix'.
 ;
 ; --------------------------------------------------------------------
 
 
 [roverbuilder]
-192.168.0.184 ansible_user=debix custom_address=192.168.0.184 rover_id=0 rover_name=RoverBuilder rover_password=a6caecf790605da0544a71b29fe91f21a44a0ec2d5934d77a06831a7d0afc2fa rover_password_plain=debix
+192.168.0.184 ansible_user=debix rover_id=0 rover_name=RoverBuilder rover_password=a6caecf790605da0544a71b29fe91f21a44a0ec2d5934d77a06831a7d0afc2fa rover_password_plain=debix
 
 [rover01]
-rover01.local ansible_user=debix custom_address=192.168.0.101 rover_id=1 rover_name=Dijkstra rover_password=a6caecf790605da0544a71b29fe91f21a44a0ec2d5934d77a06831a7d0afc2fa rover_password_plain=debix
+rover01.local ansible_user=debix rover_id=1 rover_name=Dijkstra rover_password=a6caecf790605da0544a71b29fe91f21a44a0ec2d5934d77a06831a7d0afc2fa rover_password_plain=debix
 
 [rover02]
-rover02.local ansible_user=debix custom_address=192.168.0.102 rover_id=2 rover_name=Martin rover_password=a6caecf790605da0544a71b29fe91f21a44a0ec2d5934d77a06831a7d0afc2fa rover_password_plain=debix 
+rover02.local ansible_user=debix rover_id=2 rover_name=Martin rover_password=a6caecf790605da0544a71b29fe91f21a44a0ec2d5934d77a06831a7d0afc2fa rover_password_plain=debix 
 
 [rover03]
-rover03.local ansible_user=debix custom_address=192.168.0.103 rover_id=3 rover_name=Torvalds rover_password=a6caecf790605da0544a71b29fe91f21a44a0ec2d5934d77a06831a7d0afc2fa rover_password_plain=debix 
+rover03.local ansible_user=debix rover_id=3 rover_name=Torvalds rover_password=a6caecf790605da0544a71b29fe91f21a44a0ec2d5934d77a06831a7d0afc2fa rover_password_plain=debix 
 
 [rover04]
-rover04.local ansible_user=debix custom_address=192.168.0.104 rover_id=4 rover_name=Thompson rover_password=a6caecf790605da0544a71b29fe91f21a44a0ec2d5934d77a06831a7d0afc2fa  
+rover04.local ansible_user=debix rover_id=4 rover_name=Thompson rover_password=a6caecf790605da0544a71b29fe91f21a44a0ec2d5934d77a06831a7d0afc2fa  
 
 [rover05]
-rover05.local ansible_user=debix custom_address=192.168.0.105 rover_id=5 rover_name=Lovelace rover_password=a6caecf790605da0544a71b29fe91f21a44a0ec2d5934d77a06831a7d0afc2fa rover_password_plain=debix 
+rover05.local ansible_user=debix rover_id=5 rover_name=Lovelace rover_password=a6caecf790605da0544a71b29fe91f21a44a0ec2d5934d77a06831a7d0afc2fa rover_password_plain=debix 
 
 [rover06]
-rover06.local ansible_user=debix custom_address=192.168.0.106 rover_id=6 rover_name=Stroustrup rover_password=a6caecf790605da0544a71b29fe91f21a44a0ec2d5934d77a06831a7d0afc2fa rover_password_plain=debix 
+rover06.local ansible_user=debix rover_id=6 rover_name=Stroustrup rover_password=a6caecf790605da0544a71b29fe91f21a44a0ec2d5934d77a06831a7d0afc2fa rover_password_plain=debix 
 
 [rover07]
-rover07.local ansible_user=debix custom_address=192.168.0.107 rover_id=7 rover_name=Gosling rover_password=a6caecf790605da0544a71b29fe91f21a44a0ec2d5934d77a06831a7d0afc2fa rover_password_plain=debix 
+rover07.local ansible_user=debix rover_id=7 rover_name=Gosling rover_password=a6caecf790605da0544a71b29fe91f21a44a0ec2d5934d77a06831a7d0afc2fa rover_password_plain=debix 
 
 [rover08]
-rover08.local ansible_user=debix custom_address=192.168.0.108 rover_id=8 rover_name=Turing rover_password=a6caecf790605da0544a71b29fe91f21a44a0ec2d5934d77a06831a7d0afc2fa rover_password_plain=debix 
+rover08.local ansible_user=debix rover_id=8 rover_name=Turing rover_password=a6caecf790605da0544a71b29fe91f21a44a0ec2d5934d77a06831a7d0afc2fa rover_password_plain=debix 
 
 [rover09]
-rover09.local ansible_user=debix custom_address=192.168.0.109 rover_id=9 rover_name=Hoare rover_password=a6caecf790605da0544a71b29fe91f21a44a0ec2d5934d77a06831a7d0afc2fa rover_password_plain=debix 
+rover09.local ansible_user=debix rover_id=9 rover_name=Hoare rover_password=a6caecf790605da0544a71b29fe91f21a44a0ec2d5934d77a06831a7d0afc2fa rover_password_plain=debix 
 
 [rover10]
-rover10.local ansible_user=debix custom_address=192.168.0.110 rover_id=10 rover_name=Rossum rover_password=a6caecf790605da0544a71b29fe91f21a44a0ec2d5934d77a06831a7d0afc2fa rover_password_plain=debix 
+rover10.local ansible_user=debix rover_id=10 rover_name=Rossum rover_password=a6caecf790605da0544a71b29fe91f21a44a0ec2d5934d77a06831a7d0afc2fa rover_password_plain=debix 
 
 ; [rover11]
 ; CAN'T FIND ROVER11
 
 [rover12]
-rover12.local ansible_user=debix custom_address=192.168.0.112 rover_id=12 rover_name=Tanenbaum rover_password=a6caecf790605da0544a71b29fe91f21a44a0ec2d5934d77a06831a7d0afc2fa rover_password_plain=debix 
+rover12.local ansible_user=debix rover_id=12 rover_name=Tanenbaum rover_password=a6caecf790605da0544a71b29fe91f21a44a0ec2d5934d77a06831a7d0afc2fa rover_password_plain=debix 
 
 [rover13]
-rover13.local ansible_user=debix custom_address=192.168.0.113 rover_id=13 rover_name=VonNeumann rover_password=a6caecf790605da0544a71b29fe91f21a44a0ec2d5934d77a06831a7d0afc2fa rover_password_plain=debix 
+rover13.local ansible_user=debix rover_id=13 rover_name=VonNeumann rover_password=a6caecf790605da0544a71b29fe91f21a44a0ec2d5934d77a06831a7d0afc2fa rover_password_plain=debix 
 
 [rover14]
-rover14.local ansible_user=debix custom_address=192.168.0.114 rover_id=14 rover_name=Shannon rover_password=a6caecf790605da0544a71b29fe91f21a44a0ec2d5934d77a06831a7d0afc2fa rover_password_plain=debix 
+rover14.local ansible_user=debix rover_id=14 rover_name=Shannon rover_password=a6caecf790605da0544a71b29fe91f21a44a0ec2d5934d77a06831a7d0afc2fa rover_password_plain=debix 
 
 [rover15]
-rover15.local ansible_user=debix custom_address=192.168.0.115 rover_id=15 rover_name=Hopper rover_password=a6caecf790605da0544a71b29fe91f21a44a0ec2d5934d77a06831a7d0afc2fa rover_password_plain=debix 
+rover15.local ansible_user=debix rover_id=15 rover_name=Hopper rover_password=a6caecf790605da0544a71b29fe91f21a44a0ec2d5934d77a06831a7d0afc2fa rover_password_plain=debix 
 
 [rover16]
-rover16.local ansible_user=debix custom_address=192.168.0.116 rover_id=16 rover_name=Knuth rover_password=a6caecf790605da0544a71b29fe91f21a44a0ec2d5934d77a06831a7d0afc2fa rover_password_plain=debix 
+rover16.local ansible_user=debix rover_id=16 rover_name=Knuth rover_password=a6caecf790605da0544a71b29fe91f21a44a0ec2d5934d77a06831a7d0afc2fa rover_password_plain=debix 
 
 [rover17]
-rover17.local ansible_user=debix custom_address=192.168.0.117 rover_id=17 rover_name=Minsky rover_password=a6caecf790605da0544a71b29fe91f21a44a0ec2d5934d77a06831a7d0afc2fa rover_password_plain=debix 
+rover17.local ansible_user=debix rover_id=17 rover_name=Minsky rover_password=a6caecf790605da0544a71b29fe91f21a44a0ec2d5934d77a06831a7d0afc2fa rover_password_plain=debix 
 
 [rover18]
-rover18.local ansible_user=debix custom_address=192.168.0.118 rover_id=18 rover_name=Kernighan rover_password=a6caecf790605da0544a71b29fe91f21a44a0ec2d5934d77a06831a7d0afc2fa rover_password_plain=debix 
+rover18.local ansible_user=debix rover_id=18 rover_name=Kernighan rover_password=a6caecf790605da0544a71b29fe91f21a44a0ec2d5934d77a06831a7d0afc2fa rover_password_plain=debix 
 
 [rover19]
-rover19.local ansible_user=debix custom_address=192.168.0.119 rover_id=19 rover_name=Primeagen rover_password=a6caecf790605da0544a71b29fe91f21a44a0ec2d5934d77a06831a7d0afc2fa rover_password_plain=debix
+rover19.local ansible_user=debix rover_id=19 rover_name=Primeagen rover_password=a6caecf790605da0544a71b29fe91f21a44a0ec2d5934d77a06831a7d0afc2fa rover_password_plain=debix
 
 [rover20]
-rover20.local ansible_user=debix custom_address=192.168.0.120 rover_id=20 rover_name=Matsumoto rover_password=a6caecf790605da0544a71b29fe91f21a44a0ec2d5934d77a06831a7d0afc2fa rover_password_plain=debix
+rover20.local ansible_user=debix rover_id=20 rover_name=Matsumoto rover_password=a6caecf790605da0544a71b29fe91f21a44a0ec2d5934d77a06831a7d0afc2fa rover_password_plain=debix
 
 
 
 
+; This simply defines which rovers to address when running `make`
 
 [fleet:children]
-
 roverbuilder
 rover01
 rover02

tasks/network.yaml

@@ -1,36 +1,7 @@
 ---
-
-# - name: Set netplan configuration file
-#   tags: network
-#   become: true
-#   copy:
-#     dest: /etc/netplan/01-netcfg.yaml
-#     content: |
-#       network:
-#         version: 2
-#         renderer: networkd
-#         ethernets:
-#           ens33:
-#             dhcp4: no
-#             addresses:
-#               - {{ custom_address }}/24
-#             nameservers:
-#               addresses: [192.168.0.1, 1.1.1.1]
-#         wifis:
-#           wlan0:
-#             dhcp4: no
-#             dhcp6: no
-#             access-points:
-#               "aselabs":
-#                 password: "{{ wifi_password }}"
-#             addresses:
-#               - "{{ custom_address }}/24"
-#             routes:
-#               - to: default
-#                 via: 192.168.0.1
-#             nameservers:
-#               addresses: [192.168.0.1, 1.1.1.1]
-
+ 
+# Using mDNS for addressing the Rovers via hostname
+# so no longer using "custom_address" field from hosts.ini file
 
 - name: Make sure old networking files don't exist
   tags: network