• washi means eagle in the Japanese language. Eagle was taken from double-headed eagle on the flag of Albania.
• sh2 is taken from Albanian State Road 2.
• durana is another name of Tirana-Durres.

Here are some references.

Unix

https://linuxjourney.com/

CLI

I would recommend vimtutor command to learn about how to use vi text editor.

In this issue you can set up WiFi connection and also can change the hostname of your Raspberry Pi so that you can connect to your Raspberry Pi through WiFi. After that, you can connect to your Raspberry Pi from anywhere in the room without connecting your Raspberry Pi and your PC using an Ethernet cable!

sudo raspi-config

Please run the command above.

2 Network Options

Please select 2 Network Options.

N2 Wireless LAN

Then select N2 Wireless LAN.

Select the country in which your Raspberry Pi is to be used

You are probably asked to select your country.

Ok

Select Ok and enter.

Enter your SSID

Please select your SSID.

Enter your WiFi passphrase

Enter your WiFi passphrase then the WiFi connection is set up.

Why you need to change your hostname

You need to have your own hostname when you have more than two RaspberryPi-s in a single WiFi network. The default hostname is raspberrypi.local which you used to log in. There will be a hostname conflict if your team connect several RaspberryPi-s with this default hostname.

2 Network Options

Select 2 Network Options again.

N1 Hostname

Select N1 Hostname.

Ok

Select Ok and press enter.

Enter your new hostname

Enter your new hostname.

You can choose a unique name for your Raspberry Pi. I keep the default 'raspberrypi' for this capacity building text for a less confusion.

For we are now using Remote Desktop Connection (RDC), the use of tmux is less relevant. However, tmux is useful when you are connecting via CLI, and/or you are using a relatively unstable connection.

Because tmux is included in equinox setup, you can simply use tmux as below.

Now you can do multitasking from a single CLI by Ctrl-b Ctrl-c. See the document below for more details.

See also

https://github.com/tmux/tmux

tmux is a terminal multiplexer: it enables a number of terminals to be created, accessed, and controlled from a single screen. tmux may be detached from a screen and continue running in the background, then later reattached.

The figure below explains how we wrap UNVT with additional technologies to assist this capacity building activity.

At the center, UNVT is the geospatial toolkit as explained in #51. We wrap UNVT by VS Code (Visual Studio Code) so that we can more easily handle the Command-Line Interface (CLI) and also we can more easily edit the configuration file.

The whole computing environment is implemented on a single-board computer named Raspberry Pi.

In connecting Raspberry Pi with your PC, we use Remote Desktop Connection (on Windows) or Microsoft Remote Desktop (on macOS).

The configuration files and the vector tile data, and the documentation like this document, are shared using GitHub.

The figure below is a flowchart for this additional capacity building activity.

Where we start

Hardware

Your Personal Computer (PC)

Windows or Mac, with WiFi and an Ethernet port.

Raspberry Pi 4

With an empty microSD card.

Ethernet cable

Internet connection

Through both an Ethernet cable and also WiFi connection. We need an Ethernet cable connection to set-up your Raspberry Pi.

Where we finish

Raspberry Pi hosting Tirana-Durres Vector Tiles.

Tirana-Durres Vector Tiles will constitute an advanced web map for the Tirana-Durres area, Albania.

CONTENTS HERE DOES NOT NECESSARILY FIT WITH YOUR CONFIGURATION.

Here we install a plain Raspberry Pi OS to a microSD card.

Download and install Raspberry Pi Imager on your PC

Access https://www.raspberrypi.org/downloads/ and download Raspberry Pi Imager for your OS of your PC.

Installation to Windows

Double-click imager_x.x.exe to start the installer.

Installation to macOS

Double-click imager_x.x.dmg to start the installer

Drag and drop Raspberry Pi Imager to Applications.

Connect your microSD to your PC

Following is my case using MacBook Pro. How you can connect your microSD to your PC may differ.

Prepare a microSD card

Again, it does not have to be 32GB.

Insert the microSD card to an SD card adapter

Insert the SD card adapter to a memory card reader

Connect the memory card reader to the PC

Install Raspberry Pi OS using the Raspberry Pi Imager

Run Raspberry Pi Imager

CHOOSE OS - Raspberry Pi OS (32-bit)

CHOOSE SD CARD

WRITE

It took about 30 minutes. to finish writing.

Write an empty ssh file on the root directory of the microSD.

Connect the microSD card to your PC again, so that you can see the content of the microSD card.

Create an empty file and rename it ssh (without extension or with extension .txt).

After that, you can eject the microSD card.

This step is no longer necessary because we are using RDP rather than VNC.

sudo raspi-config

5 Interfacing Options

P3 VNC

Yes

Ok

Finish

Complete.

Install Microsoft Remote Desktop from AppStore

Run Microsoft Remote Desktop

Click Add PC

Add PC

Open your Raspberry Pi

Click Raspberry Pi logo -> Programming -> Code - OSS (headmelted)

Inside Code, Terminal -> New Terminal

Click "^" to enlarge the Terminal area.

washi を作るにあたり、Shirley Taylor: Model Business Letters, Emails and Other Business Documents (Seventh Edition) に書かれている次の表現を参考にしています。

引用

英語を母語としていない人が英語でメッセージを書く場合は、以下のような手順を踏んで書くことをお勧めします。

• 言いたいことを、まず母語ではっきりさせる。
• それを英語に翻訳する。
• 正しい英語の書き言葉に直す。
• 読む人に正確に理解してもらえる言葉になっているかを考える。
• 明快に伝えるため、書き直すところがないかどうか、最後にもう一度考えてみる。

• It is hard to see the text via teleconference. Do not rely on the text. Always try to zoom the command text.

You can connect to your Raspberry Pi by using ssh command, a standard command bundled with both Windows and macOS.

ssh [email protected]

Please enter the command above and press enter.

Please enter raspberrypi for a new Raspbian OS installation. This is the default password for a fresh installation.

sudo poweroff

When you need to power-off your Raspberry Pi, you need to run:

$ sudo poweroff

After your are disconnected from your Raspberry Pi, please allow about ten seconds for Raspberry Pi OS to properly shutdown. Then your are safe to unplug your Raspberry Pi.

We may be able to use VNC so that we can use GUI in addition to CLI.

The default desktop environment of Raspberry Pi OS was xfce.

Terminal

The characters were a little bit too small.

LXTerminal

Editor

MousePad

Chromium

Chromium is the default browser.

Firefox

Firefox (Iceweasel) can be installed additionally.

git clone [email protected]:${you}/sh2

equinox: UNVT one-line installer for Raspberry Pi OS

Project repository: https://github.com/unvt/equinox

curl

$ curl -sL https://unvt.github.io/equinox/install.sh | bash -

If you see this, you are successful in installing UNVT on your Raspberry Pi.

Flow

1. Create a secret-public key pair on your Raspberry Pi.
2. Register your public key to your GitHub account

ssh-keygen -t rsa -b 4096 -C "[email protected]"

cat ~/.ssh/id_rsa.pub | xsel --input --clipboard

Open https://github.com/settings/keys

Click "New SSH key"

Test if the key pair works

ssh -T [email protected]

[Advanced] Tips

On Linux, we can use xsel --input --clipboard instead of pbcopy on macOS.

Insert microSD card to Raspberry Pi

Eject SD card adapter, if you used it

If you have just written Raspberry Pi OS to your microSD card in the SD card adapter, first you need to eject your SD card adapter first.

Eject microSD

Then you can eject your microSD card from your SD card adapter.

Insert the microSD card to the slot

Insert the microSD card to the microSD card slot in your Raspberry Pi.

Please make sure you inserted the microSD card to the end of the slot.

Connect your PC and your Raspberry Pi using an Ethernet cable

For a direct-connection, you can connect your PC and your Raspberry Pi using an Ethernet cable.

Connect power to Raspberry Pi

Then you can connect power to your Raspberry Pi. In most cases, we use AC adapter to supply power.

On connecting the power, the system will automatically boot. You need to follow the next steps before you can shut down your Raspberry Pi. Please refrain from simply disconnect power from Raspberry Pi; doing so may damage or even break your Raspberry Pi.

The figure below shows the basic data flow.

• We provide design configuration when producing vector tiles from the source data.
• We provide style configuration when hosting web maps which makes use of vector tiles.

UNVT is to support you developing design and style configurations for your geospatial data, in addition to assisting the data to flow.

make sure you have tiles.mbtiles

First, make sure you are in ~/sh2 and you have tiles.mbtiles. If you do not have tiles.mbtiles, you need to produce it first.

node ../vt-optimizer/index.js -m tiles.mbtiles

y and select 15 (Let's see how z=15 is.)

y and select 10 (Let's see the content of the bucket of the largest tiles.)

y and select a tile

n n n and you are done

FIXME

This part will be completed once the capacity building activity is done.

CONTENTS HERE DOES NOT NECESSARILY FIT WITH YOUR CONFIGURATION.

Raspberry Pi hardware

Raspberry Pi

This is a Raspberry Pi hardware. We use Raspberry Pi 4 Model B at this stage, but previous versions or future versions will also be good.

In our case on the photo above, we added a heatsink.

microSD card

You need to have an empty microSD card as below. The size does not have to be 32GB. 16GB or 8GB should work.

From our experience, it would be a good practice to use an SD card adapter when writing to the microSD card from your PC. Sometimes writing to a microSD card from a PC fails. Below is a microSD card in a SD card adapter.

Case

We have an official Raspberry Pi case as below, with a UNVT sticker on it :-).

AC Adapter

Any good USB-C power adapter should work.

Ethernet cable

A short Ethernet cable will work and will be nice to handle.
FIXME

Optional: SD / microSD adapter

FIXME

Optional: USB-Ethernet port adapter

Assembly into a case

Place the board into the lower part of the case

Place the case lid and push it down until a click

Place a microSD card

And it is assembled

tippecanoe -v

ogr2ogr --version

osmium --version

node -v

gl-style-validate

parse-hocon -v

node ~/vt-optimizer/index.js -h

You may want to scroll up on your console because the message from vt-optimizer is long.

budo --version

git --version

ruby -v

rake download

yarn

rake tiles

• Engineers who want to learn how to produce vector tiles and how to host a web map.
• Engineers with some experience in geospatial information.
• Engineers who are willing to learn about operating a computer. Detailed knowledge of computer science is not necessary.

It is not possible to get packages if the cross-cable connection does not provide connection to the Internet.

This is a tentative solution and will no longer be used.

git clone https://github.com/optgeo/sh2

In this issue, you are creating your own copy of the capacity building material of the phase 1 (sh2).

Create your form of optgeo/sh2

Access https://github.com/optgeo/sh2.

Then click Fork button in the upper left to create your own fork of sh2.

In my case, I am asked to "Where should we fork sh2?" because I belong to several organizations. I clicked hfu.

You will see this while GitHub is creating a fork for you.

After that you have your own fork.

Complete.

This is a non-technical introduction on why we shall jointly produce, host, style, and optimize vector tiles.

About UNVT

1. Geospatial information authorities have been providing geospatial infrastructure even under the geospatial platforms. We have been providing infrastructure even before the digital age.
2. We believe that infrastructure SHOULD NOT be a black-box. Infrastructure SHOULD NOT be a black-box not only for cost-effectiveness but also for interoperability and scalability.
3. We have been operating web maps of geospatial information authority using this method for years. United Nations has invited one of us for two years to share this method within the United Nations.
4. UN Open GIS Initiative provided us an opportunity to start the United Nations Vector Tile Toolkit (UNVT).
5. Let's build advanced web maps together using UNVT.

About this course

1. We are building a web map which is small but true.
2. Here true means ROBUST and SCALABLE.
3. ROBUST web platform often runs on Unix. We can see good examples in cloud services such as Amazon EC2.
4. For this reason, UNVT runs on Unix.
5. Unix can be hard, but let's work on it together.
6. SCALABLE means that it works with huge data, and that it works well with a huge amount of accesses.
7. UNVT can produce global vector tiles using the global OpenStreetMap data within 80 hours using a single MacBook Pro.
8. You will be able to produce vector tiles of a country withing a day or a few days.

rake host

Access http://your-hostname.local:9966 from your PC.

Ctrl-C to stop the server.

Open https://github.com

Input your username, email, and password. Then "Sign up for GitHub".

Verify your account.

Join a free plan.

Follow the survey.

Complete setup.

Your need to verify your email address.

You should have received an email. Click "Verify email address".

You will see the following screen. You may want to click "Skip this for now".

Then you will see the home page of your GitHub account. That's it.

It was too hard for many participants to use vi(m).

First of all, we connect Raspberry Pi with your PC directly so that we can set-up the Raspberry Pi without major information security concern.

We connect Raspbery Pi and the PC with an Ethernet cable as in the figure below.

Otherwise you can also connect keyboard and monitor to the Raspberry Pi.

This is https://github.com/unvt/washi/issues/1.

You may want to bookmark here because we often come back here to move around.

Introduction

1. #3 Scope
2. #4 Intended Readers
3. #2 Executive Summary FIXME
4. #5 Introduction
5. #6 Where we start and where we finish
6. #50 Data flow
7. #7 Capacity building flowchart
8. #51 Contents of UNVT
9. #43 Structure of the capacity building environment
10. #16 What we are developing in phase 1 (sh2)
11. What we are developing in phase 2 (durana)

Raspberry Pi set-up

Hardware check

1. #8 Raspberry Pi hardware

Raspberry Pi OS Installation to a microSD card

1. #9 Installation of Raspberry Pi OS into a microSD card

Under direct connection

1. #37 What do we mean by direct connection
2. #10 Boot your Raspberry Pi
3. #32 Open console on your PC
4. #11 Log-in to your Raspberry Pi / poweroff
5. #12 Set up WiFi and change hostname
6. #13 Change password
7. #40 Enable VNC

Under Wi-Fi connection

1. #39 What do we mean by Wi-Fi connection
2. #14 Log in via Wi-Fi
3. #30 Update Raspberri Pi OS
4. #15 [Advanced] What is Unix? What is CLI?

UNVT set-up

1. #17 Install equinox - UNVT online installer for Raspberry Pi OS
2. #18 Check installed UNVT tools
3. #20 [Advanced] Use tmux
4. #19 Create a GitHub user account if you do not have one
5. #45 [Windows] Connect to your Raspberry Pi using Remote Desktop Connection
6. #46 [macOS] Connect to your Raspberry Pi using Remote Desktop Connection

Phase 1 (sh2)

make your clone of sh2

1. #33 Fork optgeo/sh2
2. #34 Enable GitHub Pages for ${you}/sh2
3. #42 Register your SSH key to GitHub
4. #48 Configure GitHub global variables
5. #47 Clone ${you}/sh2 into your Raspberry Pi

produce

1. #23 Produce vector tiles

style

1. #22 Compile the style

host

1. #31 Host the site

optimize

1. #41 Run vt-optimizer

Phase 2 (durana)

understand the content of the source data

produce

style

host

optimize

Appendix

1. #52 poweroff
2. #26 Tips for tutors
3. #44 What are in the code names?
4. #38 Comments

git config --global user.email "[email protected]"

git config --global user.name "Your Name"

cd sh2

nano hocon/_root.conf

Or vi hocon/_root.conf if you are familiar with vi.

Change site_root to http://your-hostname.local:9966.

Before the edit

After the edit, when your hostname is (still) raspberrypi.

rake style

This compiles the style file from the files in hocon directory.

• Covid, this is a response from UNVT. Washi is (almost) landing. 🔥
• Washi is online, remote, asynchronous, but still physical.

Let's change the password of your pi account before you log in via WiFi.

1 Change User Password

Ok

Enter your new passwords twice

Ok

Finish

Use tab key until turns to red. Then enter.

sudo reboot

Then disconnect the Ethernet cable, to make sure you are connecting via WiFi next time.

ssh pi@<your hostname>.local

The screenshot above keeps using raspberrypi as the hostname for convenience in the capacity building process.

Now you are back to your Raspberry Pi via WiFi.

Ping somewhere in the Internet to make sure you have a connection to the Internet from your Raspbery Pi

ping www.google.com for example. Press Ctrl-C to stop pinging.

Here we explain the main contents of UNVT. Please refer to unvt/equinox/README.md for more details, including support tools and libraries.

Produce

1. Tippecanoe: Builds vector tilesets from large (or small) collections of GeoJSON, Geobuf, or CSV features.
2. GDAL: Geospatial Data Abstraction Library - Utility programs
3. Osmium Tool: Command line tool for working with OpenStreetMap data

Host

1. budo: A browserify server for rapid prototyping

Style

1. hocon-parser: a lightweight and extensible JavaScript parser for HOCON (Human-Optimized Config Object Notation)
2. gl-style-validate: A Mapbox GL style utility that validate the given style JSON and print errors to stdout

Optimize

1. Vector Tile optimizer: A small NodeJS cli tool to inspect and optimize Mapbox Vector Tiles files

• Add issues based on the internal 2020-09-10 session.
• Complete sh2 part of washi.
• Work on durana (phase 2).

Scope of washi

This capacity-building document titled washi describes the process to produce vector tiles from openly available geospatial information and host a web map.

We also describe how we can modify the style for the vector tiles.

We also describe how we can calculate indicators for the size of vector tiles and how we can optimize the size of vector tiles.

The web site happens to work. But the vector tiles and its style-related files are source from the original. We will revisit this issue once we explored UNVT on Raspberry Pi.

Before you can connect to your Raspberry Pi using Remote Desktop Connection (or Microsoft Remote Desktop), we need to connect to your Raspberry Pi using Command-Line Interface (CLI). We use CLI to enable remote desktop connection to your Raspberry Pi. In the coming several issues, we explain how we can do it.

macOS

We can use Terminal.app. For example, Command+Space terminal then Enter to start Terminal.app.

Windows

We can use the Command Prompt. Enter cmd on your search then select the Command Prompt.

For both security, functionality, and performance reasons, it is always a good idea to keep your Rapberri Pi OS up to date. Instead of Windows Update, your are going to follow the steps below.

sudo apt update

sudo apt upgrade

In the phase 1, we are developing a web map shown below. For a live example, please see https://optgeo.github.io/sh2/.