# Ichigojam 永續指南入門 - 把微電腦當作你的主力機吧!
你的下一台電腦何必是一台電腦?他其實可以是塊微控制器!
> 🚧 撰寫中,資料尚未完整
[TOC]
> 從 2022-02-07 開始撰寫
## 0.1 前言
我是 [IT. Wolf](https://ljcu.cc),來自台灣 🇹🇼 的資工系學士生。我很喜歡**可以獨立運作、永續的電腦**,這讓我有種孤島感。於是我遠到 科技的巴加拉格群島 —— 日本 搜集類似的案例,在到島不久我就搜集到Ichigojam,這是我國中時就聽說過的電腦,夢寐已求的電腦,現在就出現在我眼前,我廢話不多說買了好幾塊回來玩。
**簡單來說我希望你單透過這個指南就可以使用ichigojam作為主力機器**。這個指南會有大方向的在解決 Ichigojam 的永續問題與探討其永續的方式,所以會與其他 Ichigojam 指南大不相同。。如果你偏好一個較為「正常」的指南,建議您前往:https://15jamrecipe.jimdofree.com/ 會有更多的收穫。
此指南目前只針對台灣所撰寫,許多可行性考量目前也只針對台灣當前環境做的評估。如果你是其他地區的ichigojam愛好者,歡迎加入共筆。
> 如果你有任何更多的想法,歡迎在留言提出你的看法。
## 0.2 簡介
Ichigojam是一個很神奇的MCU based的小電腦,他是繼ZX Spectrum、Commondore 64、Apple II 後在千禧世代出現的BASIC電腦,也是眾多電腦中,從設計開始就從不仰賴網路和外部更新的電腦系統。
Ichigo在日文名為「草莓」,所以Ichigojam又是「草莓醬」。你可以搭配他們的 IchigoPanCake「草莓鬆餅」或者試試看他們的「IchigoLatte(草莓拿鐵)」或「IchigoMaple(蜂糖草莓)」。**但是這些SBC都只在日本販售,不對外。(我也是花了好一番時間才找到許多網路資源,但大部分只有日文,而且零散在不同網站的各處)**。 因為如此,才有了這篇文件!
## 0.3 參考資源列表(外部連結)
以下是所有Ichigojam的參考資源彙整,或許你也可以在這裡快速瀏覽不同的原生資源網站:
**官方站點**
* **Ichigojam 官方網站**:https://ichigojam.net
* Ichigojam **Pancake** 官方網站:http://pancake.shizentai.jp
* Ichigo**Latte** 官方網站:http://ichigolatte.shizentai.jp
**第三方站點**
* **IchigoJam** 粉絲團: https://www.facebook.com/groups/ichigojamfan
* Ichigolatte 官方粉絲團:https://www.facebook.com/groups/568222796651326/
* **IchigoJam Recipe** (IchigoJam Information Site) : https://15jamrecipe.jimdofree.com/ (目前找到統整資源最完整的網站)
* yrm06 私人 blog: https://yrm006.wordpress.com
**參考文件**
* Ichigojam BASIC reference (en):https://ichigojam.net/IchigoJam-en.html
* Ichigojam BASIC Code page: https://15jamrecipe.jimdofree.com/ツール/キャラクターコード一覧/
## 0.4 永續
指南圍繞著「永續」的理念。因為Ichigojam的特殊性,他不需要、必要軟體更新。也因為他的封閉,早就他的獨立性。在這裡永續主要指:
* 長久使用、減少電子垃圾、增加裝置的使用時長。
* 可複製性: 延續其精神與減少斷源的可能,即使原本的軟體不再更新依然可以有更多選擇。
* 減少依賴性:儘量對於其他生態的依賴減少,例如透過網路的必要軟體更新、線上特定平台的服務驗證。
**在有限的資源下創造**
但除了永續外,我認為 **創意是人與生俱來的天賦,也是生而為人的使命。** 所以我也希望透過這個指南帶給你在有限的資源中「創造」的能力。
> 因此,你可以嘗試把這個指南印下來、另存成PDF(因為是單頁式網頁),在沒有網路的時候觀看,這裡為您保留了此權利。
**Legacy 科技會幫助你**
使用較久的科技,除了在尋找零件和科技產品上會比比較新的科技產品來的容易外(例如 mac 必須回到 Apple Store 維修),也因為過去的大量生產、除了可以把被遺棄的電子產品垃圾變黃金外,也可以延續許多科技產品的使用。
**EEPROM 壽命問題**
基於永續原因,而EEPROM雖然對於寫入和讀取都有壽命上的限制,單是對於寫入的壽命還是比較致命的,所以在這裡不建議對板上的 EEPROM 做寫入。但您可以使用 外部的 EEPROM IC 來存取外部的程式碼。
**Ichigojam 永續性評估**
...
## 0.5 教育
「插上插頭、AV端子、USB鍵盤!開工」就算連樹莓派都很難做得如此流暢,因此 Ichigojam 可在日本程式教育中流行。
## 0.6 購買
Ichigojam的購買可以通過英文版的PCN網頁取得,目前跟官方實體店鋪確認可以直送台灣(但是需要另外 3000 多 日圓的費用)
# 1. 硬體入門
## 1.1 板子種類
Ichigojam有很多不同的變種,板子通常內建 BASIC 或 IchigoLatte(其他語言)。目前最新的ichigojam board主要以 Ichigojam R 為主、再來是 Ichigojam S,他們兩者有處理器規格上的天壤之別。[^ref_diff_type_15jams]
**1. Ichigojam boards**
Ichigojam 使用的規格固定,擁有 一個 RCA video output、PS/2 or USB 的 keyboard input、一個 microUSB 的 power input 以及一個 燈和一個按鈕 和 一堆 GPIO。 [^ref_diff_type_15jams]
**1.1 Ichigojam R**
**1.2 Ichigojam S**
**1.3 Ichigojam T**
**1.4 Ichigojam U**
**1.5 Ichigojam 初代**
**2. IchigoCake**
Ichigocake 是一個結合 IchigoPancake 概念的電腦,他同時擁有一個 Ichigojam Computer 以及一個 Pancake 相容的擴容卡。
**3. IchigoDake**
IchigoDake系列是一個極簡版的Ichigojam,他在主板上移除了原先的 RCA output、USB port 和 power input,取而代之的是把原先在板子上的配件轉移到一個dock上,通過此方式降低一塊Ichigojam的價格與體積。
**3.1 IchigoDake**
**3.2 IchigoIgai**
**3.3 DakeJacket**
**4. Raspberry pi**
**4. 配件**
## 1.2 微控制器
ichigojam是一塊基於MCU的小電腦,bootloader、ROM 全部寫入在MCU的Flash memory中。
雖然ichigojam出了好幾種款式,單是他們的核心MCU基本上分為兩種:LPC1114 和 RISC-V 。[^ichigojam_official_spec]
**LPC1114 板**
SOP or DIP package。外觀是一隻毛毛蟲,無論大隻小隻
* MCU:NXP LPC1114 (arm Cortex-M0 48MHz, ROM:32kB, RAM:4kB)
* 外部石英振盪器: 1200kHz
* 鍵盤:**只支援 PS/2** (我知道很扯, USB 介面只有 PS/2 支援)
* 如果你的板子上有 USB-A,那只支援 PS/2 over USB。你需要一個PS/2 轉 USB的轉接器,把你的 PS/2的鍵盤通過轉接器轉介到板子的USB。
* 早期的ichigojam板上是有PS/2的介面,後來不知道什麼原因改成USB。[^ichigojam_fb_kb_usb] 所以你可以當成你的板子上內建了一個 USB 轉 PS/2 的轉接器,而你被逼著使用 USB 口輸入。 ¯\\\_(ツ)\_/¯
**RISC-V 板**
外觀是一個正方形的 QFN package
* MCU:GigaDevice GD32VF103 (RISC-V 32-bit 96MHz, ROM:128kB, RAM:32kB)
* 鍵盤:繼承 LPC1114 同時支援 PS/2 和 USB「有線鍵盤」。
* 無線鍵盤請自行更新到 Ichigojam BASIC v1.5 beta 才會支援
* 還有更多⋯⋯ (之後會列出來)
:::warning
如果你在選擇買板子,我強烈建議你買有QFN package的版本。記憶體大、速度快,價格還一樣。而且支援 USB 鍵盤!(你就不用為了找鍵盤苦惱了)。而且不建議買 IchigoLatte, Ichigojam BASIC 的功能會更加完整。
:::
## 1.3 顯示螢幕
**1. 官方的螢幕配件**
你會在很多ichigojam 官方的推文和照片裡看到同款顯示器。嗯!那個是官方指定的(連創始人也在用喔)。(但是鍵盤就不怎麼統一了)
這款螢幕的型號是 —— `Mon328-AV43-15WI` ,目前唯一找到的3個銷售據點如下:
* 實體:
* 秋葉原 - 東京無線電電子材料行 的 「PCN フラッグシップ秋葉原 BY ASSEMBLAGE」: https://pcn.club/shop/akiba/
* 線上
* https://eleshop.jp/shop/g/gF52411/ (推薦這個網站,因為他有提供整組包含螢幕的 ichigojam,可能是機構指定?)
* https://www.monotaro.tw/p/26881532.html
## 1.4 鍵盤輸入
(尚未完成)
## 1.5 顯示卡與音效介面
ichigojam預設只有黑白輸出,如果需要彩色輸出即需要另一張彩色顯卡來顯示。 ichigojam官方的彩色顯卡為 IchigoPancake。
**IchigoPanCake - 草莓鬆餅 🥞**
IchigoPanCake 是 Ichigojam 的彩色顯示卡兼音效卡。(沒錯,Ichigojam是黑白的)
## 1.a 永續性評估
...
# 2. 軟體入門
## 2.1 系統簡介
:::danger
警告:已踩坑! 在編輯的當下 IchigoLatte 的 RISC-V 版本還沒有正式版,即便已在市面上流通的 IchigoLatte 板子。(他們居然把非正式版燒入正式產品??)如果你不能接受有 bug 或 JS 基礎功能尚未完成的環境請不要購買。
:::
> 註:這裡指的正事發行版是 > v1.0.0,雖然 IchigoLatte 到正式版也會有bug,詳細請看 章節 bug
目前「操作」系統主要有兩種:ichigojamBASIC 和 IchigoLatte
**Ichigojam BASIC(比 IchigoLatte 完整)**
* 原始碼授權: **閉源**
* 和任何 BASIC 環境一樣,使用「行編輯器(Line Editor)」的模式編輯程式碼。
* Ichigojam 的同生子弟,Ichigojam 為此而生。
* 由官方支援更新
* 支援官方模擬器:https://fukuno.jig.jp/app/IchigoJam/
**IchigoLatte (RISC-V 在我編輯的當下並沒有任何正式版發行)**
* 原始碼授權:有待確認
* **⚠️ 目前已知一堆問題,請有膽量的人大膽嘗鮮。**
* 有你熟知的JS語法、Python、Forth、Ruby
* 但對於 EEPROM 會有過多的操作,板子壽命會簡短。
* 沒有模擬器
## 2.2 Ichigojam BASIC
Ichigojam 的同生子弟,Ichigojam 為此而生。也是目前 Ichigojam Board 上完成度最高的作業環境。
**1. 基礎介紹**
**1.2 行編輯 - Line Editing**
在早期,寫程式是沒有游標和捲軸可以上下在程式碼之間遊蕩的。也因為早期的電腦使用 Teletyper,以紙張顯示輸出,所以唯一的游標就是那個打字機的油墨頭。到了後面映像管以數位的形式取代了終端機,但隨之而然的傳統還是保留了下來,成為了BASIC的特色。
和任何 basic 一樣,你可以通過 輸入「 `line_number [code]` 」來撰寫任何程式。
而 line_number 特別是 10 的倍數。例如:
```basic
10 PRINT "hello"
20 PRINT "world"
30 GOTO 10
RUN
```
通過在開頭指定 行數,告訴程式第幾行有什麼程式,來達到編輯的效果,所以故稱為行編輯。這也是 vim 的始祖,也是祖傳 Unix 和 Linux編輯器 ed 的原理。
也因為行數固定後無法修改指定後的內容,所以會在原本程式的每行中間做10行的空格,作為後續 debug point 和 新增程式的空間,這才是 BASIC 的味道。
下面是一個 要在第25行插入一行新的程式的範例。
```basic
10 ...
.. ...
990 ...
25 PRINT "INSERT!!
```
**2. 進階介紹**
## 2.3 IchigoJam web
# 3. 編程入門
## 3.1
## 3.2 BASIC 程式架構設計
**避免義大利麵程式、避免使用 GOTO**
GOTO 很好用,很偉大,但是他也有他的危險,請謹慎使用。如果使用不當可能造成程式無法debug 或過於複雜。
請參考:https://en.wikipedia.org/wiki/Goto
如果可以儘量使用 GOSUB 配合 RETURN,達成 能夠 debug traversal program branches 的效果。
## 3.3 ROM (EEPROM)
隨著時代的演進,ROM 從磁碟機變成了 MCU 內建的 EEPROM。雖然官方建議你使用 MCU 內建的 EEPROM,但因為 每個 EEPROM 的使用壽命有限,基於我的理念,在永續使用上還是希望你避免對內置的 EEPROM 做寫入(讀取似乎對於 MCU 沒有造成比起 寫入還要大的影響),避免電子垃圾的產生與浪費,讓我們把電腦垃圾的製造效率降到最低!
所以在這裡介紹使用外部 EEPROM 的方法(官方 blog: https://15jamrecipe.jimdofree.com/周辺機器/外部記憶装置-eeprom/ )
# 4. 操作入門
「編程」只是操作電腦的其中一種方式,在這個章節中將會 introduce 許多操作此電腦的方式與概念。
> 如果你對「操作」這個名字在這台電腦上任然陌生,你可以從 shell 的影子中看到,我們每天打的指令,事實與 microcopmuter 系統中 BASIC 的 terminal 雷同,他們都是使用指令操作電腦。
## 4.1 基礎概念
對於現代電腦,I/O有很多種輸入。從鍵盤、滑鼠、觸控、網路、USB、隨身碟、指紋辨識、Webcam、Microphone等等都是 I/O。
對於 Ichigojam 的 I/O 的讀寫相對簡單,你可以使用 UART 以STD I/O或者通過外接ROM讓系統讀取,還有額外的 GPIO 和 I2C 介面可以使用。
但除了使用Ichigojam上的「基礎I/O」外,我們還可以使用不同的部件來達成對應的功能。例如利用 ESP-AT 來連用IRC網路聊天、上網、用 CH376S 來存取 隨身碟上的檔案(其實可以用 EEPROM )等等⋯⋯**所有模組、訊號都是你可以觸手可及的**。
**1. 操作的概念**
操作什麼?當然是操作電腦!統稱「Computing」。2020年後的我們每天都在操作電腦,尤其是手機或iPhone,他的運算能力更是勝過一台ichigojam的好幾倍。但是究竟算力這麼弱的電腦我們又能做什麼?
「控制電腦達成一連串的動作或行為」就是一種操作電腦的行為,為此,我們可以讓 ichigojam 做很多我們可以做的事情,包括打筆記、上網、編輯照片(因為照片是彩色,你可能需要一塊 ichigo pancake)
但回歸到本質,電腦也只是進行一連串重複行為的組合而已。也就是說他們本質上都是電腦,但取決於你打算拿他們做什麼。如果你也想要用ichigojam來當作主力機的話,你可能也要稍微熟悉讓 ichigojam 做出你想要讓他做出的事情。
**2. BASIC 操作的定位**
如果我們選擇「操著」這台電腦,而不是「編程(Program)」這台電腦,對於 BASIC 在 ichigojam 上來說就是我們的shell scripting language,他可以是我們程式的entry point。就如同 Commodore 64 一樣,載入程式需要透過 BASIC 的 LOAD 把程式從 磁碟機 載入進去。
以下是一些 shell scripting language 和 BASIC 之間的差異:
| Shell Script | Ichigojam BASIC |
|-|-|
| `echo "hello world"` | `print "hello world"` |
| `sleep 60; echo -ne '\007'` | `wait 60: beep`
| `./file.bin` | `load 100` |
| `ls` | `files` or `files 107` if you have EEPROM |
## 4.2 使用者介面
在 Ichigojam 中有兩種可以操作系統的方式:
* Keyboard & AV 端子輸出
* UART Serial 介面
在 BASIC 中 兩者可以並存(使用 SWITCH 切換模式),但在 IchigoLatte中需要互相切換(一旦切換所有狀態都會消失,按下板上按鈕即可)。
**Code Page**
採用自定義的 Code page 和 keybaord 資源映射。
**Keyboard Input[](https://)**
鍵盤佈局根據系統有所不同。只要呼叫 0xD00 系統會預判並且在記憶體位址就可以切換鍵盤佈局。在預載為BASIC的Ichigojam board上,EEPROM 的 file 3 已經寫好了以下指令:
```basic
files
0
1
2
3 'EXCHG KBD JP-US
OK
load 3
Loaded 84byte
OK
list
1 'EXCHG KBD JP-US
2 IF USR(#D00)=#F00 ?"US KEYBOARD" ELSE ?"JP KEYBOARD"
3 NEW
```
如果你重灌或你拿到的板子沒有這行,可以刻上去測試看看。
# 5. 進階操作
## 5.1 刷機
:::danger
刷機屬於進階操作,請謹慎使用。官方提供刷機服務,如有任何不慎刷失敗,你只能跨海到日本請求支援,在台灣的你是沒有任何援助的,請自救。(或者來找我? :3c )
:::
官方刷機資源(皆為日文,中文請看個章節 👇):
* LPC1114 - https://yrm006.wordpress.com/2019/05/15/how-to-reflash-a-firmware-of-your-ichigojam-board-ichigojamボードのファームウェアの焼き方/
* RISC-V - https://15jamrecipe.jimdofree.com/周辺機器/パソコンと接続/risc-v/
> 👆 同時也是我的參考來源
> 我用了 IchigoLatte 的 JS 板之後我馬上刷了 Ichigojam BASIC 上去,真的太難用了。
**1. LPC1114 刷機**
在刷機之前你需要準備幾個工具:
* 你要刷的 Ichigojam board
* TTL to USB 的轉接器 / 線(或者 UART to USB)
* (或者你要用Arduino 我也不反對)
在這之後請按照以下方式連結:
```
TTL -- Ichigojam
VCC -- VCC
TX -- RX
RX -- TX
GND -- GND
ISP -- GND
```
然後開啟你的電腦來刷機。
LPC1114 的刷機很簡單,這裡以 mac 舉例:
1. 安裝必要套件(請先安裝 brew )
```sh
brew install lpc21isp
```
2. 準備 TTL 轉接器,接上電腦,輸入以下指令
```
```
## 5.2 重製 Ichigojam
Ichigojam是非開源的,而大部分產品的開發都仰賴官方的開發。基於永續發展
# 6. 進階編程
在這個單元中,我會希望透過一系列的實作發揮這台機器的可玩性、把不同平台的橋樑建立起來。所以我們將會進行4個階段:
* Machine code
* 組譯器
* Virtual machine
* 編譯器
## 6.1 Machine code 編程
顧名思義,就是直接寫 0 和 1 來操作 Ichigojam,這是 Ichigojam 的最終形式!!終極形式!!
通過直接設計 MCU 上架構的指令集,你可以得到比 BASIC 直譯器還要高效率的程式。這也是很多 Commodore 64 玩家在最後開發遊戲時的首選,因為這比起BASIC空間效率和執行效率都比 BASIC 直譯器高。
官方支援:
* 在ichigojam BASIC上實作 ARM-Cortex M0 的 binary - https://fukuno.jig.jp/1186
**1. Machine Code 入門**
**2. 基礎運算**
## 6.2 組譯器 實作
## 6.3 Virtual Machine 實作
## 6.4 編譯器 實作
# 7. 已知問題
這裡是 **臭蟲** 地帶,會帶領你隨處都踩到蟲,不要怪我。
## 7.1 IchigoLatte
1. 目前測試 v1.1.7 的版本輸入: 0.1+0.2 會直接閃退。
2. 輸入 0.1 或 任何錯誤的語法,會導致接下來的所有操作失靈。
3. IchigoLatte 會頻繁對 MCU EEPROM寫入,已知EEPROM寫入壽命有限,因此不建議使用 IchigoLatte 作為作業系統,你可以參考 章節 刷機 來把您IchigoLatte的板子灌成更完整的 Ichigojam BASIC。
4. 有時使用 `var a = Array(10);` 會直接閃退,儘管符合記憶體使用。
5. IchigoLatte 不支援直接對螢幕做任何的繪圖,需仰賴 IchigoPanCake 繪圖卡才能實作(差評) 或者直接對特定字元寫入達成更高解析度的繪圖。
> 經過一整輪的使用,我發現目前的 IchigoLatte 還處於半成品的階段。如果你有挑戰的心 IchigoLatte 隨時會歡迎您的挑戰。
# 8. 參考文獻
# 9. 附錄
## 9.1 應用程式
**1. Calender**
來源:https://15jamrecipe.jimdofree.com/basic/プログラム/カレンダー/
```basic
10 LET [1],31:LET [2],28:LET [3],31
20 LET [4],30:LET [5],31:LET [6],30
30 LET [7],31:LET [8],31:LET [9],30
40 LET [10],31:LET [11],30:LET [12],31
50 INPUT "ネン?",Y:INPUT "ツキ?",M
60 IF(Y%4==0)*((Y%100<>0)+(Y%400==0)) LET [2],[2]+1
70 IF M<3 LET Y,Y-1:LET M,M+12
80 LET O,(13*M+8)/5:LET O,(Y+Y/4-Y/100+Y/400+O+1)%7
90 IF M>12 LET M,M-12
100 LET I,O:LET J,1
110 ?:? "SunMonTueWedThuFriSat"
120 IF O<>0 ? " ";:LET O,O-1:GOTO 120
130 ? " ";:IF J<10 ? " ";
140 ? J;:LET I,I+1:IF I=7 ?:LET I,0
150 LET J,J+1:IF J<=[M] GOTO 120
160 ?:IF I<>0 ?
```
## 9.2 Ichigojam BASIC 語言定義
語言定義是為了可以讓更多工程師可以重新復刻原本的語言設計和設定。在這裡是為了更精準的描述 Ichigojam BASIC 的細節,理論上要比官方的文件還要詳細,因為他解釋了每個程式碼字元之間的關係定義[^official_ichigojam_basic_ref] 。也因為如此,更能夠透過這個規則重新實現 ichigojam BASIC 於其它的裝置。
語言定義繼承 BASIC 原始定義,並外加許多 function 與 keyword [^ref_basic_lang_def] :
> 註:語言定義尚未完整
```
line ::= number statement CR | statement CR
statement ::= PRINT expr-list
IF expression relop expression THEN statement
FOR var = expression TO expression (STEP expression)* (statement) NEXT
GOTO expression
INPUT var-list
LET var, expression
GOSUB expression
RETURN
CLS
LIST ((number) (, number)* )*
RUN
END
(statement) : (statement)
LED (0|1)
expr-list ::= (string|expression) (, (string|expression) )*
var-list ::= var (, var)*
expression ::= (+|-|ε) term ((+|-) term)*
term ::= factor ((*|/) factor)*
factor ::= var | number | (expression)
var ::= A | B | C ... | Y | Z | a | b | c ... | y | z
number ::= digit digit*
digit ::= 0 | 1 | 2 | 3 | ... | 8 | 9
relop ::= < (>|=|ε) | > (<|=|ε) | =
```
# 著作權 與 授權
<a rel="license" href="http://creativecommons.org/licenses/by/3.0/tw/"><img alt="Creative Commons License" style="border-width:0" src="https://i.creativecommons.org/l/by/3.0/tw/88x31.png" /></a><br />This work is licensed under a <a rel="license" href="http://creativecommons.org/licenses/by/3.0/tw/">Creative Commons Attribution 3.0 Taiwan License</a>.
[^ichigojam_official_spec]: 官方的 ichigojam spec https://p.na-s.jp/ichigoboard.html
[^ichigojam_fb_kb_usb]: 參考根據 https://www.facebook.com/groups/ichigojamfan/permalink/1015392615509894/?mibextid=S66gvF 所表述,大部分市面上的usb鍵盤都有支援legacy mode,可以提供 ps2 over usb的訊號,但這不意味著說鍵盤都支援。(2023-02-07 更新:從官方取得了一個「Mini Keyboard」的鍵盤,從鍵盤外觀來看我在台灣也有買過。US 佈局可使用 LCP1114 的板子)
[^ref_basic_lang_def]: 參考自 https://en.wikipedia.org/wiki/BASIC_interpreter#Language_design
[^official_ichigojam_basic_ref]: 官方語言的大致參考文件: https://ichigojam.net/IchigoJam-en.html
[^ref_diff_type_15jams]: 參考自:https://15jamrecipe.jimdofree.com/ichigojam/種類/