HSP : Hot Soup Processor ver3.7 / onion software 1997-2025(c)

# HSP3 for Linux/Raspberry Pi

## はじめに

HSP3 for Linux/Raspberry Piは、LinuxのGUI環境(X Window System)及びRaspberry Pi(Raspbian)で動作するHot Soup Processor(HSP)の開発環境です。
安価で幅広く環境が整備されているLinux上で、HSP3の開発環境を含むサポートを目指して開発が進められています。 Raspberry Piは、その中でも非常にコンパクトで安価なデバイスとして、IoTやプログラミング教育の分野でも注目されています。
いままでも、Windowsだけでなく、HSP3Dishというランタイムを通してAndroid,iOS,WebGL(html5)などの実行環境を整備してきましたが、 新たに、Linux及びRaspbian(Raspberry Pi上のOS)環境でも利用できるよう、整備を行なっていきます。
最初のバージョンとして、簡易スクリプトエディタとHSP3Dish/HGIMG4実行環境を含むプレビュー版を公開しています。 Windows版HSP3とともにサポートを広げていく予定ですので、どうぞご期待ください。
最新版は、githubにてソースコードとともに公開されています。
Raspberry Piをご使用の方は、JBOYSOFT様の「初心者入門 HSPプログラミング ラズベリーパイ版」のページにて導入が説明されています。

| 初心者入門 HSPプログラミング ラズベリーパイ版 by JBOYSOFT

## Linuxインストール

LinuxのGUI環境(X Window System)で動作します。一部の機能は、OpenGL及びSDLライブラリを使用して動作します。 ネットワークに接続できる場合は、gitコマンドで直接リポジトリを取得してください。

    	git clone http://github.com/onitama/OpenHSP

アーカイブがある場合は、内容を任意のディレクトリに展開して、ソースをコンパイルしてください。コンパイルには、gcc及びmakeを実行できる環境が必要になります。 コンパイルの際には、以下のライブラリが必要になりますので、あらかじめ確認を行なって下さい。

    	OpenGLES2.0以降 / EGL
    	SDL2 / SDL2-mixer
    	gtk+-2
    	libcurl4
    	libgpiod2
    	libffi

Debian(Ubuntu)の場合は、以下のスクリプトを実行してコンパイルすることができます。

    	./setup.sh

手動でmakeを行う場合は、以下のようにパッケージマネージャから以下のようにライブラリをインストールしてください。(Debian(Ubuntu)の場合)

    	sudo apt update
    	sudo apt install libgtk2.0-dev
    	sudo apt install libglew-dev
    	sudo apt install libsdl2-dev libsdl2-image-dev libsdl2-mixer-dev libsdl2-ttf-dev
    	sudo apt install libgles2-mesa-dev libegl1-mesa-dev
    	sudo apt install libcurl4-openssl-dev
    	sudo apt install libgpiod2 libgpiod-dev
    	sudo apt install -y libffi-dev

リポジトリにはソースのみが含まれていますので、makeによってコンパイルする必要があります。 (Linuxのバージョンやディストリビューションによって正しくコンパイルされない場合は、修正が必要になります。)

    	cd OpenHSP
    	make

必要なツールのコンパイルが行なわれ、HSP3が使用できる状態になります。

## Raspberry Piインストール

Raspberry Pi, Raspberry Pi2, Raspberry Pi3, Raspberry Pi400, Raspberry Pi4, Raspberry Pi5, Raspberry Pi zeo上で動作します。
Raspberry Pi OS, Raspbian OS上で動作します。あらかじめ、Raspbianが動作してキーボード、マウスが接続されている状態でご使用ください。
hsp3dish及びhsp3gp(HGIMG4)、hsed(スクリプトエディタ)は、GUI環境でのみ動作します。
githubから最新版を任意のディレクトリに展開して、ソースをコンパイルしてください。コンパイルには、gcc及びmakeを実行できる環境が必要になります。

    	git clone http://github.com/onitama/OpenHSP
    	cd OpenHSP

コンパイルの際には、追加のライブラリが必要になります。ネットワークに接続されている状態でライブラリをダウンロードする必要があります。 Raspberry Pi OSの場合は、以下のコマンドを実行することでセットアップが実行されます。

    	./setup.sh

Raspberry Pi3以下の環境で、Raspbian OSの場合は、以下のコマンドを実行することでセットアップが実行されます。

    	./pisetup.sh

アーカイブにはソースのみが含まれていますので、makeによってコンパイルする必要があります。 (Raspbianのバージョンやディストリビューションによって正しくコンパイルされない場合は、修正が必要になります。)

    	make -f makefile.raspbian

アーカイブの内容が展開されたディレクトリでmakeコマンドを実行してください。 必要なツールのコンパイルが行なわれ、HSP3が使用できる状態になります。

    ※ Raspberry Pi4以降の場合は、Linuxと同様の方法でインストールを行ってください
    ※ Raspberry Pi4以降ではフルスクリーンによる実行はサポートされません

## 使用方法

インストールを行なうと、以下のコマンドが生成されます。

    	hsed		スクリプトエディタ(簡易版)
    	hspcmp		HSP3コードコンパイラ
    	hsp3cl		HSP3コマンドラインランタイム
    	hsp3dish	HSP3Dishランタイム
    	hsp3gp		HGIMG4ランタイム

スクリプトエディタ(簡易版)は、HSP3のスクリプトを記述して、実行することのできるGUIアプリケーションです。 基本的なスクリプトの編集、及びロード・セーブ機能を持っています。 以下のコマンドで起動することができます。

    	./hsed

[F5]キー、または「HSP」メニューから「Run」を選択することで編集しているスクリプトを実行できます。 現在のバージョンでは、標準ランタイムとしてhsp3dishが使用されます。 HSP3Dishに対応するサンプルコードがsampleフォルダに含まれていますので、お試しください。 スクリプトの文字コードはUTF-8として扱われます。Windowsが使用する文字コード(SJIS)とは異なりますので注意してください。
コマンドラインからスクリプトの実行を行なう場合は、hspcmpによりHSPオブジェクトファイルを作成する必要があります。

    	./hspcmp -d -i -u test.hsp

上の例では、「test.hsp」ファイルからオブジェクトファイル「test.ax」を生成します。 生成されたオブジェクトファイルを、ランタイムに渡して実行を行ないます。

    	./hspcmp -e test.ax

上の例では、「test.ax」をHSP3コマンドラインランタイム「hsp3cl」で実行します。 同様に、「hsp3dish」「hsp3gp」などのランタイムに合わせたスクリプトを実行させることができます。 (「hsp3dish」「hsp3gp」の実行は、GUI環境が必要になります。)
Raspberry Pi版では、フルスクリーンで実行を行ないます。 実行の中断は、[ctrl]+[C]か[esc]キーを押してください。 キーボードだ正しく認識されていない場合など、中断ができなくなることがありますので注意してください。 GUIエディタだけでなく、コマンドラインから「./hsp3dish ****.ax」の形で実行を行なうことも可能です。

| HSP3Dishのページへ
| HSP3Dishオンラインマニュアル

## exec、devprm命令について

Linux版、Raspberry Pi版ともにexec命令により、シェルのコマンドを呼び出すことができます。 また、devprm命令によりファイルシステム上のデバイスに文字列を出力することが可能です。

    	devprm "/sys/class/gpio/export", "2"

のように記述した場合は、「/sys/class/gpio/export」に「2」が出力されます。 シェルから「echo 2 > /sys/class/gpio/export」を実行するのと同じ動作になります。

## GPIO入出力

devcontrol(gpio)命令によりGPIO入出力を行なう拡張が行われています。
GPIO出力を制御する場合は、以下のように記述します。

    	devcontrol "gpio", ポート番号, 出力値
    	( 「gpio ポート番号, 出力値」と記述することも可能 )

ポート番号は、GPIOのポートを数値で指定します。 出力値は、1(ON)か0(OFF)を数値で指定することで、デジタルポートの出力を制御します。 入力を行う場合は、以下のように記述します。

    	devcontrol "gpioin", ポート番号
    	( 関数として「gpioin(ポート番号)」と記述することも可能 )

命令の実行後にシステム変数statに0か1が代入されます。 (エラーが発生した場合は、マイナス値が代入されます)
GPIO入出力は、hsp3dishだけでなくhsp3clからも使用することが可能です。

## I2C入出力

devcontrol(i2c～)命令によりI2Cデバイスとの入出力を行なう拡張が行われています。
(RaspberryPiでは、オプション設定でI2CをEnableにする必要があります。I2C制御を行なわない場合は、設定の必要ありません。)
I2C制御を行う場合は、以下のように記述します。

    	devcontrol "i2copen", スレーブアドレス, チャンネル
    	( 「i2copen スレーブアドレス, チャンネル」と記述することも可能 )

    	「チャンネル」は複数のデバイスを同時に指定する場合に識別を行う番号です。(0～31の整数値)
    	単一のデバイスを制御する場合は省略(0)して構いません。
    	i2copenにより指定されたアドレスのデバイスを制御できる状態になります。
    	結果がシステム変数statに返ります。0の場合は成功、それ以外はエラーになります。

データを出力する場合は、以下のように記述します。

    	devcontrol "i2cwrite", データ値, データサイズ, チャンネル
    	( 「i2cwrite データ値, データサイズ, チャンネル」と記述することも可能 )

    	データ値は、HSPが扱う32bitの整数値になります。
    	データサイズが0または省略した場合は、8bit(1byte)のみ出力されます。
    	データサイズは、1,2,3,4が指定できます。それぞれ、1～4byteのサイズが出力されます。

データを入力する場合は、以下のように記述します。

    	devcontrol "i2cread", チャンネル
    	( 関数として「i2cread(チャンネル)」と記述することも可能 )

    	devcontrol "i2creadw", チャンネル
    	( 関数として「i2creadw(チャンネル)」と記述することも可能 )

命令の実行後にシステム変数statに結果が代入されます。 i2creadは、8bit(1byte)の値、i2creadwは、16bit(2byte)の値を取得します。 (エラーが発生した場合は、マイナス値が代入されます) I2C制御は、hsp3dishだけでなくhsp3clからも使用することが可能です。

## GPIO入出力

devcontrol(gpio)命令によりGPIO入出力を行なう拡張が行われています。
GPIO出力を制御する場合は、以下のように記述します。

    	devcontrol "gpio", ポート番号, 出力値
    	( 「gpio ポート番号, 出力値」と記述することも可能 )

ポート番号は、GPIOのポートを数値で指定します。 出力値は、1(ON)か0(OFF)を数値で指定することで、デジタルポートの出力を制御します。 入力を行う場合は、以下のように記述します。

    	devcontrol "gpioin", ポート番号
    	( 関数として「gpioin(ポート番号)」と記述することも可能 )

命令の実行後にシステム変数statに0か1が代入されます。 (エラーが発生した場合は、マイナス値が代入されます)
GPIO入出力は、hsp3dishだけでなくhsp3clからも使用することが可能です。

## SPI入出力

devcontrol(spi)命令によりSPIの全二重通信を行なう拡張が行われています。
HSP3.6までのSPIサポートは、read/write システムコールによるものに限られており、 したがって半二重通信のみがサポートされていました(read/write では全二重通信はできない)。 しかし SPI はデータ線が 2 本あり、いくつかの SPI デバイスは全二重通信による通信を要求します。 完全なデータのやり取りをするには IOCTL による全二重通信が必要になります。
HSP3.7では、HSPスクリプトからアクセスできる汎用的で全二重通信 (IOCTL 経由) 可能な SPIインターフェースを追加します。また IOCTL で全二重通信 (`SPI_IOC_MESSAGE(N)`) をリクエストするときに必要なパラメータ`struct spi_ioc_transfer` を設定する関数も追加しました。
SPI制御は、hsp3dishだけでなくhsp3clからも使用することが可能です。 (RaspberryPiでSPI制御を行う場合は、オプション設定でSPIをEnableにする必要があります。SPI制御を行なわない場合は、設定の必要ありません)
基本的な命令は、以下の通りです。

    	devcontrol "spiopen", バス番号, チップセレクト, ch番号
    	( open ch )

「ch番号」は複数のデバイスを同時に指定する場合に識別を行う番号です。(0～31の整数値) 単一のデバイスを制御する場合は省略(0)して構いません。 バス番号セレクトとチップセレクトはデバイスファイルへのパス`/dev/spidev<バス番号>.<チップセレクト>`に対応し、 指定したデバイスファイルに対応するデバイスを制御できるようになります。 結果がシステム変数statに返ります。0の場合は成功、それ以外はエラーになります。

    	devcontrol "spiclose", ch番号
    	( open ch )

指定したチャンネルの通信を終了します。

    	devcontrol "spiread", ch番号
    	( byte read )
    	devcontrol "spiread", ch番号
    	( word read )

命令の実行後にシステム変数statに入力値が代入されます。 (エラーが発生した場合は、マイナス値が代入されます)

    	devcontrol "spiwrite", 出力値, ch番号
    	( byte write )
    	devcontrol "spiwritew", 出力値, ch番号
    	( word write )

出力値がSPIに出力されます。 (エラーが発生した場合は、マイナス値が代入されます)

全二重通信の命令は、以下の通りです。

    	devcontrol "spitransceive", データ値, データサイズ, ch番号
    		データ値は、HSPが扱う32bitの整数値になります。
    		データサイズが0または省略した場合は、8bit(1byte)のみ出力されます。
    		データサイズは、1,2,3が指定できます。それぞれ、1～3byteのサイズが送信・受信されます。
    		送受信は同時に行われます。
    		命令の実行後に指定したサイズの受信データがシステム変数statに結果が代入されます。
    		（エラーが発生した場合は、マイナス値が代入されます）。
    		ビッグエンディアン環境で使用する場合は上位3 byteがデータを、下位1 byteがエラーを表します。

SPI デバイスドライバに対して設定が必要な場合は、`spiconfigureh`、`spiconfighrem`、`spiconfigurel`、 加えて`spisetmode`、`spisetmode32`、`spisetlsbfirst`、 `spisetbitsperword`、`spisetmaxspeedhz`を使用します。 それぞれ以下のように記述します。

    	devcontrol "spiconfigureh", SPEED_HZ, DELAY_USECS, BITS_PER_WORD
    	devcontrol "spiconfighrem", CS_CHANGE, TX_NBITS, RX_NBITS
    	devcontrol "spiconfighrel", WORD_DELAY_USECS
    	devcontrol "spisetmode", MODE, チャンネル
    	devcontrol "spisetmode32", MODE, チャンネル
    	devcontrol "spisetlsbfirst", LSB_FIRST, チャンネル
    	devcontrol "spisetbitsperword", BITSPERWORD, チャンネル
    	devcontrol "spisetmaxspeedhz", SPEED_HZ, チャンネル
    		SPEED_HZ でクロック周波数を設定します。
    		DELAT_USECS に非ゼロを設定すると最終ビット送信と次のバイト送信の間にマイクロ秒単位の遅延を挿入します。
    		BITS_PER_WORD でデバイスのワードサイズを設定します。
    		CS_CHANGE に非ゼロを設定すると通信の後にチップセレクトを非アクティブ化しません。
    		TX_NBITS で書き込みのデータ線本数を指定します。0 でシングルモードになります。
    		デュアル、クアッドモードに設定する場合ホストのヘッダーから SPI_TX_DUAL、
    		SPI_TX_QUAD が参照する値を設定してください。
    		RX_NBITS で読み込み時のデータ線本数を指定します。0 でシングルモードになります。
    		デュアル、クアッドモードに設定する場合ホストのヘッダーから SPI_RX_DUAL、
    		SPI_RX_QUAD が参照する値を設定してください。
    		WORD_DELAY_USECS でワード間の遅延をマイクロ秒単位で設定します。
    		MODE に0—3を設定するとSPIの動作モードがそれぞれモード0、...、モード3 に設定されます。
    		LSB_FIRSTにゼロを設定するとMSB先行モードに、非ゼロを設定するとLSB先行モードになります。

SPI通信と初期化の例:

    	; Configure spidev options
    	devcontrol "spisetmaxspeedhz", 10000, ch
    	devcontrol "spisetmode", 0, ch
    	devcontrol "spisetlsbfirst", 0, ch
    	devcontrol "spisetbitsperword", 8, ch
    	devcontrol "spiconfigureh", 10000, 0, 8
    	devcontrol "spiconfigurem", 1, 0, 0	; Keep selecting the device for the 3-bytes command
    	devcontrol "spiconfigurel", 0

    	; Start communication
    	;; Prepare a buffer as {dont care, upper 2 bits of data, lower 8 bits of data}
    	dim recv, 3
    	;; Send start byte
    	devcontrol "spitransceive", 1, 1, ch
    	byte(0) = stat
    	;; Send control byte: SINGLE_ENDED (0x80) | adc_pin.
    	;; In bit-wire sepresentation, {single/diff, adc_pin[2], adc_pin[1], adc_pin[0], x, x, x}
    	SIGNLE_ENDED = 0x80
    	devcontrol "spitransceive", SINGLE_ENDED | (adc_pin << 4), 1, ch
    	byte(1) = stat
    	;; Send an empty byte (avoiding start byte 0x01) and receive rest data.
    	devcontrol "spiconfigurem", 0, 0, 0	; Deselect the device
    	devcontrol "spitransceive", 0x00, 1, ch
    	byte(2) = stat
    	res = ((0x03 & byte(1)) << 8) | byte(2)
    	mes res

## 著作権とライセンス

Linux/Raspberry Pi版は、OpenHSPの派生物として取り扱い、ライセンスもOpenHSP/HSP3に準拠した修正BSDライセンスとなります。

    -------------------------------------------------------------------------------
    Hot Soup Processor (HSP)
    Copyright (C) 1997-2021, Onion Software/onitama, all rights reserved.
    Made with base technology of OpenHSP.

    OpenHSP
    Copyright (C) 1997-2025, Onion Software/onitama, all rights reserved.

    These softwares are provided by the copyright holders and contributors "as is" and
    any express or implied warranties, including, but not limited to, the implied
    warranties of merchantability and fitness for a particular purpose are disclaimed.

Linux/Raspberry Pi版は、zakkiさん、yshimmyoさんに多大なご協力を頂きました。 開発を支援し、ご意見をお寄せいただいた多くの方々に感謝致します。
ソースコードは、OpenHSPリポジトリから取得することができます。

    		Github OpenHSP Development
    		http://github.com/onitama/OpenHSP