Skip to content

Commit 2026074

Browse files
echo-laliaecho-lalia
authored
Wikiupdate (#177)
* Clarify app format * Add internet connection wiki page * Expand internet examples
1 parent 8f3e5cd commit 2026074

File tree

3 files changed

+135
-24
lines changed

3 files changed

+135
-24
lines changed

‎wiki/App-Format.md‎

Lines changed: 33 additions & 18 deletions
Original file line numberDiff line numberDiff line change
@@ -1,35 +1,43 @@
11
## Format of MicroHydra apps:
22
MicroHydra apps can be placed in the apps folder on the device's main storage, or in the apps folder on an SD Card (The launcher will create these folders automatically if they don't exist.)
33

4+
A MicroHydra app is basically just a MicroPython [module](https://docs.python.org/3/tutorial/modules.html) without an [import-guard](https://docs.python.org/3/library/__main__.html#name-main).
5+
Apps can also (*optionally*) import and use MicroHydra modules, in order to simplify app development, or to integrate with core MicroHydra features.
6+
47
<br/>
58

6-
All that is needed to make a valid MicroHydra app, is a .py file *(or a compiled .mpy file)* with some MicroPython code placed in the apps folder.
7-
The file name becomes the app name, and it will be imported by main.py when launched using MicroHydra.
8-
This is the simplest form of a MH app, and several apps in the [apps](https://github.com/echo-lalia/MicroHydra-Apps) repo are designed like this.
9+
### Basic App
10+
11+
All that is needed to make a valid MicroHydra app, is a .py file *(or a compiled .mpy file)* with some MicroPython code, placed in the apps folder.
12+
The file name becomes the app name, and it will be imported by `main.py` when launched using MicroHydra.
13+
This is the simplest form of an MH app, and several apps in the [community apps repo](https://github.com/echo-lalia/MicroHydra-Apps) are designed like this.
914

1015
<br/>
1116

12-
Apps that are more complex can be made as a folder, instead. This can allow you to bundle in dependencies, or split the code up into multiple files for better readability. A MicroHydra app as a folder works essentially the same as a normal Python module, where a file named `__init__.py` inside that folder will be imported at launch.
17+
### More Complex App
1318

14-
If you decide to format your app as a folder, you'll probably want to use 'relative' imports to access the other modules in the app folder.
15-
However, relative imports don't work when running from the editor. My usual solution to this is to use both relative, and absolute imports, in a try/except statement. Here's what that looks like:
19+
Apps that are more complex can be made as a folder, instead of a single file.
20+
This can allow you to bundle in dependencies, or split the code up into multiple files for better organization.
1621

17-
``` Python
18-
try:
19-
# relative import for launching the app normally
20-
from . import myothermodule
21-
except:
22-
# absolute path for launching from the editor (which causes the above to fail)
23-
from apps.myappname import myothermodule
24-
```
22+
Inside your app's folder, you'll need an `__init__.py` file.
23+
When your app is imported, `__init__.py` is the specific file that MicroPython will actually be importing on launch. From there, you can import any other modules you'd like.
24+
*(This behavior is mostly identical to CPython)*
25+
26+
> **Note on relative imports**:
27+
> *If you decide to format your app as a folder, you'll probably want to use 'relative' imports to access the other modules in the app folder.
28+
> However, relative imports don't work when running directly from the editor. My usual solution to this is to just use both relative, and absolute imports, in a `try...except` statement. Here's what that looks like:*
29+
> ``` Python
30+
> try:
31+
> # relative import for launching the app normally
32+
> from . import myothermodule
33+
> except ImportError:
34+
> # absolute path for launching from the editor (which causes the above to fail)
35+
> from apps.myappname import myothermodule
36+
> ```
2537
2638
<br/><br/><br/>
2739
2840
## App Icons:
29-
> Quick note:
30-
> *The previous version of MicroHydra used a bizzare method of packing vectorized/polygonal icon definitions into a short string, which would be unpacked and executed by the launcher. This strategy was chosen for memory efficiency, but it felt awkward and is not used anymore. The script `polygon_to_raw_bmp.py` from the `tools/icons` folder has been written to convert these old polygon defs if needed.*
31-
32-
<br/>
3341
3442
**To put it simply:**
3543
MicroHydra app icons are 32x32, 1bit, raw bitmaps (not bmp files) named `icon.raw`. Your app icon should be placed in the main directory of your app, alongside the `__init__.py` file.
@@ -65,3 +73,10 @@ The image can be any format supported by Pillow, and you can also specify other
6573
python3 path/to/image_to_icon.py --output_file path/to/output_filename.raw --invert --preview path/to/your_image_file.png
6674
```
6775
*(use --help to see all options)*
76+
77+
<br/>
78+
79+
> Quick note on old MH icons:
80+
> *The previous version of MicroHydra used a bizzare method of packing vectorized/polygonal icon definitions into a short string, which would be unpacked and executed by the launcher. This strategy was chosen for memory efficiency, but it felt awkward and is not used anymore. The script `polygon_to_raw_bmp.py` from the `tools/icons` folder has been written to convert these old polygon defs if needed.*
81+
82+
<br/>

‎wiki/Home.md‎

Lines changed: 8 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -8,17 +8,15 @@
88
MicroHydra uses a few different ideas in order to output code for multiple devices. You can learn about this [here](https://github.com/echo-lalia/MicroHydra/wiki/multi-platform).
99
You can also learn more about the supported devices [here](https://github.com/echo-lalia/MicroHydra/wiki/Supported-Devices).
1010

11-
## Making Apps
12-
For a basic overview of how MicroHydra apps work, see the [App Format](https://github.com/echo-lalia/MicroHydra/wiki/App-Format) section.
13-
1411
<br/>
1512

13+
## Making Apps
14+
For a basic overview of how MicroHydra apps work, see the [App Format](https://github.com/echo-lalia/MicroHydra/wiki/App-Format) section.
1615

17-
## Lib
1816

19-
MicroHydra includes a built-in library, intended to help you easily make apps. Click on a module below to learn more about it.
17+
### Lib:
2018

21-
----
19+
MicroHydra includes a built-in library, intended to help you easily make apps, and integrate with core MicroHydra functionality. Click on a module below to learn more about it.
2220

2321

2422
*MicroHydra*
@@ -53,3 +51,7 @@ MicroHydra includes a built-in library, intended to help you easily make apps. C
5351
│ &nbsp; &nbsp; &nbsp; └── zipextractor
5452
│
5553
└── main
54+
55+
### Other Guides:
56+
- Connecting to the internet
57+

‎wiki/Internet.md‎

Lines changed: 94 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,94 @@
1+
## Connecting to the internet
2+
3+
MicroPython's built-in [`network`](https://docs.micropython.org/en/latest/library/network.WLAN.html#network.WLAN) module makes it easy to connect to the internet on an ESP32 device.
4+
You can also use MicroHydra's `hydra.config` module to easily access the user-set wifi configuration.
5+
6+
Here's a really simple script that connects to WiFi using these:
7+
8+
```Py
9+
import network
10+
from lib.hydra.config import Config
11+
12+
# Create the object for network control
13+
nic = network.WLAN(network.STA_IF)
14+
# Get the MicroHydra config
15+
config = Config()
16+
17+
# Turn on the WiFi
18+
if not nic.active():
19+
nic.active(True)
20+
21+
# Connect to the user-set wifi network
22+
if not nic.isconnected():
23+
nic.connect(
24+
config['wifi_ssid'],
25+
config['wifi_pass'],
26+
)
27+
```
28+
29+
The `nic.connect` command doesn't block while waiting for a connection. So, your script will need to wait until the connection is made.
30+
There can also be some unpredictable errors raised when calling the connection method.
31+
32+
Here's an example connection function that tries to handle these potential obsticals *(similar to the function used in `getapps.py`)*:
33+
```Py
34+
import time
35+
import network
36+
from lib.hydra.config import Config
37+
38+
39+
nic = network.WLAN(network.STA_IF)
40+
config = Config()
41+
42+
43+
def connect_wifi():
44+
"""Connect to the configured WiFi network."""
45+
print("Enabling wifi...")
46+
47+
if not nic.active():
48+
nic.active(True)
49+
50+
if not nic.isconnected():
51+
# tell wifi to connect (with FORCE)
52+
while True:
53+
try: # keep trying until connect command works
54+
nic.connect(config['wifi_ssid'], config['wifi_pass'])
55+
break
56+
except OSError as e:
57+
print(f"Error: {e}")
58+
time.sleep_ms(500)
59+
60+
# now wait until connected
61+
attempts = 0
62+
while not nic.isconnected():
63+
print(f"connecting... {attempts}")
64+
time.sleep_ms(500)
65+
attempts += 1
66+
67+
print("Connected!")
68+
69+
connect_wifi()
70+
```
71+
72+
73+
74+
## Getting Data From the Internet
75+
76+
MicroPython provides a lower-level [`socket`](https://docs.micropython.org/en/latest/library/socket.html#module-socket) module, but the easiest way to make internet requests in most cases is to use the other built-in [`requests`](https://github.com/micropython/micropython-lib/tree/e4cf09527bce7569f5db742cf6ae9db68d50c6a9/python-ecosys/requests) module.
77+
78+
Here's a super simple example that fetches a random cat fact from meowfacts.herokuapp.com:
79+
80+
81+
```Py
82+
import json
83+
import requests
84+
85+
# Make a request to meowfacts
86+
response = requests.get("https://meowfacts.herokuapp.com/")
87+
# Verify that the request worked
88+
if response.status_code != 200:
89+
raise ValueError(f"Server returned {response.status_code}.\n{response.reason}")
90+
91+
# Decode the returned JSON data, and extract the random fact
92+
fact = json.loads(response.content)['data'][0]
93+
print(fact)
94+
```

0 commit comments

Comments
 (0)