├── README.md ├── img ├── spi_mode0.png ├── spi_mode1.png ├── spi_mode2.png └── spi_mode3.png ├── mruby_io_ADC_en.md ├── mruby_io_ADC_ja.md ├── mruby_io_GPIO_en.md ├── mruby_io_GPIO_ja.md ├── mruby_io_I2C_en.md ├── mruby_io_I2C_ja.md ├── mruby_io_PWM_en.md ├── mruby_io_PWM_ja.md ├── mruby_io_SPI_en.md ├── mruby_io_SPI_ja.md ├── mruby_io_UART_en.md └── mruby_io_UART_ja.md /README.md: -------------------------------------------------------------------------------- 1 | # About I/O API Guidelines 2 | 3 | mruby and mruby/c have released the Common I/O API Guidelines, which enhance program portability across various microcontrollers and improve the reusability of various sensors and I/O control libraries. 4 | 5 | # About I/O API Classes 6 | 7 | GPIO: [Japanese](mruby_io_GPIO_ja.md) / [English](mruby_io_GPIO_en.md) 8 | ADC: [Japanese](mruby_io_ADC_ja.md) / [English](mruby_io_ADC_en.md) 9 | PWM: [Japanese](mruby_io_PWM_ja.md) / [English](mruby_io_PWM_en.md) 10 | UART: [Japanese](mruby_io_UART_ja.md) / [English](mruby_io_UART_en.md) 11 | I2C: [Japanese](mruby_io_I2C_ja.md) / [English](mruby_io_I2C_en.md) 12 | SPI: [Japanese](mruby_io_SPI_ja.md) / [English](mruby_io_SPI_en.md) 13 | 14 | # Community-developed Libraries 15 | 16 | Additionally, we would like to introduce libraries developed by enthusiastic contributors for MCUs that have been made available. If there are MCU libraries not listed below and you have created your own, we encourage you to inform us through the inquiry so that we can include it in our introductions.This section is not covered by the License of this Guideline, and you should follow the guidelines of each developer. 17 | 18 | ## mruby 19 | 20 | ### ESP32 21 | 22 | [mruby-esp32](https://github.com/mruby-esp32/mruby-esp32) 23 | [mruby-esp32-spi](https://github.com/mruby-esp32/mruby-esp32-spi) by [yuuu](https://github.com/yuuu) 24 | [mruby-esp32-adc](https://github.com/mruby-esp32/mruby-esp32-adc) by [yuuu](https://github.com/yuuu) 25 | 26 | ## mruby/c 27 | 28 | ### RP2040 29 | 30 | [mrubyc-rp2040-peripheral-demo](https://github.com/picoruby/rp2040-peripheral-demo) by [hasumikin](https://github.com/hasumikin) 31 | 32 | ### PIC32 33 | 34 | [mrubyc-pic32mx170](https://github.com/YoshihiroOgura/pic32mx170_mrubyc/tree/master) by [YoshihiroOgura](https://github.com/YoshihiroOgura) 35 | 36 | ### ESP32 37 | 38 | [mrubyc-esp32](https://github.com/gfd-dennou-club/mrubyc-esp32) by [gfd-dennou-club](https://github.com/gfd-dennou-club)([sugiymki](https://github.com/sugiymki)) 39 | 40 | # License 41 | 42 | This document, excluding specifically indicated sections, is distributed under the Creative Commons License CC BY 4.0. 43 | 44 | [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/) 45 | 46 | ![CC BY 4.0](https://licensebuttons.net/l/by/4.0/88x31.png) 47 | 48 | 49 | Copyright (C) 2023 mruby forum committee. 50 | Copyright (C) 2023 Kyushu Institute of Technology. 51 | Copyright (C) 2023 Shimane IT Open-Innovation Center. 52 | -------------------------------------------------------------------------------- /img/spi_mode0.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/mruby/microcontroller-peripheral-interface-guide/514497cfe184edda842f4410cd0eaee1acbdfb9c/img/spi_mode0.png -------------------------------------------------------------------------------- /img/spi_mode1.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/mruby/microcontroller-peripheral-interface-guide/514497cfe184edda842f4410cd0eaee1acbdfb9c/img/spi_mode1.png -------------------------------------------------------------------------------- /img/spi_mode2.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/mruby/microcontroller-peripheral-interface-guide/514497cfe184edda842f4410cd0eaee1acbdfb9c/img/spi_mode2.png -------------------------------------------------------------------------------- /img/spi_mode3.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/mruby/microcontroller-peripheral-interface-guide/514497cfe184edda842f4410cd0eaee1acbdfb9c/img/spi_mode3.png -------------------------------------------------------------------------------- /mruby_io_ADC_en.md: -------------------------------------------------------------------------------- 1 | # ADC 2 | 3 | - A class that supports Analog-to-Digital Conversion (ADC) functionality. 4 | - Generally, it is capable of converting analog voltage values to digital values. 5 | 6 | ## Constructor 7 | 8 | 9 | ### ADC.new( pin, *params ) 10 | 11 | - Generate an ADC object by specifying the physical pin indicated by "pin." 12 | - Typically, "pin" is specified as an integer, but alternative methods (e.g., "B1" in PIC) are also acceptable. 13 | - If the device has a switch between analog and digital modes for the pin, it will be switched to analog mode at this point. 14 | - Generally, there is no need to specify additional parameters, such as "params." However, for certain models that require additional feature specifications like sampling speed, they can be specified here. 15 | 16 | Example of use: 17 | 18 | ```ruby 19 | adc1 = ADC.new( 1 ) 20 | ``` 21 | 22 | --- 23 | 24 | ## Instance Method 25 | 26 | 27 | ### read_voltage() -> Float 28 | 29 | - Reads the value and returns the voltage value (V). 30 | 31 | Example of use: 32 | 33 | ```ruby 34 | v1 = adc1.read_voltage() 35 | ``` 36 | 37 | Note: 38 | 39 | - VM must be compiled with Float enabled. 40 | (MRBC_USE_FLOAT macro. Default ON) 41 | - If not available, NotImplementedError exception is raised. 42 | 43 | --- 44 | 45 | ### read() -> Float 46 | 47 | - Alias for read_voltage 48 | 49 | --- 50 | 51 | ### read_raw() -> Integer 52 | 53 | - Read a value and return the raw value (the value before conversion to voltage). 54 | 55 | Example of use: 56 | 57 | ```ruby 58 | v1 = adc1.read_raw() 59 | ``` 60 | -------------------------------------------------------------------------------- /mruby_io_ADC_ja.md: -------------------------------------------------------------------------------- 1 | # ADC 2 | 3 | - アナログデジタル変換機能をサポートするクラス。 4 | - 一般に、アナログ電圧値をデジタル値に変換する機能を持つ。 5 | 6 | --- 7 | 8 | ## コンストラクタ 9 | 10 | 11 | ### ADC.new( pin, *params ) 12 | 13 | - pin で示す物理ピンを指定して、ADC オブジェクトを生成する。 14 | - pin は標準的には整数で指定するが、別な方法（例えばPICでは"B1"等）があっても良い。 15 | - ピンにアナログ・デジタルモードの切り替えがある機器の場合は、このタイミングでアナログモードに切り替える。 16 | - 基本的に追加パラメータ params の指定は無いが、機種によってサンプリング速度などの追加機能指定がある場合は、ここへ指定する。 17 | 18 | 使用例 19 | 20 | ``` 21 | adc1 = ADC.new( 1 ) 22 | ``` 23 | 24 | --- 25 | 26 | ## インスタンスメソッド 27 | 28 | 29 | ### read_voltage() -> Float 30 | 31 | --- 32 | 33 | - 値を読み込み、電圧値(V)を返す。 34 | 35 | 使用例 36 | 37 | ```ruby 38 | v1 = adc1.read_voltage() 39 | ``` 40 | 41 | 備考 42 | 43 | - Floatが使用可能な状態でVMがコンパイルされている必要がある。 44 | (MRBC_USE_FLOATマクロ。デフォルトON) 45 | - 使用可能でない場合は、NotImplementedError例外が発生する。 46 | 47 | --- 48 | 49 | ### read() -> Float 50 | 51 | - read_voltage のエイリアス 52 | 53 | --- 54 | 55 | ### read_raw() -> Integer 56 | 57 | - 値を読み込み、raw値（電圧に変換前の値）を返す。 58 | 59 | 使用例 60 | 61 | ```ruby 62 | v1 = adc1.read_raw() 63 | ``` 64 | -------------------------------------------------------------------------------- /mruby_io_GPIO_en.md: -------------------------------------------------------------------------------- 1 | # GPIO 2 | 3 | - A class that supports general-purpose digital input/output functionality. 4 | - Generally, it is intended for controlling the input or output of a single physical pin. 5 | 6 | --- 7 | 8 | ## Class method 9 | 10 | 11 | ### GPIO.setmode( pin, params ) -> nil 12 | 13 | - Specify the physical pin indicated by "pin" and change the mode of the GPIO. 14 | - Refer to the constructor for other information. 15 | 16 | Example of use: 17 | 18 | ```ruby 19 | # Set pin number 1 output. 20 | GPIO.setmode( 1, GPIO::OUT ) 21 | 22 | # Set B1 pin to input, with internal pull-up. (for PIC, etc.) 23 | GPIO.setmode( "B1", GPIO::IN|GPIO::PULL_UP ) 24 | ``` 25 | 26 | --- 27 | 28 | ### read_at( pin ) -> Integer 29 | 30 | - Returns the value read from the specified pin as either 0 or 1. 31 | - When reading from the pin set for output, if the hardware permits, the actual value should be read and returned instead of the set value. 32 | 33 | Example of use: 34 | 35 | ```ruby 36 | GPIO.setmode( 1, GPIO::IN ) 37 | v1 = GPIO.read_at( 1 ) # read from pin 1. 38 | ``` 39 | 40 | --- 41 | 42 | ### high_at?( pin ) -> bool 43 | 44 | - Return true If the value read from the specified pin is high (==1) 45 | 46 | Example of use: 47 | 48 | ```ruby 49 | if GPIO.high_at?( 1 ) 50 | ``` 51 | 52 | --- 53 | 54 | ### low_at?( pin ) -> bool 55 | 56 | - If the value loaded from the specified pin is low-level (== 0), return true. 57 | 58 | Example of use: 59 | 60 | ```ruby 61 | if GPIO.low_at?( 1 ) 62 | ``` 63 | 64 | --- 65 | 66 | ### write_at( pin, integer_data ) 67 | 68 | - Output a value to the specified pin. 69 | - The value must be specified as either 0 or 1. 70 | - If the data is out of range (i.e. not 0 or 1), a RangeError will occur. 71 | 72 | Example of use: 73 | 74 | ```ruby 75 | GPIO.setmode( 1, GPIO::OUT ) 76 | GPIO.write_at( 1, 0 ) # output zero to pin 1. 77 | ``` 78 | 79 | --- 80 | 81 | ## Constructor 82 | 83 | 84 | ### GPIO.new( pin, params ) 85 | 86 | - Specify the physical pin indicated by the pin and generate a GPIO object. 87 | - At the same time, specify a param to indicate the mode, such as input/output direction. 88 | - The pin is typically specified as an integer, but other methods (such as "B1" in PIC) may be used. 89 | - Although one bit is the basic unit, pin specification that combines multiple bits may be necessary depending on the device. 90 | - Use the following constants for param and specify them connected by `|`. 91 | - IN, OUT, or HIGH_Z instruction is mandatory, and an ArgumentError will occur if it is absent. 92 | 93 | Constants: 94 | 95 | ```ruby 96 | GPIO::IN # Set as input 97 | GPIO::OUT # Set as output 98 | GPIO::HIGH_Z # Set as high impedance 99 | GPIO::PULL_UP # Enable internal pull-up 100 | GPIO::PULL_DOWN # Enable internal pull-down 101 | GPIO::OPEN_DRAIN # Set to open-drain mode 102 | ``` 103 | 104 | Usage Example 105 | 106 | ```ruby 107 | # Set GPIO pin 1 as output. 108 | gpio1 = GPIO.new(1, GPIO::OUT) 109 | 110 | # Set B1 pin as input with internal pull-up (for PIC, etc.). 111 | gpio1 = GPIO.new("B1", GPIO::IN|GPIO::PULL_UP) 112 | ``` 113 | 114 | --- 115 | 116 | ## Instance methods 117 | 118 | 119 | ### read() -> Integer 120 | 121 | - Return the loaded value as 0 or 1. 122 | - It can be any integer only when implementing multiple bit processing. 123 | - If reading from the pin set for output, the hardware should read and return the actual value if possible, not the set value. 124 | 125 | Example of use: 126 | 127 | ```ruby 128 | v1 = gpio1.read() 129 | ``` 130 | 131 | --- 132 | 133 | ### high?() -> bool 134 | 135 | - If the loaded value is high level (==1), it returns true. 136 | 137 | Example of use: 138 | 139 | ```ruby 140 | if gpio1.high?() 141 | ``` 142 | 143 | --- 144 | 145 | ### low?() -> bool 146 | 147 | If the loaded value is low-level (==0), return true. 148 | 149 | Example of use: 150 | 151 | ```ruby 152 | if gpio1.low?() 153 | ``` 154 | 155 | --- 156 | 157 | ### write( integer_data ) 158 | 159 | - Specify the value to output to the pin as either 0 or 1. 160 | - Only in the case of implementation that handles multiple bits collectively, indicate with any integer value. 161 | 162 | Example of use: 163 | 164 | ```ruby 165 | gpio1.write( 1 ) 166 | ``` 167 | 168 | --- 169 | 170 | ### setmode( param ) -> nil 171 | 172 | - Change the GPIO mode at any timing. 173 | - When IN, OUT, or HIGH_Z is specified while PULL_UP or other settings have already been set, the previous settings will be invalidated. 174 | 175 | Example of use: 176 | 177 | ```ruby 178 | # Enable internal pullup. 179 | gpio1.setmode( GPIO::PULL_UP ) 180 | 181 | # Switch to input and enable internal pullup. 182 | gpio1.setmode( GPIO::IN|GPIO::PULL_UP ) 183 | ``` 184 | -------------------------------------------------------------------------------- /mruby_io_GPIO_ja.md: -------------------------------------------------------------------------------- 1 | # GPIO 2 | 3 | - 汎用デジタル入出力機能をサポートするクラス。 4 | - 一般には、一つの物理ピンの入力もしくは出力の制御を想定している。 5 | 6 | --- 7 | 8 | ## クラスメソッド 9 | 10 | 11 | ### GPIO.setmode( pin, params ) -> nil 12 | 13 | - pin で示す物理ピンを指定して、GPIO のモードを変更する。 14 | - その他は、コンストラクタを参照。 15 | 16 | 使用例 17 | 18 | ``` 19 | # ピン番号1を出力に設定する。 20 | GPIO.setmode( 1, GPIO::OUT ) 21 | 22 | # B1ピンを入力、内部プルアップに設定する。（PIC等） 23 | GPIO.setmode( "B1", GPIO::IN|GPIO::PULL_UP ) 24 | ``` 25 | 26 | --- 27 | 28 | ### read_at( pin ) -> Integer 29 | 30 | - 指定したピンから読み込んだ値を、0または1で返す。 31 | - 出力に設定したピンに対して read する場合は、ハードウェアが許せば、設定値ではなく実際の値を読んで返すべき。 32 | 33 | 使用例 34 | 35 | ``` 36 | GPIO.setmode( 1, GPIO::IN ) 37 | v1 = GPIO.read_at( 1 ) # read from pin 1. 38 | ``` 39 | 40 | --- 41 | 42 | ### high_at?( pin ) -> bool 43 | 44 | - 指定したピンから読み込んだ値が、ハイレベル (==1) であれば、true を返す。 45 | 46 | 使用例 47 | 48 | ``` 49 | if GPIO.high_at?( 1 ) 50 | ``` 51 | 52 | --- 53 | 54 | ### low_at?( pin ) -> bool 55 | 56 | - 指定したピンから読み込んだ値が、ローレベル (==0) であれば、true を返す。 57 | 58 | 使用例 59 | 60 | ``` 61 | if GPIO.low_at?( 1 ) 62 | ``` 63 | 64 | --- 65 | 66 | ### write_at( pin, integer_data ) 67 | 68 | - 指定したピンへ値を出力する。 69 | - 値は0もしくは1で指定する。 70 | - データが範囲外の場合（通常 0と1以外）、RangeErrorになる。 71 | 72 | 使用例 73 | 74 | ``` 75 | GPIO.setmode( 1, GPIO::OUT ) 76 | GPIO.write_at( 1, 0 ) # output zero to pin 1. 77 | ``` 78 | 79 | --- 80 | 81 | ## コンストラクタ 82 | 83 | 84 | ### GPIO.new( pin, params ) 85 | 86 | - pin で示す物理ピンを指定して、GPIO オブジェクトを生成する。 87 | - 同時に param を指定して、入出力方向などのモードを指示する。 88 | - pin は標準的には整数で指定するが、別な方法（例えばPICでは"B1"等）があっても良い。 89 | - 1ビットを基本とするが、機器によっては必要に応じて複数ビットまとめたピン指定もありうる。 90 | - param は以下の定数を使い、`|`で接続して指定する。 91 | - IN, OUT もしくは HIGH_Z の指示は必須とし、無き場合は ArgumentError が発生する。 92 | 93 | 定数 94 | 95 | ``` 96 | GPIO::IN # 入力に設定する 97 | GPIO::OUT # 出力に設定する 98 | GPIO::HIGH_Z # ハイインピーダンスに設定する 99 | GPIO::PULL_UP # 内部プルアップを有効にする 100 | GPIO::PULL_DOWN # 内部プルダウンを有効にする 101 | GPIO::OPEN_DRAIN # オープンドレインモードに設定する 102 | ``` 103 | 104 | 使用例 105 | 106 | ``` 107 | # ピン番号1を出力に設定する。 108 | gpio1 = GPIO.new( 1, GPIO::OUT ) 109 | 110 | # B1ピンを入力、内部プルアップに設定する。（PIC等） 111 | gpio1 = GPIO.new( "B1", GPIO::IN|GPIO::PULL_UP ) 112 | ``` 113 | 114 | --- 115 | 116 | ## インスタンスメソッド 117 | 118 | 119 | ### read() -> Integer 120 | 121 | - 読み込んだ値を、0または1で返す。 122 | - 複数ビットまとめて扱う実装の場合のみ、任意の整数になりうる。 123 | - 出力に設定したピンに対して read する場合は、ハードウェアが許せば、設定値ではなく実際の値を読んで返すべき。 124 | 125 | 使用例 126 | 127 | ``` 128 | v1 = gpio1.read() 129 | ``` 130 | 131 | --- 132 | 133 | ### high?() -> bool 134 | 135 | - 読み込んだ値が、ハイレベル (==1) であれば、true を返す。 136 | 137 | 使用例 138 | 139 | ``` 140 | if gpio1.high?() 141 | ``` 142 | 143 | --- 144 | 145 | ### low?() -> bool 146 | 147 | - 読み込んだ値が、ローレベル (==0) であれば、true を返す。 148 | 149 | 使用例 150 | 151 | ``` 152 | if gpio1.low?() 153 | ``` 154 | 155 | --- 156 | 157 | ### write( integer_data ) 158 | 159 | - ピンへ出力する値を0もしくは1で指定する。 160 | - 複数ビットまとめて扱う実装の場合のみ、任意の整数で指示する。 161 | 162 | 使用例 163 | 164 | ``` 165 | gpio1.write( 1 ) 166 | ``` 167 | 168 | --- 169 | 170 | ### setmode( param ) -> nil 171 | 172 | - GPIOのモードを任意のタイミングで変更する。 173 | - 既に PULL_UP 等が設定されている時に IN,OUT もしくは HIGH_Z が指定された場合は、PULL_UP 等の設定は無効化される。 174 | 175 | 使用例 176 | 177 | ```ruby 178 | # 内部プルアップを有効にする 179 | gpio1.setmode( GPIO::PULL_UP ) 180 | 181 | # 入力に切り替え、内部プルアップを有効にする。 182 | gpio1.setmode( GPIO::IN|GPIO::PULL_UP ) 183 | ``` 184 | -------------------------------------------------------------------------------- /mruby_io_I2C_en.md: -------------------------------------------------------------------------------- 1 | # I2C 2 | 3 | - A class that supports I2C bus. 4 | - This specification supports only master devices with 7-bit addresses. 5 | - Define two types of methods: convenience methods, which are easy to use, and low-level methods, which provide detailed control. 6 | - The low-level methods should be implemented on an as-needed basis, since it is unlikely that they will be needed in most cases. 7 | 8 | --- 9 | 10 | ## Constructor 11 | 12 | 13 | ### I2C.new( id=nil, *params ) 14 | 15 | - Generates an I2C object by specifying the physical unit indicated by "id." 16 | - "id" can be omitted when there is only one physical unit. 17 | 18 | Optional Parameters 19 | 20 | | param | type | description | 21 | | --- | --- | --- | 22 | | frequency | Integer | Frequency (default 100kHz) | 23 | | freq | (Same as above) | | 24 | | scl_pin | --- | SCL pin specification | 25 | | sda_pin | --- | SDA pin specification | 26 | 27 | Example of use: 28 | 29 | ```ruby 30 | # Generate an I2C object with the default settings. 31 | i2c = I2C.new() 32 | 33 | # Use an I2C device of unit 1 with a frequency of 400kHz. 34 | i2c = I2C.new(1, frequency:400_000 ) # 400kHz 35 | ``` 36 | 37 | Device-specific 38 | 39 | - Not all parameters may be supported. 40 | 41 | --- 42 | 43 | ## Instance Methods 44 | 45 | 46 | ### read( i2c_adrs_7, read_bytes, *param ) -> String 47 | 48 | - Reads data of read_bytes bytes from the device with the address i2c_adrs_7. 49 | - If the device returns NAK in the middle, a String of shorter length than read_bytes may be returned. 50 | - If data is specified in the param, it will be output before the repeated start, and then reading will start. 51 | - Output specifications are the same as for write(). 52 | 53 | Example of use: 54 | 55 | ```ruby 56 | s = i2c.read( 0x45, 3 ) # case 1 57 | s = i2c.read( 0x45, 3, 0xf3, 0x2d ) # case 2 58 | ``` 59 | 60 | I2C bus sequence 61 | 62 | ``` 63 | (case 1) S -- adrs(45) R A -- data1 A -- data2 A -- data3 A|N -- P 64 | (case 2) S -- adrs(45) W A -- out1(f3) A -- out2(2d) A -- Sr -- adrs(45) R A -- data1 A -- data2 A -- data3 N -- P 65 | S : Start condition 66 | P : Stop condition 67 | Sr: Repeated start condition 68 | A : Ack 69 | N : Nack 70 | R : Read bit 71 | W : Write bit 72 | ``` 73 | 74 | --- 75 | 76 | ### write( i2c_adrs_7 , *outputs ) -> Integer 77 | 78 | - Writes data specified in outputs to the device with the address i2c_adrs_7. 79 | - The number of bytes successfully written is returned as the return value. 80 | - outputs can be specified as an Integer, Array, or String. 81 | 82 | Example of use: 83 | 84 | ```ruby 85 | i2c.write( 0x45, 0x30, 0xa2 ) 86 | i2c.write( 0x50, 0x00, 0x80, data_string ) # useful for EEPROM 87 | i2c.write( 0x11, [0x30, 0xa2] ) 88 | ``` 89 | 90 | I2C Sequence 91 | 92 | ``` 93 | S -- adrs W A -- data_1 A -- ... -- data_n N -- P 94 | S : Start condition 95 | P : Stop condition 96 | A : Ack 97 | N : Nack 98 | W : Write bit 99 | ``` 100 | 101 | --- 102 | 103 | ### send_start() 104 | 105 | - Low level method. 106 | - Outputs a StartCondition to the I2C bus. 107 | 108 | Example of use: 109 | 110 | ```ruby 111 | i2c.send_start 112 | ``` 113 | 114 | --- 115 | 116 | ### send_restart() 117 | 118 | - Low level method. 119 | - Outputs a Restart (RepeatedStart) Condition to the I2C bus. 120 | 121 | Example of use: 122 | 123 | ```ruby 124 | i2c.send_restart 125 | ``` 126 | 127 | --- 128 | 129 | ### send_stop() 130 | 131 | - Low level method. 132 | - Outputs a StopCondition to the I2C bus. 133 | 134 | Example of use: 135 | 136 | ```ruby 137 | i2c.send_stop 138 | ``` 139 | 140 | --- 141 | 142 | ### raw_read( read_bytes, ack_nack = false ) -> String 143 | 144 | - Low level method. 145 | - Reads read_bytes bytes from the I2C bus and returns them. 146 | - ack_nack = true outputs ACK at the last byte reading, and false outputs NACK. 147 | 148 | Example of use: 149 | 150 | ```ruby 151 | str = i2c.raw_read( 20 ) 152 | ``` 153 | 154 | --- 155 | 156 | ### raw_write( *outputs ) -> Integer 157 | 158 | - Low level method. 159 | - Writes data specified in outputs to the I2C bus. 160 | - The number of bytes successfully written is returned as the return value. 161 | - outputs can be specified as an Integer, Array, or String. 162 | 163 | Example of use: 164 | 165 | ```ruby 166 | i2c.raw_write( 0x45, 0x30, 0xa2 ) 167 | ``` 168 | -------------------------------------------------------------------------------- /mruby_io_I2C_ja.md: -------------------------------------------------------------------------------- 1 | # I2C 2 | 3 | - I2C バスをサポートするクラス。 4 | - この仕様書ではマスターデバイス、7ビットアドレスのみをサポートしている。 5 | - 容易に使う事ができるコンビニエンスメソッドと、細かな制御ができる低レベルメソッドを定義する。 6 | - 低レベルメソッドは、ほとんどの場合必要ないと思われるので、必要に応じて実装すれば良い。 7 | 8 | --- 9 | 10 | ## コンストラクタ 11 | 12 | 13 | ### I2C.new( id=nil, *params ) 14 | 15 | - id で示す物理ユニットを指定して、I2C オブジェクトを生成する。 16 | - 物理ユニットが１つしか無い場合などは、idは省略可能とする。 17 | 18 | オプションパラメータ 19 | 20 | | param | type | description | 21 | | --- | --- | --- | 22 | | frequency | Integer | 周波数 (デフォルト 100kHz) | 23 | | freq | 同上 | | 24 | | scl_pin | --- | クロックピンの指定 | 25 | | sda_pin | --- | データピンの指定 | 26 | 27 | 使用例 28 | 29 | ```ruby 30 | # デフォルトの設定で、i2cオブジェクトを生成する。 31 | i2c = I2C.new() 32 | 33 | # ユニット1 の I2C デバイスを、周波数 400kHz で使う。 34 | i2c = I2C.new(1, frequency:400_000 ) # 400kHz 35 | ``` 36 | 37 | 機種依存 38 | 39 | - 全てのパラメータがサポートされているとは限らない。 40 | 41 | --- 42 | 43 | ## インスタンスメソッド 44 | 45 | 46 | ### read( i2c_adrs_7, read_bytes, *param ) -> String 47 | 48 | - i2c_adrs_7 アドレスのデバイスから、read_bytes バイトのデータを読み込む。 49 | - デバイスが途中で NAK を返す場合は、read_bytes より短い長さの String が返る可能性がある。 50 | - param にデータが指定されていれば、それを出力してからリピーテッドスタートを挟み読み込みを始める。 51 | - 出力の仕様は、write() を参照。 52 | 53 | 使用例 54 | 55 | ```ruby 56 | s = i2c.read( 0x45, 3 ) # case 1 57 | s = i2c.read( 0x45, 3, 0xf3, 0x2d ) # case 2 58 | ``` 59 | 60 | I2C bus sequence 61 | 62 | ``` 63 | (case 1) S -- adrs(45) R A -- data1 A -- data2 A -- data3 A|N -- P 64 | (case 2) S -- adrs(45) W A -- out1(f3) A -- out2(2d) A -- Sr -- adrs(45) R A -- data1 A -- data2 A -- data3 N -- P 65 | S : Start condition 66 | P : Stop condition 67 | Sr: Repeated start condition 68 | A : Ack 69 | N : Nack 70 | R : Read bit 71 | W : Write bit 72 | ``` 73 | 74 | --- 75 | 76 | ### write( i2c_adrs_7 , *outputs ) -> Integer 77 | 78 | - i2c_adrs_7 アドレスのデバイスに、outputs で指定したデータを書き込む。 79 | - 書き込みできたバイト数が戻り値として返る。 80 | - outputsは、Integer, Array\ および String で指定する。 81 | 82 | 使用例 83 | 84 | ```ruby 85 | i2c.write( 0x45, 0x30, 0xa2 ) 86 | i2c.write( 0x50, 0x00, 0x80, data_string ) # useful for EEPROM 87 | i2c.write( 0x11, [0x30, 0xa2] ) 88 | ``` 89 | 90 | I2C Sequence 91 | 92 | ``` 93 | S -- adrs W A -- data_1 A -- ... -- data_n N -- P 94 | S : Start condition 95 | P : Stop condition 96 | A : Ack 97 | N : Nack 98 | W : Write bit 99 | ``` 100 | 101 | --- 102 | 103 | ### send_start() 104 | 105 | - Low level method. 106 | - I2Cバスに StartCondition を出力する。 107 | 108 | 使用例 109 | 110 | ```ruby 111 | i2c.send_start 112 | ``` 113 | 114 | --- 115 | 116 | ### send_restart() 117 | 118 | - Low level method. 119 | - I2Cバスに Restart (RepeatedStart) Condition を出力する。 120 | 121 | 使用例 122 | 123 | ```ruby 124 | i2c.send_restart 125 | ``` 126 | 127 | --- 128 | 129 | ### send_stop() 130 | 131 | - Low level method. 132 | - I2Cバスに StopCondition を出力する。 133 | 134 | 使用例 135 | 136 | ```ruby 137 | i2c.send_stop 138 | ``` 139 | 140 | --- 141 | 142 | ### raw_read( read_bytes, ack_nack = false ) -> String 143 | 144 | - Low level method. 145 | - I2Cバスから read_bytes バイト読み込んで返す。 146 | - ack_nack = true で最後のバイト読み込み時に ACK を、false で NACK 出力する。 147 | 148 | 使用例 149 | 150 | ```ruby 151 | str = i2c.raw_read( 20 ) 152 | ``` 153 | 154 | --- 155 | 156 | ### raw_write( *outputs ) -> Integer 157 | 158 | - Low level method. 159 | - I2Cバスへ outputs で指定したデータを書き込む。 160 | - 書き込みできたバイト数が戻り値として返る。 161 | - outputsは、Integer, Array\ および String で指定する。 162 | 163 | 使用例 164 | 165 | ```ruby 166 | i2c.raw_write( 0x45, 0x30, 0xa2 ) 167 | ``` 168 | -------------------------------------------------------------------------------- /mruby_io_PWM_en.md: -------------------------------------------------------------------------------- 1 | # PWM 2 | 3 | - A class that supports Pulse Width Modulation (PWM) functionality. 4 | 5 | --- 6 | 7 | ## Constructor 8 | 9 | 10 | ### PWM.new( pin, *params ) 11 | 12 | - Generate a PWM object by specifying the physical pin indicated by "pin." 13 | - Typically, "pin" is specified as an integer, but alternative methods (e.g., "B1" in PIC) are also acceptable. 14 | - When specifying the parameter frequency, the output starts with a duty cycle of 50%. 15 | - If you want to start the output with a duty cycle other than 50%, specify the parameter duty simultaneously. 16 | 17 | Optional Parameters 18 | 19 | | param | type | description | 20 | | --- | --- | --- | 21 | | frequency | Integer,Float | Specifies the frequency. | 22 | | freq | (Same as above) | | 23 | | duty | Integer,Float | Specifies the duty cycle. | 24 | 25 | Example of use: 26 | 27 | ```ruby 28 | # Generate an object for PWM output on pin 1. Output is not started yet. 29 | pwm1 = PWM.new( 1 ) 30 | 31 | # Generate an object for PWM output on pin 1 and start the output with a frequency of 440Hz and a duty cycle of 30%. 32 | pwm1 = PWM.new( 1, frequency:440, duty:30 ) 33 | ``` 34 | 35 | Device-specific 36 | 37 | - Additional parameters such as unit names may be required. 38 | 39 | --- 40 | 41 | ## Instance Methods 42 | 43 | 44 | ### frequency( freq ) 45 | 46 | - Starts the output or changes the frequency by specifying the frequency. 47 | - freq is specified as an Integer or Float. 48 | - Specifying 0 stops the output. 49 | - Changing the frequency does not affect the duty cycle. 50 | 51 | Example of use: 52 | 53 | ```ruby 54 | pwm1.frequency( 440 ) # Output at 440Hz 55 | ``` 56 | 57 | Device-specific 58 | 59 | - The maximum and minimum frequencies and resolutions depend on the device. 60 | - When stopping the output, it is desirable to stop it at LowLevel. 61 | - Whether to stop at the middle of a cycle (become LowLevel) or after the output of that cycle is complete when stopping the output is device-specific. 62 | 63 | --- 64 | 65 | ### period_us( micro_sec ) 66 | 67 | - Starts the output or changes the period by specifying the time of one cycle in microseconds. 68 | - micro_sec is specified as an Integer. 69 | - Specifying 0 stops the output. 70 | - Changing the period does not affect the duty cycle. 71 | 72 | Example of use: 73 | 74 | ```ruby 75 | pwm1.period_us( 2273 ) # 1/2273us = 440Hz 76 | ``` 77 | 78 | --- 79 | 80 | ### duty( percent ) 81 | 82 | - Changes the duty cycle by specifying a percentage from 0 to 100. 83 | - percent is specified as an Integer or Float. 84 | 85 | Example of use: 86 | 87 | ```ruby 88 | pwm1.duty( 50 ) 89 | ``` 90 | 91 | --- 92 | 93 | ### pulse_width_us( micro_sec ) 94 | 95 | - Specifies the time in microseconds for which the output stays ON in one cycle. 96 | - micro_sec is specified as an Integer. 97 | - If a time longer than one cycle is specified, it will be set to the maximum value that can be ON without an error. 98 | 99 | Example of use: 100 | 101 | ```ruby 102 | pwm1.pulse_width_us( 1000 ) 103 | ``` 104 | -------------------------------------------------------------------------------- /mruby_io_PWM_ja.md: -------------------------------------------------------------------------------- 1 | # PWM 2 | 3 | - パルス幅変調機能をサポートするクラス。 4 | 5 | --- 6 | 7 | ## コンストラクタ 8 | 9 | 10 | ### PWM.new( pin, *params ) 11 | 12 | - pin で示す物理ピンを指定して、PWM オブジェクトを生成する。 13 | - pin は標準的には整数で指定するが、別な方法（例えばPICでは"B1"等）があっても良い。 14 | - パラメータ `frequency` を指定すると、デューティー比50%で出力を開始する。 15 | - デューティー比50%以外で出力を開始したい場合には、パラメータ `duty` を同時に指定する。 16 | 17 | オプションパラメータ 18 | 19 | | param | type | description | 20 | | --- | --- | --- | 21 | | frequency | Integer,Float | 周波数の指定。 | 22 | | freq | 同上 | | 23 | | duty | Integer,Float | デューティー比の指定 | 24 | 25 | 使用例 26 | 27 | ```ruby 28 | # 1番ピンをPWM出力用としてオブジェクトを生成する。まだ出力はしない。 29 | pwm1 = PWM.new( 1 ) 30 | 31 | # 1番ピンをPWM出力用としてオブジェクトを生成するとともに、周波数 440Hz デューティー比 30% で出力を開始する。 32 | pwm1 = PWM.new( 1, frequency:440, duty:30 ) 33 | ``` 34 | 35 | 機器依存 36 | 37 | - ユニット名などの追加パラメータが必要になる可能性がある。 38 | 39 | --- 40 | 41 | ## インスタンスメソッド 42 | 43 | 44 | ### frequency( freq ) 45 | 46 | - 周波数を指定して出力を開始、もしくは周波数を変更する。 47 | - freq は、Integer もしくは Float で指定する。 48 | - 0を指定すると、出力を停止する。 49 | - 周波数を変更してもデューティー比は変更されない。 50 | 51 | 使用例 52 | 53 | ```ruby 54 | pwm1.frequency( 440 ) # 440Hzの出力 55 | ``` 56 | 57 | 機種依存 58 | 59 | - 最大、最小周波数や分解能は機種に依存する。 60 | - 出力停止時は、LowLevelで停止が望ましい。 61 | - 出力停止を指示した時に、周期の途中で停止する（LowLevelになる）か、その周期の出力が終わってから停止するかは機種に依存する。 62 | 63 | --- 64 | 65 | ### period_us( micro_sec ) 66 | 67 | - １周期の時間（マイクロ秒）を指定して出力を開始、もしくは周期を変更する。 68 | - micro_sec は、Integerで指定する。 69 | - 0を指定すると、出力を停止する。 70 | - 周期を変更してもデューティー比は変更されない。 71 | 72 | 使用例 73 | 74 | ```ruby 75 | pwm1.period_us( 2273 ) # 1/2273us = 440Hz 76 | ``` 77 | 78 | --- 79 | 80 | ### duty( percent ) 81 | 82 | - 0から100までのパーセンテージを指定してデューティー比を変更する。 83 | - percentは、Integer もしくは Float で指定する。 84 | 85 | 使用例 86 | 87 | ```ruby 88 | pwm1.duty( 50 ) 89 | ``` 90 | 91 | --- 92 | 93 | ### pulse_width_us( micro_sec ) 94 | 95 | - １周期のONになる時間をマイクロ秒で指定する。 96 | - micro_sec は、Integerで指定する。 97 | - １周期よりも長い時間を指定された場合、最大のONにできる値で設定されエラーにはならない。 98 | 99 | 使用例 100 | 101 | ```ruby 102 | pwm1.pulse_width_us( 1000 ) 103 | ``` 104 | -------------------------------------------------------------------------------- /mruby_io_SPI_en.md: -------------------------------------------------------------------------------- 1 | # SPI 2 | 3 | - A class that supports SPI bus. 4 | - This specification defines only master devices and transfers in 8-bit units. 5 | - The Chip Select (CS/SS) will be managed using GPIO functionality and is not defined within the SPI class. 6 | 7 | --- 8 | 9 | ## Constructor 10 | 11 | 12 | ### SPI.new( id=nil, *params ) 13 | 14 | - Generates an SPI object by specifying the physical unit indicated by "id." 15 | - "id" can be omitted when there is only one physical unit. 16 | 17 | Optional Parameters 18 | 19 | | param | type | description | 20 | | --- | --- | --- | 21 | | unit | --- | Specification of the SPI unit | 22 | | frequency | Integer | Frequency (default 1MHz) | 23 | | mode | Integer | 0 to 3 (default 0) | 24 | | first_bit | Constant | SPI::MSB_FIRST or SPI::LSB_FIRST (default MSB_FIRST) | 25 | 26 | Example of use: 27 | 28 | ```ruby 29 | # Generate an SPI object with the default settings. 30 | spi = SPI.new() 31 | 32 | # Use sn SPI device of unit 1 with a frequency of 10MHz. 33 | spi = SPI.new( unit:1, frequency:10_000_000 ) 34 | ``` 35 | 36 | mode parameter 37 | 38 | | mode | CPOL | CPHA | Idle state clock polarity | Sampling timing | | 39 | |:----:|:----:|:----:|:-------------------------:|:---------------:|-| 40 | | 0 | 0 | 0 | Low | Rising edge |![mode0](img/spi_mode0.png)| 41 | | 1 | 0 | 1 | Low | Falling edge |![mode1](img/spi_mode1.png)| 42 | | 2 | 1 | 0 | High | Falling edge |![mode2](img/spi_mode2.png)| 43 | | 3 | 1 | 1 | High | Rising edge |![mode3](img/spi_mode3.png)| 44 | 45 | 46 | Device-specific 47 | 48 | - Not all parameters may be supported. 49 | 50 | --- 51 | 52 | ## Instance Methods 53 | 54 | 55 | ### setmode( *params ) 56 | 57 | - Changes the operating mode (parameters) of the SPI. 58 | - The parameters are specified according to the constructor. 59 | 60 | Example of use: 61 | 62 | ```ruby 63 | spi.setmode( mode:3 ) 64 | ``` 65 | 66 | --- 67 | 68 | ### read( read_bytes ) -> String 69 | 70 | - Reads data of read_bytes bytes from the SPI bus. 71 | - At the same time, data will be output as 0. 72 | 73 | Example of use: 74 | 75 | ```ruby 76 | data = spi.read( 32 ) 77 | ``` 78 | 79 | --- 80 | 81 | ### write( *outputs ) -> nil 82 | 83 | - Outputs data specified in outputs to the SPI bus. 84 | - outputs can be specified as an Integer, Array, or String. 85 | 86 | Example of use: 87 | 88 | ```ruby 89 | spi.write( 0x30, 0xa2 ) 90 | spi.write( "\x30\xa2" ) 91 | spi.write( 0x02, 0xee, 0xad, 0x00, data_string ) # useful for EEPROM 92 | ``` 93 | 94 | --- 95 | 96 | ### transfer( outputs, additional_read_bytes = 0 ) -> String 97 | 98 | - Outputs data specified in outputs to the SPI bus while simultaneously reading data (General-purpose transfer). 99 | - outputs can be specified as an Integer, Array, or String. 100 | - If additional_read_bytes is specified, it will output 0x00 after the outputs. 101 | 102 | Example of use: 103 | 104 | ```ruby 105 | s = spi.transfer( 0b0000_0101, 1 ) # s will return a 2-byte String 106 | ``` 107 | -------------------------------------------------------------------------------- /mruby_io_SPI_ja.md: -------------------------------------------------------------------------------- 1 | # SPI 2 | 3 | - SPI バスをサポートするクラス。 4 | - この仕様書ではマスターデバイス、8bit 単位の転送のみ規定する。 5 | - チップセレクト SS はGPIO機能を使う事とし、SPIクラスでは規定しない。 6 | 7 | --- 8 | 9 | ## コンストラクタ 10 | 11 | 12 | ### SPI.new( id=nil, *params ) 13 | 14 | - id で示す物理ユニットを指定して、SPI オブジェクトを生成する。 15 | - 物理ユニットが１つしか無い場合などは、idは省略可能とする。 16 | 17 | オプションパラメータ 18 | 19 | | param | type | description | 20 | | --- | --- | --- | 21 | | unit | --- | SPIユニットの指定 | 22 | | frequency | Integer | 周波数 (default 1MHz) | 23 | | mode | Integer | 0 to 3 (default 0) | 24 | | first_bit | Constant | SPI::MSB_FIRST or SPI::LSB_FIRST (default MSB_FIRST) | 25 | 26 | 使用例 27 | 28 | ```ruby 29 | # デフォルトの設定で、spiオブジェクトを生成する。 30 | spi = SPI.new() 31 | 32 | # ユニット1 の SPI デバイスを、周波数 10MHz で使う。 33 | spi = SPI.new( unit:1, frequency:10_000_000 ) 34 | ``` 35 | 36 | モードパラメータ 37 | 38 | | mode | CPOL | CPHA | Idle state clock polarity | Sampling timing | | 39 | |:----:|:----:|:----:|:-------------------------:|:---------------:|-| 40 | | 0 | 0 | 0 | Low | Rising edge |![mode0](img/spi_mode0.png)| 41 | | 1 | 0 | 1 | Low | Falling edge |![mode1](img/spi_mode1.png)| 42 | | 2 | 1 | 0 | High | Falling edge |![mode2](img/spi_mode2.png)| 43 | | 3 | 1 | 1 | High | Rising edge |![mode3](img/spi_mode3.png)| 44 | 45 | 46 | 機種依存 47 | 48 | - 全てのパラメータがサポートされているとは限らない。 49 | 50 | --- 51 | 52 | ## インスタンスメソッド 53 | 54 | 55 | ### setmode( *params ) 56 | 57 | - SPI の動作モード（パラメータ）を変更する。 58 | - パラメータの指定は、コンストラクタに準拠する。 59 | 60 | 使用例 61 | 62 | ```ruby 63 | spi.setmode( mode:3 ) 64 | ``` 65 | 66 | --- 67 | 68 | ### read( read_bytes ) -> String 69 | 70 | - SPIバスから read_bytes バイトのデータを読み込む。 71 | - 同時に出力されるデータは、0が出力される。 72 | 73 | 使用例 74 | 75 | ```ruby 76 | data = spi.read( 32 ) 77 | ``` 78 | 79 | --- 80 | 81 | ### write( *outputs ) -> nil 82 | 83 | - SPIバスへ、outputs で指定したデータを出力する。 84 | - outputsは、Integer, Array\ もしくは String で指定する。 85 | 86 | 使用例 87 | 88 | ```ruby 89 | spi.write( 0x30, 0xa2 ) 90 | spi.write( "\x30\xa2" ) 91 | spi.write( 0x02, 0xee, 0xad, 0x00, data_string ) # useful for EEPROM 92 | ``` 93 | 94 | --- 95 | 96 | ### transfer( outputs, additional_read_bytes = 0 ) -> String 97 | 98 | - SPIバスへ outputs で指定したデータを出力しながら同時に入力する（汎用転送） 99 | - outputs は、Integer, Array\ もしくは String で指定する。 100 | - additional_read_bytes を指定すると、そのバイト数分の 0x00 を output に続いて出力する。 101 | 102 | 使用例 103 | 104 | ```ruby 105 | s = spi.transfer( 0b0000_0101, 1 ) # s は 2バイトの String が返る 106 | ``` 107 | -------------------------------------------------------------------------------- /mruby_io_UART_en.md: -------------------------------------------------------------------------------- 1 | # UART 2 | 3 | - A class that supports asynchronous serial communication. 4 | 5 | --- 6 | 7 | ## Constructor 8 | 9 | 10 | ### UART.new( id=nil, *params ) 11 | 12 | - Generates a UART object by specifying the physical unit indicated by "id." 13 | - The default parameter values follow the settings below if possible. 14 | - Baud rate: 9600 15 | - Data bits: 8 bits 16 | - Stop bits: 1 bit 17 | - Parity: None 18 | - Flow control: None 19 | 20 | Optional Parameters 21 | 22 | | param | type | description | 23 | | --- | --- | --- | 24 | | baudrate | Integer | Baud rate (default 9600) | 25 | | baud | (Same as above) | | 26 | | data_bits | Integer | Data bits (default 8) | 27 | | stop_bits | Integer | Stop bits (default 1) | 28 | | parity | Const | Parity bit (default NONE) | 29 | | flow_control | Const | Flow control (default NONE) | 30 | | unit | --- | Specifies the unit (same as parameter "id") | 31 | | txd_pin | --- | Specifies the TxD pin | 32 | | rxd_pin | --- | Specifies the RxD pin | 33 | | rts_pin | --- | Specifies the RTS pin | 34 | | cts_pin | --- | Specifies the CTS pin | 35 | 36 | Parameter Constants 37 | 38 | ```ruby 39 | UART::NONE 40 | UART::EVEN 41 | UART::ODD 42 | UART::RTSCTS 43 | ``` 44 | 45 | Example of use: 46 | 47 | ```ruby 48 | # Use UART1 with all default parameters. 49 | uart1 = UART.new( 1 ) 50 | 51 | # Use the serial device with the specified device node at 19200 bps, even parity. 52 | uart2 = UART.new("/dev/cu.usbserial1", baud:19200, parity:UART::EVEN ) 53 | ``` 54 | 55 | Device-specific 56 | 57 | - Not all parameters may be supported. 58 | 59 | --- 60 | 61 | ## Instance Methods 62 | 63 | 64 | ### setmode( *params ) 65 | 66 | - Changes the mode (parameters) of UART. 67 | - The parameter specification follows that of the constructor. 68 | 69 | Example of use: 70 | 71 | ```ruby 72 | uart1.setmode( baudrate:38400 ) 73 | ``` 74 | 75 | --- 76 | 77 | ### read( read_bytes ) -> String 78 | 79 | - Reads data of the specified number of bytes, read_bytes. 80 | - If the specified number of bytes has not arrived, it will block until they arrive. 81 | 82 | Example of use: 83 | 84 | ```ruby 85 | val = uart1.read( 10 ) 86 | ``` 87 | 88 | Note 89 | 90 | - If you do not want to block, you can check the number of bytes that can be read in advance using the bytes_available method. 91 | 92 | --- 93 | 94 | ### write( string ) -> Integer 95 | 96 | - Sends data. 97 | - Returns the number of bytes sent. 98 | 99 | Example of use: 100 | 101 | ```ruby 102 | uart1.write("Output string\r\n") 103 | ``` 104 | 105 | Device-specific 106 | 107 | - Depending on the low-level library or hardware FIFO used, the method may return before all data has been sent. 108 | - If there is a transmission buffer, and all data can be stored in the buffer, it probably won't block. 109 | 110 | --- 111 | 112 | ### gets() -> String 113 | 114 | - Reads a line of string. Internally, it returns the byte sequence until "\n" in the read buffer. 115 | - If a complete line of data has not arrived, it will block until it arrives. 116 | 117 | Example of use: 118 | 119 | ```ruby 120 | val = uart1.gets() 121 | ``` 122 | 123 | Note 124 | 125 | - If you do not want to block, you can check if reading a line is possible in advance using the can_read_line method. 126 | - The maximum character length depends on the size of the read buffer. If the buffer becomes full with data that does not contain a newline character, it will not be possible to read using gets. 127 | 128 | --- 129 | 130 | ### puts( string ) -> nil 131 | 132 | - Sends one line and sends a newline code at the end of the argument string. 133 | - The newline code is LF only by default. 134 | 135 | Example of use: 136 | 137 | ```ruby 138 | uart1.puts("Output string") 139 | ``` 140 | 141 | --- 142 | 143 | ### bytes_available() -> Integer 144 | 145 | - Returns the number of readable bytes in the read buffer. 146 | 147 | Example of use: 148 | 149 | ```ruby 150 | len = uart1.bytes_available() 151 | ``` 152 | 153 | --- 154 | 155 | ### bytes_to_write() -> Integer 156 | 157 | - Returns the number of bytes of data in the transmission buffer that have not been actually sent. 158 | 159 | Example of use: 160 | 161 | ```ruby 162 | bytes = uart1.bytes_to_write() 163 | ``` 164 | 165 | Note 166 | 167 | - For devices without a buffer, this function always returns 0. 168 | 169 | --- 170 | 171 | ### can_read_line() -> bool 172 | 173 | - Returns true if reading a line of data is possible. 174 | 175 | Example of use: 176 | 177 | ```ruby 178 | flag = uart1.can_read_line() 179 | ``` 180 | 181 | --- 182 | 183 | ### flush() 184 | 185 | - Block until transmission of data accumulated in the transmission buffer is completed. 186 | 187 | Example of use: 188 | 189 | ```ruby 190 | uart1.flush() 191 | ``` 192 | 193 | --- 194 | 195 | ### clear_rx_buffer() 196 | 197 | - Clears the receive buffer. 198 | 199 | Example of use: 200 | 201 | ```ruby 202 | uart1.clear_rx_buffer() 203 | ``` 204 | 205 | --- 206 | 207 | ### clear_tx_buffer() 208 | 209 | - Clears the transmission buffer. 210 | 211 | Example of use: 212 | 213 | ```ruby 214 | uart1.clear_tx_buffer() 215 | ``` 216 | 217 | --- 218 | 219 | ### send_break( time ) 220 | 221 | - Sends a break signal. 222 | - The time is optional and specified in seconds. 223 | 224 | Example of use: 225 | 226 | ```ruby 227 | uart1.send_break( 0.1 ) 228 | ``` 229 | 230 | Device-specific 231 | 232 | - Depending on the hardware, time may be fixed (e.g., 12 bits) and cannot be changed. 233 | -------------------------------------------------------------------------------- /mruby_io_UART_ja.md: -------------------------------------------------------------------------------- 1 | # UART 2 | 3 | - 非同期シリアル通信をサポートするクラス。 4 | 5 | --- 6 | 7 | ## コンストラクタ 8 | 9 | 10 | ### UART.new( id=nil, *params ) 11 | 12 | - id で示す物理ユニットを指定して、UART オブジェクトを生成する。 13 | - パラメータデフォルト値は、可能であれば以下の設定に従う。 14 | - ボーレート 9600 15 | - データ8ビット 16 | - ストップビット1ビット 17 | - パリティー無し 18 | - フロー制御無し 19 | 20 | オプションパラメータ 21 | 22 | | param | type | description | 23 | | --- | --- | --- | 24 | | baudrate | Integer | ボーレート (default 9600) | 25 | | baud | 同上 | | 26 | | data_bits | Integer | データビット (default 8) | 27 | | stop_bits | Integer | ストップビット (default 1) | 28 | | parity | Const | パリティービット (default NONE) | 29 | | flow_control | Const | フロー制御 (default NONE) | 30 | | unit | --- | ユニットの指定（パラメータidと同じ） | 31 | | txd_pin | --- | TxDピンの指定 | 32 | | rxd_pin | --- | RxDピンの指定 | 33 | | rts_pin | --- | RTSピンの指定 | 34 | | cts_pin | --- | CTSピンの指定 | 35 | 36 | パラメータ用定数 37 | 38 | ```ruby 39 | UART::NONE 40 | UART::EVEN 41 | UART::ODD 42 | UART::RTSCTS 43 | ``` 44 | 45 | 実行例 46 | 47 | ```ruby 48 | # UART1を、全てデフォルトパラメータで使う。 49 | uart1 = UART.new( 1 ) 50 | 51 | # 指定したデバイスノードを持つシリアルデバイスを、19200bps 偶数パリティーで使う。 52 | uart2 = UART.new("/dev/cu.usbserial1", baud:19200, parity:UART::EVEN ) 53 | ``` 54 | 55 | 機種依存 56 | 57 | - 全てのパラメータがサポートされているとは限らない。 58 | 59 | --- 60 | 61 | ## インスタンスメソッド 62 | 63 | 64 | ### setmode( *params ) 65 | 66 | - UARTのモード（パラメータ）を変更する。 67 | - パラメータの指定は、コンストラクタに準拠する。 68 | 69 | 実行例 70 | 71 | ```ruby 72 | uart1.setmode( baudrate:38400 ) 73 | ``` 74 | 75 | --- 76 | 77 | ### read( read_bytes ) -> String 78 | 79 | - read_bytes で指定されたバイト数のデータを読み込む。 80 | - 指定されたバイト数のデータが到着していない場合は、到着までブロックする。 81 | 82 | 実行例 83 | 84 | ```ruby 85 | val = uart1.read( 10 ) 86 | ``` 87 | 88 | ノート 89 | 90 | - ブロックさせたくない場合は、あらかじめ `bytes_available` メソッドで読み込むことができるバイト数を確認できる。 91 | 92 | --- 93 | 94 | ### write( string ) -> Integer 95 | 96 | - データを送信する。 97 | - 送信したバイト数を返す。 98 | 99 | 実行例 100 | 101 | ```ruby 102 | uart1.write("Output string\r\n") 103 | ``` 104 | 105 | 機種依存 106 | 107 | - 利用する低レイヤーライブラリやハードウェアFIFOなどにより、全データの送信完了を待たずに戻る場合がある。 108 | - 送信バッファがあり、全データがバッファへ格納できる場合は、ブロックしないだろう。 109 | 110 | --- 111 | 112 | ### gets() -> String 113 | 114 | - 文字列を一行読み込む。内部的にはリードバッファ内の "\n" までのバイト列を返す。 115 | - 1行のデータが到着していない場合は、到着までブロックする。 116 | 117 | 実行例 118 | 119 | ```ruby 120 | val = uart1.gets() 121 | ``` 122 | 123 | ノート 124 | 125 | - ブロックさせたくない場合は、あらかじめ `can_read_line` メソッドで行読み込みが可能かを確認できる。 126 | - 最大文字長はリードバッファのサイズに左右され、改行文字が入らないデータでバッファフルになった場合、gets で読み込むことはできないだろう。 127 | 128 | --- 129 | 130 | ### puts( string ) -> nil 131 | 132 | - 1行送信し、引数 string が改行で終わっていない場合は改行コードを送信する。 133 | - 改行コードは、デフォルトでは LF のみ。 134 | 135 | 実行例 136 | 137 | ```ruby 138 | uart1.puts("Output string") 139 | ``` 140 | 141 | --- 142 | 143 | ### bytes_available() -> Integer 144 | 145 | - リードバッファに到着している読み込み可能バイト数を返す。 146 | 147 | 実行例 148 | 149 | ```ruby 150 | len = uart1.bytes_available() 151 | ``` 152 | 153 | --- 154 | 155 | ### bytes_to_write() -> Integer 156 | 157 | - 送信バッファに溜まっており、実際に出力されていないデータのバイト数を返す。 158 | 159 | 実行例 160 | 161 | ```ruby 162 | bytes = uart1.bytes_to_write() 163 | ``` 164 | 165 | ノート 166 | 167 | - バッファの無いデバイスの場合は、この関数は常に0を返す。 168 | 169 | --- 170 | 171 | ### can_read_line() -> bool 172 | 173 | - 1行のデータを読み込むことができる場合は、true を返す。 174 | 175 | 実行例 176 | 177 | ```ruby 178 | flag = uart1.can_read_line() 179 | ``` 180 | 181 | --- 182 | 183 | ### flush() 184 | 185 | - 送信バッファに溜まったデータの送信完了までブロックする。 186 | 187 | 実行例 188 | 189 | ```ruby 190 | uart1.flush() 191 | ``` 192 | 193 | --- 194 | 195 | ### clear_rx_buffer() 196 | 197 | - 受信バッファをクリアする。 198 | 199 | 実行例 200 | 201 | ```ruby 202 | uart1.clear_rx_buffer() 203 | ``` 204 | 205 | --- 206 | 207 | ### clear_tx_buffer() 208 | 209 | - 送信バッファをクリアする。 210 | 211 | 実行例 212 | 213 | ```ruby 214 | uart1.clear_tx_buffer() 215 | ``` 216 | 217 | --- 218 | 219 | ### send_break( time ) 220 | 221 | - break 信号を送信する。 222 | - time はオプションで、秒で指定する。 223 | 224 | 実行例 225 | 226 | ```ruby 227 | uart1.send_break( 0.1 ) 228 | ``` 229 | 230 | 機種依存 231 | 232 | - ハードウェアによっては、timeは一律（e.g. 12bit）で、変更できない。 233 | --------------------------------------------------------------------------------