forked from deptofdefense/CPXSimpleSat
-
Notifications
You must be signed in to change notification settings - Fork 0
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
- Loading branch information
Nick Ashworth
committed
Sep 11, 2023
1 parent
33e3282
commit 891e51c
Showing
122 changed files
with
2,286 additions
and
2 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1 @@ | ||
| ## Placeholder location to show final assembly instructions |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,85 @@ | ||
| # Simple Sat Hardware | ||
|
|
||
| ## Ground Station Portion of CPX Simple Sat | ||
|
|
||
| Requirements to build and assembly a ground station portion of the SimpleSat kit are as follows: | ||
|
|
||
| 1. [Adafruit Circuit Playground Express](https://www.adafruit.com/product/3333) | ||
| 2. [Raspberry Pi](https://www.amazon.com/CanaKit-Raspberry-4GB-Basic-Kit/dp/B07TXKY4Z9) | ||
| 3. [Jumper Cables](https://www.adafruit.com/product/1953) or [Alligator clips](https://www.adafruit.com/product/1008) | ||
| 4. (Optional - current GS frame is built for this case) [Aluminum Pi 4 case](https://www.amazon.com/Geekworm-Raspberry-Computer-Aluminum-Compatible/dp/B07VD6LHS1/) | ||
|
|
||
| ## Satellite Portion of CPX Simple Sat | ||
|
|
||
| Requirements to build and assemble a Satellite portion of the SimpleSat kit are as follows: | ||
|
|
||
| 1. [Adafruit Circuit Playground Express](https://www.adafruit.com/product/3333) | ||
| 2. [Adafruit CRICKIT for Circuit Playground Express](https://www.adafruit.com/product/3093) | ||
| 3. [Power Supply for CRICKIT](https://www.adafruit.com/product/276) | ||
| 4. STL files 3D printed to the quantity specified below. | ||
| 5. Nuts and bolts outlined below. | ||
|
|
||
| ## Simple Sat Enclosure | ||
|
|
||
| ### STL Files | ||
|
|
||
| Print the .stl files in the following quantity: | ||
|
|
||
| 1. sat_upper_half - 1 | ||
| 2. sat_lower_half - 1 | ||
| 3. sat_solar_panel_arm - 2 | ||
| 4. sat_solar_panel - 2 | ||
| 5. sat_solar_panel_gear_18 - 2 | ||
| 6. sat_radar_dish_arm - 2 | ||
| 7. sat_radar_dish - 2 | ||
|
|
||
| ### Hardware Requirements | ||
|
|
||
| | Item | Quantity | | ||
| | ---- | ----- | | ||
| | M2.5x10 Bolt | 8 | | ||
| | M2.5 Nut | 8 | | ||
| | M2.5x20 Bolt | 4 | | ||
|
|
||
| Alternatively, it may be cheaper and easier to simply purchase an assortment of M2.5 nuts and bolts. | ||
|
|
||
| [Example Kit](https://www.amazon.com/HVAZI-Metric-304-tornillos-inoxidable/dp/B07F14J7X8/ref=sr_1_21?dchild=1&keywords=hvazi+m2.5+304+button+head&qid=1591969674&sr=8-21) | ||
|
|
||
|
|
||
| In addition, the screws that came with the Micro Servos are also used to affix gears to them and to secure the motors in place. | ||
|
|
||
| ## Assembly Instructions | ||
|
|
||
| ### Servo Orientation | ||
|
|
||
| The following diagram depicts the intended servo orientation when fully assembled. | ||
|
|
||
| <pre> | ||
| ------- | ||
| / \ | ||
| / \ | ||
| | Servo #4 | | ||
| | | | ||
| \ / | ||
| \ / | ||
| ------- | ||
| || | ||
| || | ||
| |---------------| | ||
| |---------------------\ | PWR | /---------------------| | ||
| | \--| |--/ | | ||
| | Servo #1 | | Servo #2 | | ||
| | /--| |--\ | | ||
| |---------------------/ | | \---------------------| | ||
| |---------------| | ||
| || | ||
| || | ||
| ------- | ||
| / \ | ||
| / \ | ||
| | Servo #3 | | ||
| | | | ||
| \ / | ||
| \ / | ||
| ------- | ||
| </pre> |
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,2 +1,36 @@ | ||
| # CPXSimpleSat | ||
| Repo for DEFCON28 CPXSimpleSat | ||
| # CPX Simple Sat | ||
|
|
||
| Created as a part of the [Aerospace Village](https://aerospacevillage.org/) for DEFCON28 (Rest in Safe Mode), CPX Simple Sat attempts to teach the basics of satellite exploitation with a ground station in an easily approachable and jargon free manner. | ||
|
|
||
| |  | | ||
| | :---: | | ||
| | How the setup looked like on our side | | ||
|
|
||
| ## Background | ||
|
|
||
| Satellite hacking is one of those fields where all the best stories are kept behind closed doors. Like the rest of Aerospace, the field suffers from a large amount of jargon that can make it difficult for the casual passerby to understand and follow. Add to that the lack of thorough public documentation when events do happen, and it's easy to see why there are problems. | ||
|
|
||
| In CPX Simple Sat we attempt to teach you some of the basic dangers and risks of satellite exploitation by creating an abstract version of a real world event. In 2008, hackers used a ground station to communicate to and attempt to gain access to the Terra satellite (launched in 1999). In the real world this is where the story ends, the hackers attempted to communicate with the satellite but didn't issue any commands, and the satellite itself was fine and is still working today. But while the real life event may not have been that exciting, the concept this event represents poses an interesting challenge. | ||
|
|
||
| ## The Game | ||
|
|
||
| In CPX Simple Sat, you the player have come into possession of a SpaceDotCom ground station, giving you the perfect chance to attack SpaceDotCom's CPX Simple Sat. Why do you want to attack this random satellite you ask? Maybe you got tired of all of Otter MiSpace's random otter facts (Did you know there are 13 species of Otters?), maybe he hired you to do this, or maybe you figured what else would you do when you wake up with a ground station in your home. We just make the game, you can RP it however you like. No one is here to judge. | ||
|
|
||
| Either way, you will be using a [Circuit Playground Express](https://www.adafruit.com/product/3333) (CPX) and [Raspberry Pi](https://www.raspberrypi.org/) that acts as the ground station you now control. Due to COVID-19, you will be interacting with your ground station through a twitch chat bot. To send a command to the chatbot, the message must start with "!", and all parameters are separated with a space. For example, to log into the system, the twitch user would type "!cmd login `username` `password`". Because there will be multiple people playing the game at once, we implemented a simple user management system by requiring users to type "!join" to get added to the user list and start playing the game. Once on the list, each user will get one minute to complete their turn before it moves on to the next user in the list. Your individual progress is saved and kept isolated from other users, so don't worry that you can't finish the game in one round. | ||
|
|
||
| The satellite you will be interacting with is made out of a [Circuit Playground Express](https://www.adafruit.com/product/3333) and [CRICKIT](https://www.adafruit.com/product/3093). It talks to the ground station via the Inferred receiver and transmitter on each CPX board. Due to this, sometimes a message may not be decoded properly. If you think the state of the satellite is incorrect, then type "!reset" on your turn to resync it to your current state in the game. | ||
|
|
||
| Using the game ICD, your goal in the game is to gain as much control of the satellite as you can by outwitting both its onboard systems and the remote ground station controlling it. | ||
|
|
||
| ### Game Documents | ||
|
|
||
| - [Game ICD](./SimpleSat_ICD.pdf) | ||
| - [Bonus Notes](./BONUS-cpx-sat-notes.pdf) | ||
|
|
||
| ## DIY | ||
|
|
||
| If you want to create your own version of CPX Simple Sat, the STL files, build instructions, and source code can be found here: | ||
|
|
||
| - [STL files and Assembly instructions](./3dFiles/README.md) | ||
| - [Build Guide](./buildGuide.md) | ||
| - [Source Code](./code/README.md) |
Binary file not shown.
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,124 @@ | ||
| # CPX SimpleSat Assembly Guide | ||
|
|
||
| ## Parts needed | ||
|
|
||
| ### 3D Printed pieces | ||
|
|
||
| Essential parts: | ||
|
|
||
| * 2 Solar Panel Arms | ||
| * 2 Solar Panels | ||
| * 2 Antenna Dishes | ||
| * 2 Antenna Arms | ||
| * 2 Servo Gears | ||
| * 1 Satellite Upper body | ||
| * 1 Satellite Lower body | ||
|
|
||
| Nonessential parts, but needed if doing smoker modification: | ||
|
|
||
| * 1 Smoker upper shell | ||
| * 1 smoker lower shell | ||
|
|
||
| ### Commerical Parts | ||
|
|
||
| Essential parts: | ||
|
|
||
| * [Screw kit](https://www.amazon.com/DYWISHKEY-Pieces-Stainless-Socket-Washers/dp/B082XPZV1V) | ||
| * [Micro Servo](https://www.amazon.com/Micro-Servos-Helicopter-Airplane-Controls/dp/B07MLR1498/) | ||
| * [Adafruit CRICKIT](https://www.adafruit.com/product/3093) | ||
| * 2x [Circuit Playground Express](https://www.adafruit.com/product/3333) | ||
| * Raspberry Pi | ||
|
|
||
| For Smoker modification: | ||
|
|
||
| * [Diminus mini air pump](https://www.amazon.com/gp/product/B06Y2CXZ67/) | ||
| * 1/4" silicone tubbing | ||
| * 2 KangerTech T2 esig | ||
|
|
||
| ## Build instructions | ||
|
|
||
| ### Satellite | ||
|
|
||
| The satellite part of CPX Simple Sat is the most complicated part of the build, so we'll tackle that first. Note the satellite will function with or without the smoke kit, so it's your choice if you want to add it. | ||
|
|
||
| | Build Steps | | ||
| | --- | | ||
| |  | | ||
| | Here are all the parts we'll need to build the satellite. Note for this build we painted the central part of the satellite gold to mimic the look of the multi-layer insulation on most satellite. | | ||
| |  | | ||
| | Here are the holes drilled to allow the smoker to produce smoke from underneath the CRICKIT board. This step isn't required, but it does make it look cool | | ||
| |  | | ||
| | For the first part of the build, we'll put together the antenna controller arms. Make sure all the micro servos spin smoothly before assembly| | ||
| |  | | ||
| | Find the side of the arm that has divots. this will be the top of the arm | | ||
| |  | | ||
| | To start, run the servo cable through the cavity within the arm | | ||
| |  | | ||
| | After sliding the micro servo into the gap, lock it in place by screwing it in using one of the small screws that came with the micro servo | | ||
| |  | | ||
| | Now snap on the the antenna dish. The hole at the bottom of the dish should be a snug fit for the white gear on the servo. If it feels loose, use another screw from the micro servo kit to make it a tighter fit | | ||
| |  | | ||
| | After making both control antenna arms, lets move onto the solar panels. First find the solar gears and push them onto the two remaining micro servos, just like we did with the antenna dish | | ||
| |  | | ||
| | After doing this twice, you've now finished assembling your servo components | | ||
| |  | | ||
| |  | | ||
| | This step is optional but if you drilled holes for the smoker, now would be a good time to attach part of the tubing to the front panel. The more flush the tubing is to the hole, the more even the spread of smoke. I like to use hot glue to hold this end of the tubing in place while we assemble everything else | | ||
| |  | | ||
| |  | | ||
| | Now would also be a good time to measure out how much tubing you will need to route through the satellite. Give your self a little extra to play safe, and then cut off the extra tubing | | ||
| |  | | ||
| | Now route the servo cable from the antenna arms through the back of the front panel | | ||
| |  | | ||
| | Using 10mm screws, attach the antenna arms to the front panel. Make sure everything is facing the right direction | | ||
| |  | | ||
| |  | | ||
| | Using a nut, lock the arm in place on the other side. You can also use spacers between the arm and panel, as well as the nut and panel to stop the screw from digging into the pla if you tighten to much | | ||
| |  | | ||
| | repeat with the second arm | | ||
| |  | | ||
| | Now we will install the micro servos that will control the solar panels. | | ||
| |  | | ||
| |  | | ||
| |  | | ||
| | I like to use hot glue on the back of the servo to help hold it in place. A small drop where the gap that the cable exits from is enough | | ||
| |  | | ||
| | Now its time to build the smoker backpack. Note the side with the deeper opening for the pump is the bottom of the backpack | | ||
| |  | | ||
| |  | | ||
| | Using four 6mm screws, attach the backpack to the rear panel | | ||
| |  | | ||
| |  | | ||
| | Using four 16mm screws attach the cover of the backpack. Note the two pieces are not supposed to go flush together. There should always be a gap between them | | ||
| |  | | ||
| | Now its time to attach the cricket board | | ||
| |  | | ||
| | Before you attach the crickit to the front panel, you may want to do some cable management to clean things up. Also note that the two solar panel servos should go in servo slots 1 and 2, while the two antenna servos should go in slots 3 and 4 | | ||
| |  | | ||
| |  | | ||
| | Depending on how much clearance you want for the smoke use either four 25mm or 20mm screws to attach the crickit to the satellite. Use nuts to both keep the crickit steady and lock in its offset from the surface of the satellite | | ||
| |  | | ||
| |  | | ||
| | We're almost there. Go ahead and slide the panels into the notches on the arms to complete their build. Then you will want to place them on the bottom panel and line it up with the top panel. Make sure to route the smoker tubing through the back panel if you are using that design. Finally screw everything together with four 25mm screws. | ||
| |  | | ||
| |  | | ||
| | The next steps are for getting the smoker integrated with the satellite. First tape the mosfet and extra cables to the back of the satellite to keep it out of the way. | | ||
| |  | | ||
| | Attach the air pump cables to DC motor 1 on the crickit | | ||
| |  | | ||
| | Attach the smoker cables to the 5V and ground lines of the neopixel terminal. We use this terminal because most of the cricket lines are only designed for 3V and limited current. The smoker is a fairly demanding heating element, so by using the neopixel terminal we can get the voltage and current we need without hampering the rest of the board | | ||
| |  | | ||
| | Plug a pin into the signal 1 line of the I/O connector. I prefer to just use a male jumper cable and then solder it to the signal cable on the smoker | | ||
| |  | | ||
| |  | | ||
| | Here we solder and heat shrink the jumper cable | | ||
| |  | | ||
| | And now you test it out. If all went well you will have a working CPX Simple Sat. Congratulations! | | ||
| | Note if you want to make the satellite look better in the dark, cover up the green power leds with tape | | ||
|
|
||
| ### Ground Station | ||
|
|
||
| | Ground station setup | | ||
| | :---: | | ||
| |  | | ||
| | Building the ground station part is straightforward. The two pieces slot together, and if using a case like [this](https://www.amazon.com/Geekworm-Raspberry-Computer-Aluminum-Compatible/dp/B07VD6LHS1) it should fit snugly on the pi. Once there, either screw/hot glue/tape the cpx to the board and connect the 3.3V, GND, TX, and RX to the pi or whatever device the chatbot is running on. |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,113 @@ | ||
| # CircuitPlayground Software | ||
|
|
||
| ## General Setup | ||
|
|
||
| Follow the [Adafruit tutorial](https://learn.adafruit.com/adafruit-circuit-playground-express) to get the board initially setup. Make sure to update the bootloader and download any drivers that are needed. | ||
|
|
||
| Quick Reference: | ||
|
|
||
| * [Updating the bootloader](https://learn.adafruit.com/adafruit-circuit-playground-express/updating-the-bootloader) | ||
| * Update the CPX firmware: | ||
| * For the ground station (stand alone CPX) : [Latest Circuit Playground Express](https://circuitpython.org/board/circuitplayground_express/) | ||
| * For the Satellite (CPX+Cricket) : [latest CPX + cricket](https://circuitpython.org/board/circuitplayground_express_crickit/) | ||
| * [CircuitPython Libraries](https://circuitpython.org/libraries) | ||
|
|
||
| After setup, copy over the contents of either the [satellite](./cp-sat) or [ground](./cp-gs) onto the board. To use the chatbot, run the [twitch code](./twitch/README.md) on a device connected to the ground station CPX over serial | ||
|
|
||
| ## Challenges | ||
|
|
||
| ### LEDs | ||
|
|
||
| | LED | Challenge | Notes | | ||
| | --- | --- | --- | | ||
| | 0 | Maintenance Password | Turns yellow if they enter the normal password first | | ||
| | 1 | Secondary Control Antenna | Swings servo representing control antenna | | ||
| | 2 | Primary Control Antenna | Flashes the completed color before turning back to normal if they haven’t finished the secondary control antenna | | ||
| | 3 | Disable battery charging (Solar Panel 1) | Changes to the user position for a second before switching back if Primary Control antenna hasn’t been changed | | ||
| | 4 | Disable battery charging (Solar Panel 2) | Changes to the user position for a second before switching back if Primary Control antenna hasn’t been changed | | ||
| | 5 | Disable temperature controller | Will flash as a success for a second, before resetting if the primary control antenna hasn’t been changed | | ||
| | 6 | Override emergency failsafe | Lets them override the final settings | | ||
| | 7 | Update Orbit Parameters | Will be rejected while the flight systems are working, these get disabled by the failsafe override | | ||
| | 8 | Launch thrusters | Either cause the sat to spin or smoke | | ||
| | 9 | Free Play | User discovers one of the two free play command | ||
|
|
||
| ### State Map | ||
|
|
||
| * 0: Default/Game Start | ||
| * 1: User has entered normal password | ||
| * Return health status | ||
| * 2: User has entered maint password | ||
| * 3: Adjust secondary antenna | ||
| * Set | ||
| * Status | ||
| * Calc | ||
| * 4: Adjust primary antenna | ||
| * Set | ||
| * Status | ||
| * Calc | ||
| * 5: Disable Solar Panel 1 but not 2 | ||
| * Enable | ||
| * disable | ||
| * 6: Disable Solar Panel 2 but not 1 | ||
| * Enable | ||
| * disable | ||
| * 7: Disable both Solar Panels | ||
| * 8: Disable Temperature Control | ||
| * Set | ||
| * status | ||
| * 9: Override failsafe (orbit) | ||
| * mode | ||
| * 10: Update orbit | ||
| * Status | ||
| * set | ||
| * 11: Launch thrusters | ||
| * ignite | ||
| * 12: Free Play mode | ||
| * Led | ||
| * servo | ||
|
|
||
| #### CheatSheet | ||
|
|
||
| * !cmd login twitch_handle password | ||
| * !cmd login SpaceMaint 5p4c3d07c0m | ||
| * !cmd ant calc x y z | ||
| * !cmd ant set sec xyz | ||
| * !cmd ant set pri xyz | ||
| * !cmd bat disable pri | ||
| * !cmd bat disable sec | ||
| * !cmd temp status | ||
| * !cmd temp set -20 100 | ||
| * !cmd orbit mode man | ||
| * !cmd orbit set inclination 2 | ||
| * !cmd orbit ignite | ||
| * !cmd servo 1 45 | ||
| * !cmd led 1 175 255 50 | ||
|
|
||
| ## Troubleshooting Notes | ||
|
|
||
| Very frustrating to be developing quickly with read/writes/executes to | ||
| a CircuitPlayground Express only for soemthing to hangup and the process | ||
| fail with an failed unmount or data corruption. | ||
|
|
||
| ### Backup code | ||
|
|
||
| Back up `code.py` somewhere other than the Circuit Playground Express. | ||
|
|
||
| ### Input/Output Errors | ||
|
|
||
| This happened a few times, here's what worked to reset the device. | ||
|
|
||
| ```bash | ||
| # observe how the circuit mounted | ||
| dmesg | ||
|
|
||
| # if mounted with errors | ||
| umount /dev/sda1 # verify the correct device first (i.e. sda1) | ||
|
|
||
| sudo fsck /dev/sda1 | ||
| ``` | ||
|
|
||
| ### Clean Power Supply | ||
|
|
||
| Haven't done the math yet, but from observation the pi0 GPIOs being the exclusive power supply of the CPE, led diming was observed when sending commands | ||
| to change values along with intermittent soft reboots. It is therefore recommended that power to the CPE be provided from other than the pi0. |
Oops, something went wrong.