|
9 | 9 | ## Build status |
10 | 10 |
|
11 | 11 | | Component | Build Status | NuGet Package | |
12 | | -|:-|---|---| |
| 12 | +|:---|---|---| |
13 | 13 | | MagicBit | [](https://dev.azure.com/nanoframework/nanoFramework.MagicBit/_build/latest?definitionId=59&repoName=nanoframework%2FnanoFramework.MagicBit&branchName=main) | [](https://www.nuget.org/packages/nanoFramework.MagicBit/) | |
14 | 14 | | MagicBit (preview) | [](https://dev.azure.com/nanoframework/nanoFramework.MagicBit/_build/latest?definitionId=59&repoName=nanoframework%2FnanoFramework.MagicBit&branchName=develop) | [](https://www.nuget.org/packages/nanoFramework.MagicBit/) | |
15 | 15 |
|
16 | 16 | ## Usage |
17 | 17 |
|
18 | | -TBD |
| 18 | +This nuget can be used with the great [MagicBit](https://magicbit.cc/) board. |
| 19 | + |
| 20 | +It does bring support for almost all the sensors and the robot elements. Still, some are not natively in this nuget as they are part of the existing [IoT.Device bindings](https://github.com/nanoframework/nanoFramework.IoT.Device). See the [known limitations](#known-limitations) as well. |
| 21 | + |
| 22 | +You just need to make sure your MagicBit is flashed like this: |
| 23 | + |
| 24 | +```shell |
| 25 | +# Replace the com port number by your COM port |
| 26 | +nanoff --platform esp32 --update --preview --serialport COM3 |
| 27 | +``` |
| 28 | + |
| 29 | +A detailed example is available in the [Test application](Tests/MagicBitTestApp/Program.cs) as well. |
| 30 | + |
| 31 | +### Screen |
| 32 | + |
| 33 | +The only thing you need to do to access the screen is to initialize it: |
| 34 | + |
| 35 | +```csharp |
| 36 | +MagicBit.InitializeScreen(); |
| 37 | +``` |
| 38 | + |
| 39 | +Once you've initialized it, you can access both a `Screen` static class and a `Console` static class. |
| 40 | + |
| 41 | +The `Screen` one brings primitives to write directly on the screen points, select colors as well as writing a text. |
| 42 | + |
| 43 | +For example, you can write a small buffer square of 8x8 at the position 0, 26 with a width of 8 like this: |
| 44 | + |
| 45 | +```csharp |
| 46 | +byte[] _heart = new byte[] { |
| 47 | + 0b0100_0010, |
| 48 | + 0b0110_0110, |
| 49 | + 0b1111_1111, |
| 50 | + 0b1111_1111, |
| 51 | + 0b1111_1111, |
| 52 | + 0b0011_1100, |
| 53 | + 0b0011_1100, |
| 54 | + 0b0001_1000, |
| 55 | + }; |
| 56 | +Screen.DrawBitmap(0, 26, 8, _heart); |
| 57 | +``` |
| 58 | + |
| 59 | +Note that only multiple of 8 are possible for the width, the buffer should be a multiple of the width / 8. Each bit is representing a pixel. This is the way you can display images. |
| 60 | + |
| 61 | +The screen provides as well other primitives, here is a quick example: |
| 62 | + |
| 63 | +```csharp |
| 64 | +// You can use the Screen primitives like this: |
| 65 | +Screen.Clear(); |
| 66 | +Screen.Write(2, 0, "MagicBit", 2); |
| 67 | +Screen.Write(2, 26, "loves .NET", 1, true); |
| 68 | +Screen.Write(2, 40, "nanoFramework", 1, true); |
| 69 | +Screen.Write(2, 50, "Clk right button", 1, false); |
| 70 | +Screen.DrawBitmap(0, 26, 8, _heart); |
| 71 | +Screen.DrawBitmap(Screen.Width - 9, 26, 8, _heart); |
| 72 | +// You should make sure that you call Display |
| 73 | +Screen.Display(); |
| 74 | +``` |
| 75 | + |
| 76 | +And you will get even more thru `Screen.Device`. |
| 77 | + |
| 78 | +The Console class works in a similar way as the classic `System.Console`: |
| 79 | + |
| 80 | +```csharp |
| 81 | +Console.Clear(); |
| 82 | +Console.WriteLine("Motors"); |
| 83 | +Console.CursorTop = 2; |
| 84 | +Console.WriteLine("Motors will run reverse then rotate both direction"); |
| 85 | +``` |
| 86 | + |
| 87 | +> Note: You can change the default font as well, you need to provide it as a property. The Cursor positions are calculated with the width of the font. |
| 88 | +
|
| 89 | +### Buttons |
| 90 | + |
| 91 | +The 2 buttons are exposed. |
| 92 | + |
| 93 | +They are called `ButtonLeft` and `ButtonRight`. You can get access to the events as well. For example: |
| 94 | + |
| 95 | +```csharp |
| 96 | +MagicBit.ButtonLeft.Press += (sender, e) => |
| 97 | +{ |
| 98 | + Console.CursorLeft = 0; |
| 99 | + Console.CursorTop = 0; |
| 100 | + Console.Write($"Left Pressed "); |
| 101 | +}; |
| 102 | + |
| 103 | +// Simple way of getting the button status |
| 104 | +while (!MagicBit.ButtonRight.IsPressed) |
| 105 | +{ |
| 106 | + Thread.Sleep(20); |
| 107 | +} |
| 108 | +``` |
| 109 | + |
| 110 | +Another sample with events: |
| 111 | + |
| 112 | + |
| 113 | +```csharp |
| 114 | +MagicBit.ButtonRight.IsHoldingEnabled = true; |
| 115 | +MagicBit.ButtonRight.Holding += (sender, e) => |
| 116 | +{ |
| 117 | + Console.Write("ButtonRight hold long."); |
| 118 | +}; |
| 119 | +``` |
| 120 | + |
| 121 | +### Motors |
| 122 | + |
| 123 | +The MagicBit has a driver allowing to control 2 DC motors. If you have the robot kit, you'll be able to control them. If you don't have the robot kit, you still can use your own if you plug them on the correct pins. |
| 124 | + |
| 125 | +```csharp |
| 126 | +Console.Clear(); |
| 127 | +Console.WriteLine("Motors"); |
| 128 | +Console.CursorTop = 2; |
| 129 | +Console.WriteLine("Motors will run reverse then rotate both direction"); |
| 130 | +var motor1 = MagicBit.Motor1; |
| 131 | +var motor2 = MagicBit.Motor2; |
| 132 | +motor1.Speed = -0.5; |
| 133 | +motor2.Speed = -0.5; |
| 134 | +Thread.Sleep(2000); |
| 135 | +motor1.Speed = +0.5; |
| 136 | +motor2.Speed = -0.5; |
| 137 | +Thread.Sleep(2000); |
| 138 | +motor1.Speed = -0.5; |
| 139 | +motor2.Speed = +0.5; |
| 140 | +Thread.Sleep(2000); |
| 141 | +motor1.Speed = 0; |
| 142 | +motor2.Speed = 0; |
| 143 | +``` |
| 144 | + |
| 145 | +### Buzzer |
| 146 | + |
| 147 | +It's of course possible to use the buzzer. Here is an example playing tones: |
| 148 | + |
| 149 | +```csharp |
| 150 | +var buzz = MagicBit.Buzzer; |
| 151 | +for (int i = 0; i < 10; i++) |
| 152 | +{ |
| 153 | + buzz.PlayTone(500 + i * 25, 1000); |
| 154 | +} |
| 155 | +``` |
| 156 | + |
| 157 | +### Potentiometer and Luminosity |
| 158 | + |
| 159 | +Those 2 embedded sensors can be directly accessed and used. Here is a complete example reading them, displaying the value on the screen and interrupting them when the left button is pressed: |
| 160 | + |
| 161 | +```csharp |
| 162 | +CancellationTokenSource cancellationTokenSource = new CancellationTokenSource(); |
| 163 | +MagicBit.ButtonLeft.Press += (sender, e) => |
| 164 | +{ |
| 165 | + cancellationTokenSource.Cancel(); |
| 166 | +}; |
| 167 | + |
| 168 | +Console.Clear(); |
| 169 | +Console.WriteLine("Sensors"); |
| 170 | +Console.CursorTop = 2; |
| 171 | +Console.WriteLine("Clk left button to stop"); |
| 172 | + |
| 173 | +while (!cancellationTokenSource.Token.IsCancellationRequested) |
| 174 | +{ |
| 175 | + // Read the potentiometer ratio, from 0.0 to 1.0 |
| 176 | + var ratio = MagicBit.Potentiometer.ReadRatio(); |
| 177 | + // Read the luminosity sensor ratio from 0.0 (full dark) to 1.0 (full light) |
| 178 | + var lumi = MagicBit.Luminosity.ReadRatio(); |
| 179 | + Console.CursorTop = 4; |
| 180 | + Console.CursorLeft = 0; |
| 181 | + Console.WriteLine($"Pot: {ratio * 100:N2}% "); |
| 182 | + Console.CursorTop = 5; |
| 183 | + Console.CursorLeft = 0; |
| 184 | + Console.WriteLine($"lum: {lumi * 100:N2}% "); |
| 185 | + cancellationTokenSource.Token.WaitHandle.WaitOne(200, true); |
| 186 | +} |
| 187 | +``` |
| 188 | + |
| 189 | +### Servo motor |
| 190 | + |
| 191 | +Servo motor can be attached to. So far, you have a direct and easy way on the blue pin. This full sample shows how to change the angle from 0 to 180 degrees, displays the next angle and wait for the left button to be pressed to stop: |
| 192 | + |
| 193 | +```csharp |
| 194 | +CancellationTokenSource cancellationTokenSource = new CancellationTokenSource(); |
| 195 | +MagicBit.ButtonLeft.Press += (sender, e) => |
| 196 | +{ |
| 197 | + cancellationTokenSource.Cancel(); |
| 198 | +}; |
| 199 | + |
| 200 | +Console.Clear(); |
| 201 | +Console.WriteLine("Servo"); |
| 202 | +Console.CursorTop = 2; |
| 203 | +Console.WriteLine("Clk left button to stop"); |
| 204 | + |
| 205 | +// The servo can be different and you can adjust the values as needed |
| 206 | +var servo = MagicBit.GetServoPinBlue(180, 500, 2400); |
| 207 | +// This is needed to start the servo |
| 208 | +servo.Start(); |
| 209 | +int angle = 0; |
| 210 | +while (!cancellationTokenSource.Token.IsCancellationRequested) |
| 211 | +{ |
| 212 | + servo.WriteAngle(angle); |
| 213 | + angle = angle == 0 ? 180 : 0; |
| 214 | + Console.CursorTop = 4; |
| 215 | + Console.CursorLeft = 0; |
| 216 | + Console.WriteLine($"Angle: {angle}deg "); |
| 217 | + cancellationTokenSource.Token.WaitHandle.WaitOne(3000, true); |
| 218 | +} |
| 219 | + |
| 220 | +// Don't forget to stop it at the end. |
| 221 | +servo.Stop(); |
| 222 | +``` |
| 223 | + |
| 224 | +> Note: it is technically possible to use any available pin to plug a servo motor. The board package will make your life easy if you are using the blue pin. Otherwise, you'll have to set up the Servo motor yourself. |
| 225 | +
|
| 226 | +### Leds |
| 227 | + |
| 228 | +The 4 embedded leds are available. |
| 229 | + |
| 230 | +```csharp |
| 231 | +MagicBit.LedBlue.Write(PinValue.High); |
| 232 | +``` |
| 233 | + |
| 234 | +> Important: You **cannot** use them with the motors as they are using the same pins. |
| 235 | +
|
| 236 | +### I2C Device |
| 237 | + |
| 238 | +By default you can get an I2C Device thorough the red pins. You can either use `GetRed` or `GetI2cDevice`. For example if you wan to create an I2C Device with the address 0x42, just do: |
| 239 | + |
| 240 | +```csharp |
| 241 | +var myI2cDevice = MagicBit.GetI2cDevice(0x42); |
| 242 | +``` |
| 243 | + |
| 244 | +### Black left and right pins |
| 245 | + |
| 246 | +You can get a GPIO Pin, so a pin you can use a single output or input from the Black pins directly. Both `GetPinBlackLeft` and `GetPinBlackRight` will give it to you: |
| 247 | + |
| 248 | +```csharp |
| 249 | +// This will create an output mode pint, you can for example attach a led |
| 250 | +var myPin = MagicBit.GetPinBlackLeft(PinMode.Output); |
| 251 | +// This will change the pin to high |
| 252 | +myPin.Write(PinValue.High); |
| 253 | +``` |
| 254 | + |
| 255 | +### Blue pin |
| 256 | + |
| 257 | +The blue pin is setup by default to be used as PWM. When getting it, you'll get a PWM Channel: |
| 258 | + |
| 259 | +```csharp |
| 260 | +var myPwm = MagicBit.GetPinBlue(); |
| 261 | +``` |
| 262 | + |
| 263 | +### Changing default pin behavior |
| 264 | + |
| 265 | +This is a more advance scenario but you can change the function of any pin if you did not use the default function before. For example, you can from the black left pin create a PWM chanel as well: |
| 266 | + |
| 267 | +```csharp |
| 268 | +Configuration.SetPinFunction(32, DeviceFunction.PWM11); |
| 269 | +var myBlackPwm = PwmChannel.CreateFromPin(32); |
| 270 | +``` |
| 271 | + |
| 272 | +Even if the blue pin default behavior is PWM, if you do not ask for it, you can use it in a different way. For example as a simple input: |
| 273 | + |
| 274 | +```csharp |
| 275 | +var myBluePin = MagicBit.GpioController.Open(26, PinMode.Input); |
| 276 | +``` |
| 277 | + |
| 278 | +## Known limitations |
| 279 | + |
| 280 | +There are few sensors that will not work, see the list below, the reasons and possible mitigation: |
| 281 | + |
| 282 | +- DHT sensor is not supported yet on ESP32 .NET managed code. You can use one of the other supported temperature and humidity sensor. [See here](https://github.com/nanoframework/nanoFramework.IoT.Device/tree/develop/devices#thermometers). |
| 283 | +- The HCSR04 which is on the robot is not yet supported as it's using the same pin for emission and reception of the signal. This is work in progress to find a solution. The one sold separately, when used with the red port will perfectly work. |
| 284 | +- The QRT Sensors are not yet supported as a group, this is work in progress. In the mean time, you can read them as analog sensors individually. |
19 | 285 |
|
20 | 286 | ## Feedback and documentation |
21 | 287 |
|
|
0 commit comments