From 1309b4aa5b68445dccee8c3b440944e7efdba21d Mon Sep 17 00:00:00 2001 From: Florian Loitsch Date: Fri, 8 Nov 2024 10:10:00 +0100 Subject: [PATCH 1/2] Update Joystick tutorial. --- .../peripherals/drivers/sparkfun_joystick.mdx | 66 ++++++++----------- 1 file changed, 29 insertions(+), 37 deletions(-) diff --git a/docs/peripherals/drivers/sparkfun_joystick.mdx b/docs/peripherals/drivers/sparkfun_joystick.mdx index b36ad436..1613d8e2 100644 --- a/docs/peripherals/drivers/sparkfun_joystick.mdx +++ b/docs/peripherals/drivers/sparkfun_joystick.mdx @@ -26,8 +26,8 @@ import i2c main: bus := i2c.Bus - --sda=gpio.Pin 21 - --scl=gpio.Pin 22 + --sda=gpio.Pin 21 + --scl=gpio.Pin 22 ``` ## Driver skeleton @@ -37,21 +37,24 @@ As all I2C/SPI drivers that work using registers, the driver starts w ``` import serial -class SparkFunJoystick: +class Joystick: static I2C-ADDRESS ::= 0x20 registers_/serial.Registers constructor device/serial.Device: registers_ = device.registers - - on: - - off: ``` The hookup guide has a table of I2C registers available in the custom firmware. At address `0x00` is the slave address assigned to the device (hard-coded to `0x20`). + + +Most drivers turn on their devices in the constructor, and shut them down in a `close` method. +Drivers that can be turned on or off repeatedly should instead have `on` and `off` methods. + + + ## Validate connectivity By reading the `REG-DEFAULT-ADDRESS_` register, we can confirm the connectivity to the device is functional. @@ -61,18 +64,17 @@ By reading the `REG-DEFAULT-ADDRESS_` register, we can confirm the connectivity ``` class SparkFunJoystick: + static I2C-ADDRESS ::= 0x20 + static REG-DEFAULT-ADDRESS_ ::= 0x00 - // ... + constructor device/serial.Device: + registers_ = device.registers - on: reg := registers_.read-u8 REG-DEFAULT-ADDRESS_ if reg != I2C-ADDRESS: throw "INVALID_CHIP" ``` - - - With this added, we can validate the setup: @@ -81,11 +83,9 @@ With this added, we can validate the setup: main: // ... - device := bus.device SparkFunJoystick.I2C-ADDRESS - - joystick := SparkFunJoystick device + device := bus.device Joystick.I2C-ADDRESS - joystick.on + joystick := Joystick device print "SparkFunJoystick" ``` @@ -138,7 +138,7 @@ The last 6 bits of the result are unused, but to keep the code simple we treat t ``` import serial -class SparkFunJoystick: +class Joystick: // ... @@ -153,7 +153,7 @@ class SparkFunJoystick: With that in place, we can now finish the `horizontal` and `vertical` methods: ``` - // Continuing class SparkFunJoystick: + // Continuing class Joystick: static REG-HORIZONTAL-POSITION_ ::= 0x03 // (to 0x04) static REG-VERTICAL-POSITION_ ::= 0x05 // (to 0x06) @@ -169,7 +169,7 @@ With that in place, we can now finish the `horizontal` and `vertical` methods: Lastly, we need to implement the `pressed` method. We're simply going to read out the 1-byte register value and check for `0`, with `0` meaning pressed. ``` - // Continuing class SparkFunJoystick: + // Continuing class Joystick: static REG-BUTTON-POSITION_ ::= 0x07 // ... @@ -185,14 +185,11 @@ Let's try it out: main: // ... - joystick.on while true: print "$joystick.horizontal - $joystick.vertical (pressed: $joystick.pressed)" sleep --ms=250 ``` -This code will run until aborted (Ctrl-C). - As the joystick is moved around, it's possible to get an I2C error if the I2C bus is accidentally short-circuited by the fingers. @@ -201,7 +198,7 @@ As the joystick is moved around, it's possible to get an I2C error if -To improve responsibility, the sensor should be read at a higher frequency. However no printing should be done at higher frequencies to avoid logging data building up. +To improve responsibility, the sensor should be read at a higher frequency. @@ -209,14 +206,14 @@ To improve responsibility, the sensor should be read at a higher frequency. Howe ### The driver -**`driver.toit`** +**`qwiic-joystick.toit`** - + ``` import serial -class SparkFunJoystick: +class Joystick: static I2C-ADDRESS ::= 0x20 static REG-DEFAULT-ADDRESS_::= 0x00 @@ -229,12 +226,9 @@ class SparkFunJoystick: constructor device/serial.Device: registers_ = device.registers - on: reg := registers_.read-u8 REG-DEFAULT-ADDRESS_ if reg != I2C-ADDRESS: throw "INVALID_CHIP" - off: - /** Returns the horizontal value in the range [-1..1]. */ @@ -267,20 +261,18 @@ class SparkFunJoystick: import gpio import i2c -import .driver +import .qwiic-joystick main: bus := i2c.Bus - --sda=gpio.Pin 21 - --scl=gpio.Pin 22 + --sda=gpio.Pin 21 + --scl=gpio.Pin 22 - device := bus.device SparkFunJoystick.I2C-ADDRESS + device := bus.device Joystick.I2C-ADDRESS - joystick := SparkFunJoystick device + joystick := Joystick device - joystick.on while true: - print "$joystick.horizontal - $joystick.vertical " - + "(pressed: $joystick.pressed)" + print "$joystick.horizontal - $joystick.vertical (pressed: $joystick.pressed)" sleep --ms=250 ``` From bbabb86a799acec9be775e1fed49982bc57ae6b1 Mon Sep 17 00:00:00 2001 From: Florian Loitsch Date: Fri, 8 Nov 2024 10:13:22 +0100 Subject: [PATCH 2/2] Fix code-checking. --- docs/peripherals/drivers/sparkfun_joystick.mdx | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/docs/peripherals/drivers/sparkfun_joystick.mdx b/docs/peripherals/drivers/sparkfun_joystick.mdx index 1613d8e2..4632ed09 100644 --- a/docs/peripherals/drivers/sparkfun_joystick.mdx +++ b/docs/peripherals/drivers/sparkfun_joystick.mdx @@ -61,13 +61,15 @@ By reading the `REG-DEFAULT-ADDRESS_` register, we can confirm the connectivity + + ``` class SparkFunJoystick: - static I2C-ADDRESS ::= 0x20 - static REG-DEFAULT-ADDRESS_ ::= 0x00 + // ... + constructor device/serial.Device: registers_ = device.registers